underwrit 0.3.0__py3-none-any.whl

underwrit/evidence.py

@@ -0,0 +1,590 @@
+"""Build an evidence pack: what happened, with proof it has not been altered since.
+
+A pack is a directory. It carries the audit entries for one subject with their chain links intact, a
+manifest of SHA-256 digests for every file, and `verify.py` — which needs no account, no network and
+no trust in whoever produced the pack.
+
+Version 2 adds a signed checkpoint (the whole log's size and Merkle root, signed by the data
+plane's Ed25519 log key), an inclusion proof per entry against that root, and an Ed25519 signature
+over the manifest. What each adds, precisely:
+
+- **Inclusion proofs** show that every entry present sits at its stated position in a tree of the
+  stated size. An entry moved, or a position forged, fails its proof even when its own chain hash
+  still matches its contents.
+- **The checkpoint signature** shows the tree was the data plane's, not the bundle-maker's.
+- **The manifest signature** shows the bundle was assembled by the holder of the log key.
+
+What none of this proves is completeness of a *subset*, or origin to somebody who has only the
+bundle's copy of the public key. Completeness needs a witness holding the same checkpoint; origin
+needs the key obtained out of band, which is why `verify.py` shows the key id and accepts a pinned
+one. Every pack says this in its own README and the verifier says it again.
+
+Three properties the format has committed to since version 1, each of which cost something to learn:
+
+**A verifier that overstates itself is worse than none.** **"No entries" is its own state.**
+**A subset is verified per-entry, never walked from genesis.** See §1 and §3 of the specification.
+
+This module never queries anything but the chain tables. The tree over the chain is computed in
+`checkpoint.py` and handed in; `test_gate.py` asserts that at source level.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import os
+import time
+from pathlib import Path
+
+from . import chain
+from .subject import Subject
+
+FORMAT_VERSION = 2
+
+
+def signing_key() -> str:
+    """The version-1 HMAC secret, if an operator still sets one."""
+    return os.environ.get("EVIDENCE_SIGNING_KEY", "").strip()
+
+
+def canonical(payload) -> bytes:
+    return json.dumps(payload, sort_keys=True, separators=(",", ":")).encode("utf-8")
+
+
+def _digest(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def entries_for(conn, subject: Subject) -> list[dict]:
+    """Every audit entry naming this subject, with its chain links kept verbatim.
+
+    `prevHash` and `hash` are carried unchanged because they are the whole point: an entry without
+    them is a line of text somebody typed.
+    """
+    keys = set(subject.keys())
+    entries: list[dict] = []
+
+    rows = list(conn.execute("SELECT * FROM audit_log ORDER BY seq ASC"))
+    try:
+        # A subject older than the last seal has its entries in the archive. A pack that searched
+        # only the live log would report "no entries" for exactly the changes far enough in the past
+        # to be under audit — which is when somebody asks.
+        rows = list(conn.execute("SELECT * FROM audit_log_archive ORDER BY seq ASC")) + rows
+    except Exception:
+        pass  # Archive absent on a database that has never sealed.
+
+    for row in rows:
+        raw = row["detail"] or "{}"
+        try:
+            detail = json.loads(raw) if isinstance(raw, str) else (raw or {})
+        except ValueError:
+            detail = {}
+        target = row["target"] or ""
+        named = target in keys or any(
+            isinstance(v, str) and v in keys
+            for k, v in (detail.items() if isinstance(detail, dict) else [])
+            if k in ("runId", "subjectId", "sessionId", "requestId")
+        )
+        if not named:
+            continue
+        entries.append({
+            "seq": row["seq"], "at": row["at"], "actor": row["actor"], "actorId": row["actor_id"],
+            "action": row["action"], "environment": row["environment"], "target": target,
+            "outcome": row["outcome"], "reason": row["reason"], "detail": detail,
+            "sourceIp": row["source_ip"], "prevHash": row["prev_hash"], "hash": row["hash"],
+        })
+    return entries
+
+
+_entries_for = entries_for  # the name older callers used
+
+
+def _continuity(entries: list[dict]) -> dict:
+    """Whether the entries are consecutive in the source log, said plainly."""
+    if not entries:
+        return {"consecutive": None, "gaps": [], "note": "No entries to assess."}
+    seqs = [e["seq"] for e in entries]
+    gaps = [(a, b) for a, b in zip(seqs, seqs[1:]) if b != a + 1]
+    return {
+        "consecutive": not gaps,
+        "gaps": [{"after": a, "before": b, "missing": b - a - 1} for a, b in gaps],
+        "note": (
+            "Gaps are expected and are not evidence of tampering: this subject's entries are "
+            "interleaved with every other actor's in one shared log. A gap means other entries sit "
+            "between these, not that any are missing."
+        ),
+    }
+
+
+def build(conn, subject: Subject, *, tree: dict | None = None, entries: list[dict] | None = None) -> dict:
+    """Assemble a pack for `subject`. Never returns None — an unknown subject is an empty record.
+
+    `tree`, when given, is the checkpoint view from `bundle.tree_for`: size, root, signed note, key,
+    and an inclusion proof per sequence number. Each entry then carries `leafIndex` and
+    `inclusionProof`; an entry with no place in the live tree (sealed into the archive) carries
+    `null` for both, and the pack says so rather than omitting the fields.
+    """
+    entries = entries_for(conn, subject) if entries is None else entries
+
+    if entries:
+        segment = chain.verify_segment([
+            {"seq": e["seq"], "at": e["at"], "actor": e["actor"], "actor_id": e["actorId"],
+             "action": e["action"], "environment": e["environment"], "target": e["target"],
+             "outcome": e["outcome"], "reason": e["reason"],
+             "detail": json.dumps(e["detail"], sort_keys=True),
+             "source_ip": e["sourceIp"], "prev_hash": e["prevHash"], "hash": e["hash"]}
+            for e in entries
+        ])
+        segment["status"] = "verified" if segment["ok"] else "broken"
+    else:
+        segment = {
+            "status": "no-entries", "ok": None, "checked": 0, "brokenAt": None,
+            "detail": (
+                "No audit entry names this subject. That is not a clean verification: there is "
+                "nothing here to verify."
+            ),
+        }
+
+    merkle_section = None
+    if tree:
+        proofs = tree.get("proofs") or {}
+        for e in entries:
+            p = proofs.get(e["seq"])
+            e["leafIndex"] = p["leafIndex"] if p else None
+            e["inclusionProof"] = p["proof"] if p else None
+        merkle_section = {
+            "size": tree["size"], "root": tree["root"], "keyId": tree["keyId"],
+            "key": tree.get("key"), "issuedAt": tree.get("issuedAt"),
+            "witnessed": tree.get("witnessed"),
+            # External clocks over the checkpoint body (token bytes ship as files, not here).
+            "timestamps": [{k: v for k, v in t.items() if k != "token"} for t in (tree.get("timestamps") or [])],
+            "proven": sum(1 for e in entries if e.get("inclusionProof") is not None),
+            "unplaced": sum(1 for e in entries if e.get("inclusionProof") is None),
+            "note": (
+                "Each proof shows the entry sits at its stated leaf index in a tree of the stated "
+                "size whose root the checkpoint signs. `unplaced` entries were sealed into the "
+                "archive before this tree and are verified by chain hash only."
+            ),
+        }
+
+    pack = {
+        "format": FORMAT_VERSION,
+        "generatedAt": time.time(),
+        "subject": {"id": subject.id, "kind": subject.kind, **subject.descriptor},
+        "auditEntries": entries,
+        "auditChain": {
+            "segment": segment,
+            # The whole-log verdict too. A segment can be internally consistent while the log it came
+            # from was altered elsewhere, and a pack reporting only the former would be reassuring
+            # about the wrong thing.
+            "wholeLog": chain.verify_chain(conn),
+            "segmentEntries": len(entries),
+            "note": (
+                "Entries carry prevHash and hash verbatim. `verify.py` recomputes them; it cannot "
+                "prove the segment is complete, only that what is here is unaltered and consecutive "
+                "where the sequence numbers are consecutive."
+            ),
+        },
+        "chainContinuity": _continuity(entries),
+        "merkle": merkle_section,
+    }
+    # Host sections last, and they may not shadow a structural key — a host that named a section
+    # "auditChain" would otherwise replace the verification with its own claim about it.
+    reserved = set(pack)
+    for name, value in (subject.sections or {}).items():
+        if name not in reserved:
+            pack[name] = value
+    return pack
+
+
+# --------------------------------------------------------------------------------------------
+# The shipped verifier
+#
+# Assembled from this package's own Ed25519 and Merkle code so the verifier and the signer cannot
+# disagree: there is one implementation of each, and the bundle carries a copy of it.
+
+_VERIFIER_HEAD = '''#!/usr/bin/env python3
+"""Verify this evidence pack. Standard library only; needs nothing from the system that made it.
+
+    python3 verify.py                         # from inside the bundle directory
+    UNDERWRIT_PUBLIC_KEY=<base64> python3 verify.py   # and check origin against a key you obtained elsewhere
+
+Checks, each independent of the others:
+
+  1. Every file matches the SHA-256 recorded in manifest.json, so nothing has been edited.
+  2. Every audit entry's hash is the SHA-256 of its predecessor's hash plus its own contents, so no
+     entry has been altered and none has been reordered.
+  3. (format 2) The checkpoint's Ed25519 signature verifies under the key named in the manifest,
+     and every entry's inclusion proof leads to the checkpoint's root — so each entry sits where
+     the log said it did, in a tree of the size the log signed.
+  4. (format 2) The manifest's Ed25519 signature verifies under the same key.
+
+What this cannot prove: that the record is complete (a subset cannot show what was left out), and
+origin, unless you obtained the public key from the issuer yourself — the copy in this bundle only
+shows the bundle agrees with itself. Set UNDERWRIT_PUBLIC_KEY to the issuer's published key to check that.
+"""
+import base64, hashlib, hmac, json, os, sys
+from pathlib import Path
+
+HERE = Path(__file__).parent
+GENESIS = "0" * 64
+
+'''
+
+_VERIFIER_TAIL = '''
+
+def entry_hash(previous, payload):
+    body = json.dumps(payload, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    return hashlib.sha256(previous.encode("utf-8") + body).hexdigest()
+
+
+def canonical(payload):
+    return json.dumps(payload, sort_keys=True, separators=(",", ":")).encode("utf-8")
+
+
+def parse_note(note):
+    body, _, sigs = note.partition("\\n\\n")
+    lines = body.split("\\n")
+    out = {"origin": lines[0], "size": int(lines[1]), "root": base64.b64decode(lines[2]), "signatures": []}
+    for line in sigs.splitlines():
+        if line.startswith("\\u2014 "):
+            _, name, blob = line.split(" ", 2)
+            raw = base64.b64decode(blob)
+            out["signatures"].append((name, raw[:4].hex(), raw[4:]))
+    return out
+
+
+def _require() -> set:
+    """--require a,b or UNDERWRIT_REQUIRE: artefacts whose absence is a failure, not a notice."""
+    want = set()
+    argv = sys.argv[1:]
+    for i, a in enumerate(argv):
+        if a.startswith("--require="):
+            want.update(x.strip() for x in a.split("=", 1)[1].split(",") if x.strip())
+        elif a == "--require" and i + 1 < len(argv):
+            want.update(x.strip() for x in argv[i + 1].split(",") if x.strip())
+    want.update(x.strip() for x in os.environ.get("UNDERWRIT_REQUIRE", "").split(",") if x.strip())
+    bad = want - {"signature", "checkpoint", "witness", "timestamp"}
+    if bad:
+        raise SystemExit(f"unknown --require item(s): {', '.join(sorted(bad))} "
+                         f"(choose from signature, checkpoint, witness, timestamp)")
+    return want
+
+
+def main():
+    require = _require()
+    pinned = os.environ.get("UNDERWRIT_PUBLIC_KEY", "").strip()
+    wkeys = [k.strip() for k in os.environ.get("UNDERWRIT_WITNESS_KEY", "").split(",") if k.strip()]
+    # A pinned key is a demand, not a hint: pinning the log key requires a signed, checkpointed
+    # bundle, and pinning a witness key requires a cosignature. Otherwise a bundle stripped back to
+    # format 1 would "verify" with every pin silently ignored.
+    if pinned:
+        require |= {"signature", "checkpoint"}
+    if wkeys:
+        require |= {"witness"}
+
+    try:
+        manifest = json.loads((HERE / "manifest.json").read_text())
+    except FileNotFoundError:
+        print("FAILED: manifest.json is missing — this is not a complete bundle")
+        return 1
+    except ValueError:
+        print("FAILED: manifest.json is not valid JSON")
+        return 1
+    if manifest.get("format", 1) not in (1, 2):
+        print(f"FAILED: this verifier understands formats 1 and 2, not {manifest.get('format')}")
+        return 1
+    problems = []
+
+    for name, expected in sorted((manifest.get("files") or {}).items()):
+        try:
+            actual = hashlib.sha256((HERE / name).read_bytes()).hexdigest()
+        except FileNotFoundError:
+            problems.append(f"{name}: listed in the manifest but missing from the bundle")
+            continue
+        if actual != expected:
+            problems.append(f"{name}: content does not match its recorded digest")
+    for name in ("evidence.json", "verify.py"):
+        if name not in (manifest.get("files") or {}):
+            problems.append(f"{name}: not covered by the manifest")
+
+    try:
+        pack = json.loads((HERE / "evidence.json").read_text())
+        entries = pack["auditEntries"]
+        assert isinstance(entries, list)
+    except (FileNotFoundError, ValueError, KeyError, AssertionError):
+        print("FAILED: evidence.json is missing or malformed")
+        return 1
+    for entry in entries:
+        try:
+            payload = {
+                "at": entry["at"], "actor": entry["actor"], "actor_id": entry["actorId"],
+                "action": entry["action"], "environment": entry["environment"],
+                "target": entry["target"], "outcome": entry["outcome"], "reason": entry["reason"],
+                # `detail` is hashed as the OBJECT, not as a JSON string of it.
+                "detail": entry["detail"], "source_ip": entry["sourceIp"],
+            }
+            if entry_hash(entry["prevHash"] or GENESIS, payload) != entry["hash"]:
+                problems.append(f"audit entry seq {entry['seq']}: contents do not match its hash")
+        except (KeyError, TypeError) as exc:
+            problems.append(f"audit entry {entry.get('seq', '?') if isinstance(entry, dict) else '?'}: malformed ({type(exc).__name__})")
+
+    # --- format 2: checkpoint, proofs, signatures ----------------------------------------------
+    sigs = manifest.get("signatures") or []
+    ed = next((s for s in sigs if isinstance(s, dict) and s.get("alg") == "ed25519"), None)
+    if "signature" in require and not ed:
+        problems.append("origin: no Ed25519 manifest signature, and one is required (a key is pinned)")
+    pub = None
+    if ed:
+        pub = base64.b64decode(ed["publicKey"])
+        if pinned:
+            pins = [base64.b64decode(k.strip()) for k in pinned.split(",") if k.strip()]
+            if pub in pins:
+                print(f"origin: verified against the pinned key ({ed['keyId']})")
+            else:
+                problems.append("origin: no pinned key matches the key that signed this bundle")
+        else:
+            print(f"origin: key {ed['keyId']} ({ed.get('origin', '')}) — shown, not verified. "
+                  "Obtain the issuer's key and set UNDERWRIT_PUBLIC_KEY to check origin.")
+        if ed25519_verify(pub, canonical(manifest["files"]), base64.b64decode(ed["signature"])):
+            print("manifest: signature verified")
+        else:
+            problems.append("manifest: Ed25519 signature does not verify")
+    else:
+        print("origin: no Ed25519 signature (format 1 bundle, or an unsigned data plane)")
+
+    proven = 0
+    has_checkpoint = (HERE / "checkpoint").exists() and bool(pack.get("merkle"))
+    if "checkpoint" in require and not has_checkpoint:
+        problems.append("checkpoint: none in this bundle, and one is required (a key is pinned)")
+    if "witness" in require and not has_checkpoint:
+        problems.append("witness: no checkpoint to carry a cosignature, and one is required")
+    if "timestamp" in require and not (HERE / "timestamps" / "checkpoint.tsr").exists():
+        problems.append("timestamp: no RFC 3161 token in this bundle, and one is required")
+    if has_checkpoint:
+        note = (HERE / "checkpoint").read_text()
+        try:
+            cp = parse_note(note)
+        except (ValueError, IndexError, TypeError) as exc:
+            print(f"FAILED: the checkpoint note is malformed ({type(exc).__name__})")
+            return 1
+        body = f"{cp['origin']}\\n{cp['size']}\\n{base64.b64encode(cp['root']).decode()}\\n".encode()
+        ok_sig = False
+        if pub is not None:
+            want = hashlib.sha256(cp["origin"].encode() + b"\\n\\x01" + pub).digest()[:4].hex()
+            ok_sig = any(n == cp["origin"] and kh == want and ed25519_verify(pub, body, s)
+                         for n, kh, s in cp["signatures"])
+        if ok_sig:
+            print(f"checkpoint: signature verified (size {cp['size']})")
+        else:
+            problems.append("checkpoint: signature does not verify under the bundle's key")
+        if cp["root"].hex() != pack["merkle"]["root"] or cp["size"] != pack["merkle"]["size"]:
+            problems.append("checkpoint: does not match the tree the pack describes")
+        # Witness cosignatures, if any: each is a second party's statement that this is the
+        # history it saw. Pin one key per witness in UNDERWRIT_WITNESS_KEY (comma-separated); every
+        # pinned key must verify a cosignature on this checkpoint.
+        cosigs = [(n, kh, rest) for n, kh, rest in cp["signatures"] if n != cp["origin"] and len(rest) == 72]
+        if "witness" in require and not cosigs:
+            problems.append("witness: no cosignature on this checkpoint, and one is required (a witness key is pinned)")
+        if cosigs and wkeys:
+            import datetime
+            for wkey in wkeys:
+                wpub = base64.b64decode(wkey)
+                ok_w = None
+                for n, kh, rest in cosigs:
+                    want = hashlib.sha256(n.encode() + b"\\n\\x04" + wpub).digest()[:4].hex()
+                    t = int.from_bytes(rest[:8], "big")
+                    msg = f"cosignature/v1\\ntime {t}\\n".encode() + body
+                    if kh == want and ed25519_verify(wpub, msg, rest[8:]):
+                        ok_w = (n, t)
+                        break
+                if ok_w:
+                    print(f"witness: {ok_w[0]} cosigned this checkpoint at "
+                          f"{datetime.datetime.utcfromtimestamp(ok_w[1]).isoformat()}Z — the history up to size "
+                          f"{cp['size']} is the one it saw")
+                else:
+                    problems.append(f"witness: the pinned witness key {wkey[:8]}… does not verify any cosignature on this checkpoint")
+            if len(wkeys) > 1 and not problems:
+                print(f"witness: {len(wkeys)} independent witnesses agree on this history")
+        elif cosigs:
+            print(f"witness: cosigned by {', '.join(n for n, _, _ in cosigs)} — set UNDERWRIT_WITNESS_KEY to check it")
+        else:
+            print("witness: none — completeness rests on the log alone; a witness cosignature is what "
+                  "would show this history is the one a second party saw")
+        # External clocks. An RFC 3161 token binds SHA-256(checkpoint body) to a time a third party
+        # signed; we check the imprint here and hand the CMS signature to OpenSSL when it is present.
+        imprint_hex = hashlib.sha256(body).hexdigest()
+        tsr = HERE / "timestamps" / "checkpoint.tsr"
+        if tsr.exists():
+            try:
+                info = parse_tsr(tsr.read_bytes())
+            except (IndexError, ValueError, TypeError):
+                info = {"ok": False}
+            if not info.get("ok") or info.get("imprint") != imprint_hex or info.get("hashAlg") not in (None, "sha256"):
+                problems.append("timestamp: the RFC 3161 token does not cover this checkpoint's body (imprint or hash algorithm differs)")
+            else:
+                import shutil, subprocess
+                ca = os.environ.get("UNDERWRIT_TSA_CA", "").strip()
+                if ca and shutil.which("openssl"):
+                    r = subprocess.run(["openssl", "ts", "-verify", "-in", str(tsr), "-digest", imprint_hex,
+                                        "-CAfile", ca], capture_output=True, text=True)
+                    if r.returncode == 0 and "Verification: OK" in r.stdout:
+                        print(f"timestamp: TSA signature and chain verified by openssl; this checkpoint existed at "
+                              f"{info['genTime']} (serial {info['serial']})")
+                    else:
+                        why = ((r.stderr or r.stdout).strip().splitlines() or ["no output"])[-1]
+                        problems.append(f"timestamp: openssl could not verify the TSA signature against UNDERWRIT_TSA_CA: {why}")
+                elif ca:
+                    problems.append("timestamp: UNDERWRIT_TSA_CA is set but openssl is not on PATH, so the TSA signature "
+                                    "could not be checked")
+                else:
+                    print(f"timestamp: RFC 3161 token present, imprint matches; its claimed time {info['genTime']} "
+                          f"(serial {info['serial']}) is UNVERIFIED until the TSA signature is checked — set UNDERWRIT_TSA_CA "
+                          "to the TSA's CA bundle with openssl on PATH, or run: openssl ts -verify -in "
+                          f"timestamps/checkpoint.tsr -digest {imprint_hex} -CAfile <ca.pem>")
+        ots = HERE / "timestamps" / "checkpoint.ots"
+        if ots.exists():
+            meta = next((t for t in (pack["merkle"].get("timestamps") or []) if t.get("kind") == "ots"), {})
+            print(f"timestamp: OpenTimestamps proof present ({meta.get('status', 'unknown')}, calendar "
+                  f"{meta.get('calendar', '?')}) — upgrade and verify with the ots client; a pending proof is not an anchor")
+        if not tsr.exists() and not ots.exists():
+            print("timestamp: no external clock — the checkpoint's time rests on the log and its witnesses")
+        for entry in entries:
+            proof = entry.get("inclusionProof")
+            idx = entry.get("leafIndex")
+            if proof is None or idx is None:
+                continue
+            leaf = leaf_hash(entry["hash"].encode("ascii"))
+            try:
+                got = root_from_inclusion(idx, cp["size"], leaf, [bytes.fromhex(p) for p in proof])
+            except ValueError as exc:
+                problems.append(f"audit entry seq {entry['seq']}: inclusion proof malformed ({exc})")
+                continue
+            if got != cp["root"]:
+                problems.append(f"audit entry seq {entry['seq']}: inclusion proof does not reach the checkpoint root")
+            else:
+                proven += 1
+        print(f"merkle: {proven} of {len(entries)} entries proven at their positions under checkpoint size {cp['size']}")
+    elif manifest.get("format", 1) == 2:
+        print("merkle: no checkpoint in this bundle — positions not proven, chain hashes only")
+
+    key = os.environ.get("EVIDENCE_SIGNING_KEY", "").strip()
+    signature = manifest.get("signature")
+    if signature and key:
+        expected = hmac.new(key.encode("utf-8"), canonical(manifest["files"]), hashlib.sha256).hexdigest()
+        if not hmac.compare_digest(expected, signature):
+            problems.append("signature does not match: this bundle was not produced with that key")
+        else:
+            print("signature: verified")
+    elif signature:
+        print("signature: present, not checked (set EVIDENCE_SIGNING_KEY to check it)")
+    elif not ed:
+        print("signature: none (this bundle proves it is internally consistent, not who made it)")
+
+    if not entries:
+        print("NOTE: this pack contains no audit entries. There is nothing here to verify —")
+        print("      that is not the same as a clean result.")
+
+    if problems:
+        print(f"\\nFAILED — {len(problems)} problem(s):")
+        for p in problems:
+            print(f"  - {p}")
+        return 1
+    print(f"\\nOK — {len(manifest['files'])} file(s) intact, {len(entries)} audit entr(ies) verified.")
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        raise SystemExit(main())
+    except SystemExit:
+        raise
+    except Exception as exc:  # noqa: BLE001 — a verifier that crashes has said nothing
+        print(f"\\nFAILED — verifier error: {type(exc).__name__}: {exc}")
+        raise SystemExit(1)
+'''
+
+
+def _embedded_crypto() -> str:
+    """The package's own Ed25519 verifier and Merkle proof code, as text, for the shipped script."""
+    here = Path(__file__).parent
+    ed = (here / "ed25519.py").read_text()
+    ed = ed.split("# --- optional acceleration")[0]
+    ed = ed[ed.index("import hashlib"):]  # drop the module docstring; keep the code
+    ed = ed.replace("def verify(pub: bytes, msg: bytes, sig: bytes) -> bool:", "def ed25519_verify(pub, msg, sig):")
+    mk = (here / "merkle.py").read_text()
+    mk = mk[mk.index("import hashlib"):]
+    ts = (here / "tsa.py").read_text()
+    ts = ts[ts.index("SHA256_OID"):ts.index("def fetch_token")]
+    ts = ts.replace("def parse_response(", "def parse_tsr(")
+    return "# ---- Ed25519 (RFC 8032), from underwrit/ed25519.py ----\n" + ed + \
+           "\n# ---- Merkle proofs (RFC 9162), from underwrit/merkle.py ----\n" + mk + \
+           "\n# ---- RFC 3161 response reader, from underwrit/tsa.py ----\n" + ts
+
+
+_VERIFIER_CACHE: str | None = None
+
+
+def verifier() -> str:
+    global _VERIFIER_CACHE
+    if _VERIFIER_CACHE is None:
+        _VERIFIER_CACHE = _VERIFIER_HEAD + _embedded_crypto() + _VERIFIER_TAIL
+    return _VERIFIER_CACHE
+
+
+VERIFIER = verifier()
+
+
+def readme(pack: dict) -> str:
+    s = pack["subject"]
+    seg = pack["auditChain"]["segment"]
+    mk = pack.get("merkle")
+    return f"""# Evidence pack
+
+Subject: {s.get('kind')} `{s.get('id')}`
+Generated: {time.strftime('%Y-%m-%d %H:%M:%SZ', time.gmtime(pack['generatedAt']))}
+Audit entries: {len(pack['auditEntries'])}
+Chain segment: {seg.get('status')}
+Format: {pack.get('format')}{f"  ·  checkpoint size {mk['size']}, key {mk['keyId']}" if mk else ""}
+
+## Verify it
+
+    python3 verify.py
+
+Needs Python 3 and nothing else. No account, no network, no trust in whoever gave you this.
+
+## What this does and does not prove
+
+It proves the files have not been edited since the pack was made, and that each audit entry's
+contents match the hash recorded for it — so no entry has been altered or reordered.
+{"It proves each entry sits at its stated position in a log of the stated size, signed by the data plane's key, so an entry cannot be moved or its position forged." if mk else ""}
+
+It does **not** prove the record is complete. A pack can only show what it contains. Where the
+sequence numbers have gaps, other actors' entries sit between these — see `chainContinuity`.
+
+It does **not** prove origin from the bundle alone. The public key inside it shows the bundle
+agrees with itself. Obtain the issuer's key separately (`GET /v1/keys` on the data plane) and run
+`UNDERWRIT_PUBLIC_KEY=<key> python3 verify.py` to check the bundle was signed by that key.
+"""
+
+
+_readme = readme
+
+
+def write(conn, subject: Subject, dest: str | Path, key=None) -> dict:
+    """Write a verifiable bundle directory. Returns the manifest.
+
+    `key` is a `checkpoint.Key`; without one the bundle is format 2 without a checkpoint, proofs
+    or Ed25519 signature — the version-1 guarantees, stated as such.
+    """
+    from . import bundle as bundle_mod
+
+    dest = Path(dest)
+    dest.mkdir(parents=True, exist_ok=True)
+    _, files = bundle_mod.files_for(conn, subject, key)
+    for name, data in files.items():
+        (dest / name).write_bytes(data)
+    manifest = bundle_mod.manifest_for(files, key)
+    (dest / "manifest.json").write_text(json.dumps(manifest, indent=2, sort_keys=True))
+    return manifest