codeimprint 0.5.0a11__py3-none-any.whl

codeimprint_cli/receipt.py

@@ -0,0 +1,679 @@
+"""Verify a seal receipt: digest, attestation, developer signatures, log inclusion, time.
+
+A receipt is what `POST /api/v1/seal` returns next to the Imprint (see
+docs/how-sealing-works.md). Every check here is offline and uses only keys the caller already
+trusts; ``verify_online`` adds the checks that need the server's current log.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import asdict, dataclass
+from datetime import datetime, timedelta, timezone
+
+from . import imprint_file, records, timestamp, transparency, trust
+from .imprint_file import b64d, canonical
+
+# The development log's origin. Servers can run under another origin (CODEIMPRINT_LOG_ORIGIN),
+# so a checkpoint must carry its receipt's origin, and the live log must keep it.
+ORIGIN = "codeimprint.mudrika.io/log/v1"
+CLOCK_SKEW = timedelta(minutes=5)       # allowed between the server's and a TSA's clock
+CONFIRM_WITHIN = timedelta(hours=1)     # a TSA time further after the seal is reported
+AGREE_WITHIN = timedelta(hours=1)       # valid tokens of one subject further apart: FAIL
+
+PASS, FAIL, WARN = "PASS", "FAIL", "WARN"
+
+
+@dataclass
+class Check:
+    name: str
+    status: str
+    detail: str
+
+    def as_dict(self) -> dict:
+        return asdict(self)
+
+
+def _time(text: str) -> datetime:
+    return datetime.strptime(text, "%Y-%m-%dT%H:%M:%SZ").replace(tzinfo=timezone.utc)
+
+
+def checkpoint_digest(checkpoint: dict) -> bytes:
+    """What a TSA timestamps for a checkpoint: SHA-256 of its canonical statement."""
+    return hashlib.sha256(canonical(checkpoint["statement"])).digest()
+
+
+RELEASE = "codeimprint.release.v1"
+
+
+def _record(receipt: dict) -> Check:
+    """Receipt format 4: an ownership record. Its digest, typed ID, attestation fields and
+    owner signatures must all follow from the record document."""
+    from cryptography.exceptions import InvalidSignature
+    from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+
+    rec = receipt.get("record") or {}
+    doc, rtype_name = rec.get("document"), rec.get("type")
+    rtype = records.TYPES.get(rtype_name)
+    if rtype is None or not isinstance(doc, dict) or doc.get("type") != rtype_name:
+        return Check("record", FAIL, f"unknown or malformed record type {rtype_name!r}")
+    digest = hashlib.sha256(canonical(doc)).hexdigest()
+    if digest != receipt.get("digest"):
+        return Check("record", FAIL, "the record document does not give the receipt's digest")
+    if imprint_file.record_id(rtype.prefix, digest) != receipt.get("imprint_id"):
+        return Check("record", FAIL, "the record's ID is not the one its type and digest give")
+    st = (receipt.get("attestation") or {}).get("statement") or {}
+    if (st.get("kind"), st.get("project"), st.get("parents")) != (
+            rtype.kind, doc.get("project"), records.parents(rtype, doc)):
+        return Check("record", FAIL, "the attestation names another kind, project or parents")
+    message = canonical(records.sign_statement(rtype_name, digest))
+    sigs = receipt.get("signatures") or []
+    for sig in sigs:
+        try:
+            raw = b64d(sig["public_key"])
+            Ed25519PublicKey.from_public_bytes(raw).verify(b64d(sig["signature"]), message)
+        except (InvalidSignature, KeyError, TypeError, ValueError):
+            return Check("record", FAIL, f"the {sig.get('role')} signature does not verify")
+        if trust.fingerprint(raw) != sig.get("fingerprint"):
+            return Check("record", FAIL, "a signature's fingerprint does not match its key")
+    if [{"role": s["role"], "fingerprint": s["fingerprint"]} for s in sigs] != st.get("signers"):
+        return Check("record", FAIL, "the signatures are not the ones the attestation names")
+    missing = [r for r in rtype.roles if r not in {s["role"] for s in sigs}]
+    if missing:
+        return Check("record", FAIL, f"missing signature(s) for: {', '.join(missing)}")
+    who = ", ".join(f"{s['role']} {s['fingerprint']}" for s in sigs) or "no owner signatures"
+    return Check("record", PASS, f"{rtype.kind} record; {who}")
+
+
+def _release(receipt: dict) -> Check:
+    """A release record: its digest is SHA-256 of the release document, which names the
+    labelled seal; the chain must say the same."""
+    rel, digest, iid = receipt["release"], receipt.get("digest", ""), receipt.get("imprint_id")
+    if hashlib.sha256(canonical(rel)).hexdigest() != digest:
+        return Check("release", FAIL, "the release document does not give the receipt's digest")
+    if imprint_file.release_id(digest) != iid:
+        return Check("release", FAIL, "the receipt's digest does not give its release ID")
+    chain = receipt.get("chain") or {}
+    if (rel.get("type") != RELEASE or chain.get("kind") != "release"
+            or chain.get("parents") != [rel.get("seal")]
+            or chain.get("project") != rel.get("project")):
+        return Check("release", FAIL, "the release document and its chain disagree")
+    tag = (f"tag {rel['tag']}" if "tag" in rel else
+           "tag kept private (a salted commitment is public)" if "tag_commitment" in rel
+           else "no tag")
+    return Check("release", PASS, f"labels seal {rel['seal']}; {tag}")
+
+
+def _identity(receipt: dict, now: datetime) -> Check | None:
+    """Type checks for identity and revocation records (ADR 0002 steps 1.5-1.7)."""
+    from cryptography.exceptions import InvalidSignature
+    from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+
+    rec = receipt.get("record") or {}
+    doc = rec.get("document") or {}
+    if rec.get("type") == "codeimprint.identity.v1":
+        req = doc.get("request") or {}
+        st = req.get("statement") or {}
+        try:
+            raw = b64d(doc["public_key"])
+            Ed25519PublicKey.from_public_bytes(raw).verify(b64d(req["signature"]),
+                                                           canonical(st))
+        except (InvalidSignature, KeyError, TypeError, ValueError):
+            return Check("identity", FAIL, "the key did not sign this identity request")
+        if (st.get("type") != "codeimprint.identity-request.v1"
+                or st.get("public_key") != doc.get("public_key")
+                or trust.fingerprint(raw) != doc.get("key")
+                or (st.get("level"), st.get("provider"), st.get("subject")) != (
+                    doc.get("level"), doc.get("provider"), doc.get("subject"))):
+            return Check("identity", FAIL, "the identity record does not match the request "
+                                           "the key signed")
+        try:
+            until = _time(doc["valid_until"])
+        except (KeyError, ValueError):
+            return Check("identity", FAIL, "the identity record has no validity window")
+        if until <= now:
+            return Check("identity", FAIL, f"expired at {doc['valid_until']}")
+        subject = f" as {doc['subject']}" if doc.get("subject") else ""
+        return Check("identity", PASS, f"key {doc['key']} verified at level {doc['level']} "
+                                       f"({doc['provider']}{subject}) until {doc['valid_until']}")
+    if rec.get("type") == "codeimprint.org-member.v1":
+        roles = {s.get("role"): s for s in receipt.get("signatures") or []}
+        member = roles.get("member")
+        if not member or member.get("fingerprint") != doc.get("member_key"):
+            return Check("membership", FAIL, "the member key did not sign its membership")
+        if doc.get("basis") == "admin-approval" and "admin" not in roles:
+            return Check("membership", FAIL, "an admin-approved membership without the admin's "
+                                             "signature")
+        if doc.get("basis") != "admin-approval" and "admin" in roles:
+            return Check("membership", FAIL, "a domain-proven membership with an admin signature")
+        return Check("membership", PASS, f"key {doc.get('member_key')} in organisation "
+                                         f"{doc.get('org')} ({doc.get('basis')}) from "
+                                         f"{doc.get('valid_from')}")
+    if rec.get("type") == "codeimprint.disclosure.v1":
+        return Check("disclosure", PASS, f"organisation {doc.get('org')} discloses "
+                                         f"{doc.get('value')} (identity {doc.get('record')}); "
+                                         "check it against that record's commitment online")
+    if rec.get("type") == "codeimprint.revocation.v1":
+        holders = [s for s in receipt.get("signatures") or [] if s.get("role") == "holder"]
+        if holders and holders[0].get("fingerprint") != doc.get("key"):
+            return Check("revocation", FAIL, "signed by a key other than the revoked one")
+        since = f", compromised since {doc['compromised_since']}" \
+            if doc.get("compromised_since") else ""
+        what = doc.get("revokes") or f"key {doc.get('key')}"
+        return Check("revocation", PASS, f"{what}: {doc.get('reason')} from "
+                                         f"{doc.get('effective_at')}{since}")
+    return None
+
+
+def key_checks(receipt: dict, client) -> list[Check]:
+    """Online: the identity status of a record, and whether a seal's signer keys were reported
+    compromised before the seal (a seal signed from then on is flagged)."""
+    if not hasattr(client, "key_identity"):
+        return []
+    from .api import ApiError
+
+    def status(fp):
+        try:
+            return client.key_identity(fp)
+        except ApiError:
+            return None                              # a server without identity records
+
+    rec = receipt.get("record") or {}
+    if rec.get("type") == "codeimprint.identity.v1":
+        doc = rec["document"]
+        s = status(doc["key"])
+        if s is None:
+            return []
+        mine = next((i for i in s.get("identities", []) if i["id"] == receipt["imprint_id"]),
+                    None)
+        if mine is None:
+            return [Check("identity status", FAIL, "the server does not list this identity")]
+        if mine["status"] != "valid":
+            why = {"revoked": f"revoked by {mine.get('revoked_by')}",
+                   "expired": f"expired at {mine['valid_until']}",
+                   "suspect": f"bound after the key was reported compromised "
+                              f"({s.get('compromised_since')})"}.get(mine["status"],
+                                                                     mine["status"])
+            return [Check("identity status", FAIL, why)]
+        return [Check("identity status", PASS, "valid, not revoked")]
+    if rec:
+        return []
+    attested = ((receipt.get("attestation") or {}).get("statement") or {}).get("attested_at")
+    fps = {s.get("fingerprint") for s in receipt.get("developer_signatures") or []}
+    signer = chain_signer(receipt)
+    if signer:
+        fps.add(signer)
+    out = []
+    for fp in sorted(f for f in fps if f):
+        s = status(fp)
+        if s is None:
+            continue
+        since = s.get("compromised_since")
+        levels = sorted({f"{i['level']} ({i['subject'] or i['provider']})"
+                         for i in s.get("identities", []) if i["status"] == "valid"})
+        who = f"; verified: {', '.join(levels)}" if levels else ""
+        if since and attested and attested >= since:
+            out.append(Check("key status", FAIL, f"signed by {fp} after the key was reported "
+                                                 f"compromised (since {since})"))
+        elif since:
+            out.append(Check("key status", PASS, f"{fp} was reported compromised since {since}, "
+                                                 f"after this seal{who}"))
+        else:
+            out.append(Check("key status", PASS, f"{fp}: no compromise reported{who}"))
+    return out
+
+
+def _digest(receipt: dict, doc: dict | None) -> Check:
+    if "release" in receipt:
+        return _release(receipt)
+    digest, iid = receipt.get("digest", ""), receipt.get("imprint_id")
+    if imprint_file.imprint_id(digest) != iid:
+        return Check("digest", FAIL, "the receipt's digest does not give its Imprint ID")
+    if doc is None:
+        return Check("digest", PASS, f"{digest[:16]}… gives {iid} (no .imprint file checked)")
+    status = imprint_file.verify_document(doc)
+    if not status["digest_ok"]:
+        return Check("digest", FAIL, "the .imprint file was changed after sealing")
+    if (doc.get("integrity") or {}).get("sha256") != digest:
+        return Check("digest", FAIL, "the .imprint file is not the one this receipt seals")
+    if status["signature_ok"] is False:
+        return Check("digest", FAIL, "the .imprint file's own signature does not verify")
+    return Check("digest", PASS, f"{digest[:16]}… matches the .imprint file ({iid})")
+
+
+def _attestation(receipt: dict, keys: list[dict]) -> Check:
+    att = receipt.get("attestation") or {}
+    ok, why = trust.verify_signed(att, keys)
+    if not ok:
+        return Check("attestation", FAIL, why)
+    st = att["statement"]
+    if st.get("type") not in ("codeimprint.attestation.v1", "codeimprint.attestation.v2"):
+        return Check("attestation", FAIL, "not an attestation statement")
+    chain = receipt.get("chain")
+    if (st["type"].endswith(".v2") or chain) and "record" not in receipt:
+        fields = ("project", "kind", "parents")
+        if not chain or any(st.get(k) != chain.get(k) for k in fields):
+            return Check("attestation", FAIL, "the attestation and the receipt's chain disagree")
+    if st.get("digest") != receipt.get("digest") or st.get("imprint_id") != receipt.get(
+            "imprint_id"):
+        return Check("attestation", FAIL, "the attestation is for another Imprint")
+    params = (receipt.get("header") or {}).get("params")
+    if params and st.get("params") != params:
+        return Check("attestation", FAIL, "the attestation names another parameter set")
+    kind = f", kind {st['kind']}" if "kind" in st else ""
+    return Check("attestation", PASS, f"signed by {why} at {st['attested_at']}{kind}")
+
+
+CHAIN_STATEMENT = "codeimprint.chain-seal.v1"
+
+
+def chain_signer(receipt: dict) -> str | None:
+    """The fingerprint of the project key that signed this seal into its chain, if valid."""
+    from cryptography.exceptions import InvalidSignature
+    from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+
+    chain = receipt.get("chain") or {}
+    sig = chain.get("signature")
+    if not sig:
+        return None
+    statement = {"type": CHAIN_STATEMENT, "project": chain.get("project"),
+                 "kind": chain.get("kind"), "parents": chain.get("parents") or [],
+                 "digest": receipt.get("digest")}
+    try:
+        raw = b64d(sig["public_key"])
+        Ed25519PublicKey.from_public_bytes(raw).verify(b64d(sig["signature"]),
+                                                       canonical(statement))
+    except (InvalidSignature, ValueError, KeyError, TypeError):
+        return None
+    fp = trust.fingerprint(raw)
+    return fp if fp == sig.get("fingerprint") else None
+
+
+def _chain(receipt: dict) -> Check | None:
+    chain = receipt.get("chain")
+    if not chain:
+        return None
+    parents = ", ".join(chain.get("parents") or []) or "none"
+    if not chain.get("project"):
+        return Check("chain", PASS, f"kind {chain.get('kind')}, in no project")
+    if not chain.get("signature"):
+        return Check("chain", FAIL, "a project seal without its developer signature")
+    fp = chain_signer(receipt)
+    if fp is None:
+        return Check("chain", FAIL, "the developer signature over the chain does not verify")
+    return Check("chain", PASS, f"project {chain['project']}, kind {chain['kind']}, parent "
+                                f"{parents}; signed by project key {fp}")
+
+
+def _manifest(receipt: dict, doc: dict | None) -> Check | None:
+    """A Git seal's .imprint holds the manifest root the server attested."""
+    root = ((receipt.get("attestation") or {}).get("statement") or {}).get("manifest_root")
+    if root is None and not (doc or {}).get("manifest"):
+        return None
+    if doc is None:
+        return Check("manifest", PASS, f"root {root[:16]}… (no .imprint file checked)")
+    if (doc.get("manifest") or {}).get("root") != root:
+        return Check("manifest", FAIL, "the .imprint file's manifest root is not the sealed one")
+    return Check("manifest", PASS, f"root {root[:16]}… over {doc['manifest'].get('units')} "
+                                   "units matches the attestation")
+
+
+def _release_tag(receipt: dict, doc: dict | None) -> Check | None:
+    """A release seal names its tag as a release record does (a salted commitment, or the tag
+    when published): the Imprint's public header and the signed attestation must agree."""
+    signed = ((receipt.get("attestation") or {}).get("statement") or {}).get("release")
+    shown = ((doc if doc is not None else receipt.get("header")) or {}).get("release")
+    if signed is None and shown is None:
+        return None
+    if signed != shown:
+        return Check("release", FAIL, "the release tag in the Imprint is not the attested one")
+    tag = (f"tag {signed['tag']}" if "tag" in signed else
+           "tag kept private (a salted commitment is public)")
+    return Check("release", PASS, f"release seal; {tag}")
+
+
+def _developer(receipt: dict, expected: str | None) -> Check:
+    from cryptography.exceptions import InvalidSignature
+    from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+
+    good, bad = [], []
+    for sig in receipt.get("developer_signatures") or []:
+        try:
+            raw = b64d(sig["public_key"])
+            Ed25519PublicKey.from_public_bytes(raw).verify(
+                b64d(sig["signature"]), trust.developer_message(receipt["digest"]))
+            if trust.fingerprint(raw) != sig.get("fingerprint"):
+                raise ValueError("fingerprint does not match the key")
+            good.append(sig["fingerprint"])
+        except (InvalidSignature, ValueError, KeyError, TypeError):
+            bad.append(str(sig.get("fingerprint")))
+    signer = chain_signer(receipt)
+    if signer and signer not in good:
+        good.append(signer)                          # the chain signature is the developer's
+    if bad:
+        return Check("developer signature", FAIL, f"does not verify: {', '.join(bad)}")
+    if expected and expected not in good:
+        return Check("developer signature", FAIL,
+                     f"no signature by the project's developer key {expected}")
+    if not good:
+        return Check("developer signature", WARN, "none (sealed without a developer key)")
+    mark = " (the project's key)" if expected else ""
+    return Check("developer signature", PASS, f"by {', '.join(good)}{mark}")
+
+
+def _log(receipt: dict, keys: list[dict]) -> Check:
+    log = receipt.get("log") or {}
+    cp, leaf, att = log.get("checkpoint") or {}, log.get("leaf") or {}, receipt.get(
+        "attestation") or {}
+    ok, why = trust.verify_signed(cp, keys)
+    if not ok:
+        return Check("log inclusion", FAIL, f"checkpoint: {why}")
+    st = cp["statement"]
+    if st.get("type") != "codeimprint.checkpoint.v1" or not st.get("origin"):
+        return Check("log inclusion", FAIL, "not a CodeImprint log checkpoint")
+    if st["origin"] != receipt.get("origin", st["origin"]):
+        return Check("log inclusion", FAIL, f"the checkpoint is from log {st['origin']}, not "
+                                            f"from this receipt's log {receipt.get('origin')}")
+    expected = {"type": "codeimprint.log-entry.v1", "index": log.get("index"),
+                "imprint_id": receipt.get("imprint_id"), "digest": receipt.get("digest"),
+                "attested_at": (att.get("statement") or {}).get("attested_at"),
+                "attestation_key_id": att.get("key_id"),
+                "attestation_signature": att.get("signature")}
+    ast = att.get("statement") or {}
+    if ast.get("type") == "codeimprint.attestation.v2":
+        expected.update(type="codeimprint.log-entry.v2", project=ast.get("project"),
+                        kind=ast.get("kind"), parents=ast.get("parents"))
+    if leaf != expected:
+        return Check("log inclusion", FAIL, "the log entry does not match this seal")
+    size = st.get("tree_size")
+    if log.get("tree_size") != size:
+        return Check("log inclusion", FAIL, "the proof is for another tree size")
+    try:
+        proof = [bytes.fromhex(h) for h in log.get("inclusion_proof", [])]
+        root = bytes.fromhex(st["root_hash"])
+    except (ValueError, TypeError, KeyError):
+        return Check("log inclusion", FAIL, "malformed proof")
+    if not transparency.verify_inclusion(log["index"], size,
+                                         transparency.leaf_hash(canonical(leaf)), proof, root):
+        return Check("log inclusion", FAIL, "the inclusion proof does not reach the checkpoint")
+    return Check("log inclusion", PASS,
+                 f"entry #{log['index']} of {size}, checkpoint signed by {why}")
+
+
+# -- timestamps ----------------------------------------------------------------------------
+@dataclass
+class _Group:
+    """The timestamps of one thing the TSAs were asked to stamp: the seal or the checkpoint."""
+
+    label: str                       # seal | checkpoint
+    subject: str                     # as the server's signed record names it
+    digest: bytes                    # the SHA-256 the TSAs timestamped
+    committed: list | None           # TSAs the signed statement committed to (None: v1)
+    record: dict | None              # the server's signed codeimprint.timestamps.v1 record
+    tokens: list[dict]               # one entry per TSA: ok (with token) | unavailable | invalid
+
+
+def _view(view) -> tuple[dict | None, list[dict]]:
+    """(record, token entries) from a receipt v2 view, or from a v1 single-token field."""
+    if isinstance(view, dict) and "tokens" in view:
+        return view.get("record"), [t for t in view.get("tokens") or [] if isinstance(t, dict)]
+    return None, [view] if isinstance(view, dict) else []
+
+
+def _groups(receipt: dict) -> list[_Group]:
+    cp = (receipt.get("log") or {}).get("checkpoint") or {}
+    cp_st = cp.get("statement") or {}
+    att_st = (receipt.get("attestation") or {}).get("statement") or {}
+    try:
+        seal_digest = bytes.fromhex(receipt.get("digest") or "")
+    except ValueError:
+        seal_digest = b""
+    groups = []
+    for label, view, committed, subject, digest in (
+            ("seal", (receipt.get("timestamps") or {}).get("seal"), att_st.get("tsas"),
+             f"seal:{receipt.get('imprint_id')}", seal_digest),
+            ("checkpoint", cp.get("timestamps", cp.get("timestamp")), cp_st.get("tsas"),
+             f"checkpoint:{cp_st.get('tree_size')}", checkpoint_digest(cp) if cp_st else b"")):
+        record, tokens = _view(view)
+        groups.append(_Group(label, subject, digest, committed, record, tokens))
+    return groups
+
+
+def _record_problem(g: _Group, keys: list[dict]) -> str | None:
+    """With a commitment, the signed record must name every committed TSA and match each
+    token entry exactly: a token cannot be dropped, swapped or relabelled unnoticed."""
+    if not g.committed:
+        return None
+    if g.record is None:
+        return "the server's signed record of these timestamps is missing (removed?)"
+    ok, why = trust.verify_signed(g.record, keys)
+    if not ok:
+        return f"timestamps record: {why}"
+    st = g.record["statement"]
+    if (st.get("type") != "codeimprint.timestamps.v1" or st.get("subject") != g.subject
+            or st.get("digest") != g.digest.hex()):
+        return "the timestamps record is for something else"
+    results = {r.get("url"): r for r in st.get("results") or []}
+    if set(results) != set(g.committed):
+        return "the timestamps record does not cover the TSAs the seal committed to"
+    entries = {t.get("url"): t for t in g.tokens}
+    if set(entries) != set(results):
+        return "a timestamp was removed from (or added to) the receipt"
+    for url, result in results.items():
+        entry = entries[url]
+        if entry.get("status") != result.get("status"):
+            return f"{url}: recorded as {result.get('status')}, shown as {entry.get('status')}"
+        if result.get("status") == "ok":
+            try:
+                sha = hashlib.sha256(b64d(entry["token"])).hexdigest()
+            except (KeyError, ValueError, TypeError):
+                sha = None
+            if sha != result.get("token_sha256"):
+                return f"{url}: the token is not the one the server recorded"
+    return None
+
+
+def _cn(subject: str) -> str:
+    part = next((p for p in subject.split(",") if p.startswith("CN=")), subject)
+    return part.removeprefix("CN=")
+
+
+def _timestamps(receipt: dict, keys: list[dict],
+                anchors: list) -> tuple[list[Check], list[timestamp.TokenInfo]]:
+    """One line per TSA and subject; every token present must verify (else FAIL)."""
+    checks, infos = [], []
+    groups = _groups(receipt)
+    for g in groups:
+        name = f"timestamp {g.label}"
+        problem = _record_problem(g, keys)
+        if problem:
+            checks.append(Check(name, FAIL, problem))
+        good = []
+        for entry in g.tokens:
+            where, status = entry.get("url") or "TSA", entry.get("status")
+            if status == "ok":
+                try:
+                    info = timestamp.verify_token(b64d(entry["token"]), g.digest, anchors)
+                except (timestamp.TimestampError, KeyError, ValueError, TypeError) as exc:
+                    checks.append(Check(name, FAIL, f"{where}: {exc}"))
+                    continue
+                if entry.get("gen_time") not in (None, info.gen_time):
+                    checks.append(Check(name, FAIL, f"{where}: the receipt misstates genTime"))
+                    continue
+                good.append(info)
+                checks.append(Check(name, PASS, f"{_cn(info.tsa)} at {info.gen_time} "
+                                                f"(root {info.root})"))
+            elif status == "unavailable":
+                checks.append(Check(name, WARN, f"{where}: unavailable at seal time"))
+            elif status == "invalid":
+                checks.append(Check(name, WARN, f"{where}: invalid response at seal time "
+                                                "(not kept)"))
+            elif status == "pending":                                  # receipt v1
+                checks.append(Check(name, WARN, "pending at the TSA; fetch the receipt again"))
+            else:
+                checks.append(Check(name, FAIL, f"{where}: unknown status {status!r}"))
+        if len(good) > 1:
+            times = sorted(_time(i.gen_time) for i in good)
+            if times[-1] - times[0] > AGREE_WITHIN:
+                checks.append(Check(name, FAIL, f"the TSAs disagree on the time by "
+                                                f"{times[-1] - times[0]}"))
+        infos += good
+    if not any(g.tokens for g in groups) and not checks:
+        checks.append(Check("timestamp", WARN, "no RFC 3161 timestamp on this seal"))
+    return checks, infos
+
+
+def _time_order(receipt: dict, infos: list[timestamp.TokenInfo], now: datetime) -> Check:
+    try:
+        attested = _time(receipt["attestation"]["statement"]["attested_at"])
+        issued = _time(receipt["log"]["checkpoint"]["statement"]["issued_at"])
+    except (KeyError, TypeError, ValueError):
+        return Check("time", FAIL, "missing or malformed times")
+    if attested > now + CLOCK_SKEW:
+        return Check("time", FAIL, f"attested in the future ({attested:%Y-%m-%d %H:%M} UTC)")
+    if issued < attested:
+        return Check("time", FAIL, "the checkpoint is older than the seal it includes")
+    if not infos:
+        return Check("time", WARN, f"sealed {attested:%Y-%m-%d %H:%M:%S} UTC, attested by the "
+                     "server only (no independent timestamp)")
+    for info in infos:                           # timestamps are requested after sealing
+        if _time(info.gen_time) < attested - CLOCK_SKEW:
+            return Check("time", FAIL, f"{_cn(info.tsa)} dates the seal {info.gen_time}, "
+                         "before its attested time: the seal time was forged")
+    earliest = min(_time(i.gen_time) for i in infos)
+    if earliest - attested > CONFIRM_WITHIN:
+        return Check("time", WARN, f"attested {attested:%Y-%m-%d %H:%M} UTC but independently "
+                     f"confirmed only from {earliest:%Y-%m-%d %H:%M} UTC; rely on the later time")
+    count = len({i.tsa for i in infos})
+    return Check("time", PASS, f"sealed {attested:%Y-%m-%d %H:%M:%S} UTC, confirmed by "
+                 f"{count} TSA{'s' if count > 1 else ''} from {earliest:%Y-%m-%d %H:%M:%S} UTC")
+
+
+def verify(receipt: dict, keys: list[dict], doc: dict | None = None,
+           developer: str | None = None, now: datetime | None = None,
+           anchors: list | None = None) -> list[Check]:
+    """Every offline check. ``developer`` is the fingerprint the project expects to sign;
+    ``anchors`` the trusted TSA roots (default: the pinned ones)."""
+    now = now or datetime.now(timezone.utc)
+    anchors = timestamp.pinned_anchors() if anchors is None else anchors
+    if not keys:
+        return [_digest(receipt, doc),
+                Check("attestation", FAIL, "no trusted server keys: run `imprint verify "
+                      "--online` once, or pass --keys FILE")]
+    if "record" in receipt:                          # receipt format 4
+        checks = [_record(receipt), _attestation(receipt, keys), _log(receipt, keys)]
+        typed = _identity(receipt, now)
+        if typed:
+            checks.insert(1, typed)
+        tokens, infos = _timestamps(receipt, keys, anchors)
+        return checks + tokens + [_time_order(receipt, infos, now)]
+    checks = [_digest(receipt, doc), _attestation(receipt, keys),
+              *[c for c in (_chain(receipt), _manifest(receipt, doc),
+                            _release_tag(receipt, doc)) if c],
+              _developer(receipt, developer), _log(receipt, keys)]
+    tokens, infos = _timestamps(receipt, keys, anchors)
+    checks += tokens
+    checks.append(_time_order(receipt, infos, now))
+    return checks
+
+
+# -- online --------------------------------------------------------------------------------
+def _consistent(a: dict, b: dict, proof_hex: list[str]) -> bool:
+    try:
+        return transparency.verify_consistency(
+            a["statement"]["tree_size"], b["statement"]["tree_size"],
+            bytes.fromhex(a["statement"]["root_hash"]), bytes.fromhex(b["statement"]["root_hash"]),
+            [bytes.fromhex(h) for h in proof_hex])
+    except (KeyError, ValueError, TypeError):
+        return False
+
+
+def verify_online(receipt: dict, client, keys: list[dict],
+                  anchors: list | None = None) -> list[Check]:
+    """Check the receipt against the server's current log (``client`` is an api.Client)."""
+    anchors = timestamp.pinned_anchors() if anchors is None else anchors
+    checks = []
+    cp = receipt["log"]["checkpoint"]
+    size, index = cp["statement"]["tree_size"], receipt["log"]["index"]
+
+    latest = client.log_checkpoint()
+    ok, why = trust.verify_signed(latest, keys)
+    if not ok:
+        return [Check("log consistency", FAIL, f"latest checkpoint: {why}")]
+    if latest["statement"].get("origin") != cp["statement"].get("origin"):
+        return [Check("log consistency", FAIL, f"the server now serves log "
+                      f"{latest['statement'].get('origin')}, not "
+                      f"{cp['statement'].get('origin')}")]
+    new_size = latest["statement"]["tree_size"]
+    if new_size < size:
+        return [Check("log consistency", FAIL, f"the log shrank from {size} to {new_size}")]
+    proof = client.log_consistency(size, new_size)
+    if not _consistent(cp, latest, proof["proof"]):
+        return [Check("log consistency", FAIL, "the log was rewritten since this receipt: an "
+                      "entry was removed, reordered or changed")]
+    checks.append(Check("log consistency", PASS,
+                        f"log now has {new_size} entries and extends this receipt's checkpoint"))
+
+    if index > 0:                                  # the log just before this entry
+        before = client.log_consistency(index, size)
+        prior = before["from_checkpoint"]
+        ok, why = trust.verify_signed(prior, keys)
+        if not ok or not _consistent(prior, cp, before["proof"]):
+            checks.append(Check("log order", FAIL, "cannot prove the log before this entry"))
+        else:
+            attested = receipt["attestation"]["statement"]["attested_at"]
+            floor = prior["statement"]["issued_at"]
+            _record, entries = _view(prior.get("timestamps", prior.get("timestamp")))
+            for entry in entries:
+                if entry.get("status") != "ok":
+                    continue
+                try:
+                    info = timestamp.verify_token(b64d(entry["token"]),
+                                                  checkpoint_digest(prior), anchors)
+                    floor = max(floor, info.gen_time)
+                except (timestamp.TimestampError, KeyError, ValueError):
+                    pass
+            if _time(attested) < _time(floor) - CLOCK_SKEW:
+                checks.append(Check("log order", FAIL, f"attested {attested}, but the log "
+                                    f"before this entry already existed at {floor}: backdated"))
+            else:
+                checks.append(Check("log order", PASS,
+                                    f"entry #{index} was added after entry #{index - 1}"))
+
+    chain = receipt.get("chain") or {}
+    signer = chain_signer(receipt)
+    if chain.get("project") and signer and hasattr(client, "public_project"):
+        attested = receipt["attestation"]["statement"]["attested_at"]
+        keys_now = {k["fingerprint"]: k
+                    for k in client.public_project(chain["project"]).get("keys", [])}
+        k = keys_now.get(signer)
+        if k and k["valid_from"] <= attested and (not k["valid_until"]
+                                                  or attested <= k["valid_until"]):
+            checks.append(Check("project key", PASS, f"{signer} was a key of project "
+                                                     f"{chain['project']} at {attested}"))
+        else:
+            checks.append(Check("project key", FAIL, f"{signer} was not a key of project "
+                                                     f"{chain['project']} at {attested}"))
+    rel = receipt.get("release")
+    if rel:
+        try:
+            sealed = client.public_imprint(rel["seal"])
+        except Exception as exc:  # noqa: BLE001 — reported as a failed check
+            sealed = {"error": str(exc)}
+        ok = (sealed.get("digest") == rel.get("seal_digest")
+              and ((sealed.get("chain") or {}).get("project") == rel.get("project"))
+              and (sealed.get("log") or {}).get("index", index) < index)
+        checks.append(Check("released seal", PASS if ok else FAIL,
+                            f"{rel['seal']} is an earlier seal of the project with digest "
+                            f"{str(rel.get('seal_digest'))[:16]}…" if ok else
+                            f"{rel['seal']} is not the sealed tree this release names"))
+    checks += key_checks(receipt, client)
+    record = (client.public_record(receipt["imprint_id"]) if "record" in receipt
+              else client.public_imprint(receipt["imprint_id"]))
+    same = (record.get("digest") == receipt["digest"]
+            and record.get("attestation") == receipt["attestation"]
+            and (record.get("log") or {}).get("index") == index)
+    checks.append(Check("registry", PASS if same else FAIL,
+                        "the public record matches this receipt" if same else
+                        "the public record differs from this receipt"))
+    return checks