underwrit 0.3.0__py3-none-any.whl

underwrit/auth.py

@@ -0,0 +1,348 @@
+"""Who is calling, and what they may do.
+
+The rule this module exists for: **an approver's identity comes from the token, never from the
+request body.** Before this, `/v1/decisions/:id/resolve` took `{"approver": "priya"}` and believed
+it — so anybody who could reach the port could approve anything under any name, and the audit trail
+would record the name they chose. A record of who approved something is worthless if the subject of
+the record supplies it.
+
+Five roles, and the separation between approver and admin is the point:
+
+| role       | may                                                        |
+|------------|------------------------------------------------------------|
+| `agent`    | open sessions, propose actions, report outcomes            |
+| `approver` | resolve held decisions — and nothing else                  |
+| `admin`    | distribute policy, mint and revoke tokens, read everything |
+| `auditor`  | read sessions and evidence; change nothing                 |
+| `node`     | a data plane authenticating upward to the control plane    |
+
+An `agent` cannot resolve. That is the whole shape of the control: a runtime that could approve its
+own held decision has an approval gate it can open, which is the thing the product sells against.
+And an `admin` cannot resolve either — the role that mints approver tokens must not also approve
+with them.
+
+**Production needs two distinct people.** Counted as people, not as calls: approving twice from two
+tokens held by the same subject advances nothing. Quorum applies where enforcement is on, because a
+shadow-mode hold blocks nothing and demanding a quorum to acknowledge it would teach people to click
+through both.
+
+Tokens are stored as SHA-256, never in the clear. The database is backed up, copied to a laptop, and
+read by whoever has the file; a token in it is a credential leaked to all of them. A token carries a
+tenant (empty on a data plane, which is single-tenant by construction) and may carry an expiry;
+rotation mints a successor and revokes the predecessor in one step, and the successor records which
+token it replaced so the lineage is in the record.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import os
+import secrets
+import time
+
+from . import db, oidc
+
+ROLES = ("agent", "approver", "admin", "auditor", "node")
+
+# What each role may do. Deny by default: an action absent here is refused for everyone, so adding an
+# endpoint without deciding who may call it fails closed rather than open.
+GRANTS: dict[str, frozenset[str]] = {
+    "agent": frozenset({"session.open", "session.close", "decide", "outcome", "decision.read",
+                        "evidence.read", "whoami"}),
+    "approver": frozenset({"decision.resolve", "decision.read", "read", "evidence.read", "whoami"}),
+    "admin": frozenset({"policy.write", "policy.read", "token.mint", "token.revoke", "token.read",
+                        "read", "decision.read", "evidence.read", "retention.read",
+                        "retention.write", "hold.write", "tenant.create", "tenant.read", "metrics",
+                        "whoami"}),
+    "auditor": frozenset({"read", "decision.read", "evidence.read", "policy.read", "retention.read",
+                          "metrics", "whoami"}),
+    # A data plane authenticating *upward* to the control plane. It may fetch the policy it is to
+    # enforce and report what it decided, and nothing else — a node credential lives on a customer's
+    # infrastructure, so it must not be able to rewrite the policy the rest of the fleet receives.
+    "node": frozenset({"policy.read", "report", "whoami"}),
+}
+# `read` is the console's floor; `evidence.read` is separate because a pack is the thing you hand to
+# an outsider, and being able to watch decisions go by is not the same as being able to export them.
+
+TWO_PERSON = frozenset({"decision.resolve"})
+
+SCHEMA = [
+    """CREATE TABLE IF NOT EXISTS tokens (
+        id TEXT PRIMARY KEY,
+        digest TEXT NOT NULL UNIQUE,
+        subject TEXT NOT NULL,
+        role TEXT NOT NULL,
+        tenant TEXT NOT NULL DEFAULT '',
+        created_at REAL NOT NULL,
+        expires_at REAL,
+        revoked_at REAL,
+        rotated_from TEXT NOT NULL DEFAULT ''
+    )""",
+    "CREATE INDEX IF NOT EXISTS tokens_digest ON tokens (digest)",
+    """CREATE TABLE IF NOT EXISTS approvals (
+        decision_id TEXT NOT NULL,
+        subject TEXT NOT NULL,
+        verdict TEXT NOT NULL,
+        reason TEXT NOT NULL DEFAULT '',
+        at REAL NOT NULL,
+        PRIMARY KEY (decision_id, subject)
+    )""",
+]
+
+# Columns added after the table first shipped. Applied when absent, so a database created before
+# they existed gains them without a rebuild.
+_ADDED_COLUMNS = (
+    ("tenant", "TEXT NOT NULL DEFAULT ''"),
+    ("expires_at", "REAL"),
+    ("rotated_from", "TEXT NOT NULL DEFAULT ''"),
+    # Break glass: an emergency credential minted from the host, never over the API. Every request
+    # it makes is chained by name, because emergency access that leaves no trace is the incident.
+    ("break_glass", "INTEGER NOT NULL DEFAULT 0"),
+    ("note", "TEXT NOT NULL DEFAULT ''"),
+)
+
+
+def init(conn) -> None:
+    for ddl in SCHEMA:
+        conn.execute(db.ddl(ddl))
+    have = db.table_columns(conn, "tokens")
+    for name, ddl in _ADDED_COLUMNS:
+        if name not in have:
+            conn.execute(db.ddl(f"ALTER TABLE tokens ADD COLUMN {name} {ddl}"))
+    conn.commit()
+
+
+def default_ttl() -> float | None:
+    """Seconds a newly minted token lives unless the caller says otherwise. Unset means no expiry."""
+    raw = os.environ.get("UNDERWRIT_TOKEN_TTL_SECONDS", "").strip()
+    return float(raw) if raw else None
+
+
+def _digest(token: str) -> str:
+    return hashlib.sha256(token.encode("utf-8")).hexdigest()
+
+
+def _meta(r) -> dict:
+    keys = r.keys()
+    return {"id": r["id"], "subject": r["subject"], "role": r["role"],
+            "tenant": r["tenant"] or "", "createdAt": r["created_at"],
+            "expiresAt": r["expires_at"], "revokedAt": r["revoked_at"],
+            "rotatedFrom": r["rotated_from"] or "",
+            "breakGlass": bool(r["break_glass"]) if "break_glass" in keys else False,
+            "note": (r["note"] or "") if "note" in keys else ""}
+
+
+def mint(conn, *, subject: str, role: str, tenant: str = "", ttl: float | None = None,
+         rotated_from: str = "", break_glass: bool = False, note: str = "") -> tuple[str, dict]:
+    """Create a token. Returned once, in the clear, and never recoverable afterwards.
+
+    `ttl` in seconds; `None` takes the environment default (`UNDERWRIT_TOKEN_TTL_SECONDS`), and `0`
+    means no expiry — which is what a bootstrap admin gets, because a first credential that expires
+    out from under the operator is a locked door with the key inside.
+    """
+    if role not in ROLES:
+        raise ValueError(f"unknown role {role!r}; expected one of {', '.join(ROLES)}")
+    if not subject:
+        raise ValueError("subject is required — an approval attributed to nobody is not a record")
+    ttl = default_ttl() if ttl is None else ttl
+    if ttl is not None and ttl < 0:
+        raise ValueError("ttl must be positive, or 0 for no expiry")
+    now = time.time()
+    token = f"underwrit_{'bgl' if break_glass else role[:3]}_{secrets.token_urlsafe(32)}"
+    tid = f"tok-{secrets.token_hex(6)}"
+    conn.execute(
+        "INSERT INTO tokens (id, digest, subject, role, tenant, created_at, expires_at, rotated_from, "
+        "break_glass, note) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+        (tid, _digest(token), subject, role, tenant or "", now,
+         (now + ttl) if ttl else None, rotated_from or "", 1 if break_glass else 0, note or ""),
+    )
+    conn.commit()
+    return token, {"id": tid, "subject": subject, "role": role, "tenant": tenant or "",
+                   "expiresAt": (now + ttl) if ttl else None, "rotatedFrom": rotated_from or "",
+                   "breakGlass": bool(break_glass), "note": note or ""}
+
+
+def revoke(conn, token_id: str) -> bool:
+    cur = conn.execute("UPDATE tokens SET revoked_at = ? WHERE id = ? AND revoked_at IS NULL",
+                       (time.time(), token_id))
+    conn.commit()
+    return bool(getattr(cur, "rowcount", 0))
+
+
+def get(conn, token_id: str) -> dict | None:
+    r = conn.execute("SELECT * FROM tokens WHERE id = ?", (token_id,)).fetchone()
+    return _meta(r) if r else None
+
+
+def rotate(conn, token_id: str, *, ttl: float | None = None) -> tuple[str, dict] | None:
+    """Mint a successor with the same subject, role and tenant, and revoke the predecessor.
+
+    One step, so there is never a moment with two live tokens for one purpose — and the successor
+    names the token it replaced, which is how an auditor follows a credential through its life.
+    """
+    r = conn.execute("SELECT * FROM tokens WHERE id = ? AND revoked_at IS NULL", (token_id,)).fetchone()
+    if not r:
+        return None
+    if "break_glass" in r.keys() and r["break_glass"]:
+        # An emergency credential is short-lived by construction; a successor without the flag and
+        # without the clock would turn a break-glass event into standing access.
+        raise ValueError("break-glass tokens cannot be rotated; issue a new one from the host if still needed")
+    remaining = (float(r["expires_at"]) - time.time()) if r["expires_at"] else None
+    if remaining is not None:
+        if remaining <= 0:
+            raise ValueError("token has expired; mint a new one")
+        # A successor never outlives what the predecessor had left, whatever TTL was asked for.
+        ttl = remaining if ttl is None or ttl <= 0 or ttl > remaining else ttl
+    token, meta = mint(conn, subject=r["subject"], role=r["role"], tenant=r["tenant"] or "",
+                       ttl=ttl, rotated_from=token_id)
+    revoke(conn, token_id)
+    return token, meta
+
+
+def list_tokens(conn, *, tenant: str | None = None, include_revoked: bool = False) -> list[dict]:
+    """Every token's metadata. Never the token, never the digest — neither has a reader."""
+    sql = "SELECT * FROM tokens WHERE 1=1"
+    params: list[object] = []
+    if tenant is not None:
+        sql += " AND tenant = ?"
+        params.append(tenant)
+    if not include_revoked:
+        sql += " AND revoked_at IS NULL"
+    sql += " ORDER BY created_at DESC"
+    now = time.time()
+    out = []
+    for r in conn.execute(sql, params).fetchall():
+        m = _meta(r)
+        m["expired"] = bool(m["expiresAt"] and m["expiresAt"] <= now)
+        out.append(m)
+    return out
+
+
+def identify(conn, header: str | None, *, plane: str = "data") -> dict | None:
+    """Resolve a bearer to an identity. `None` means unauthenticated, never a default one.
+
+    An Underwrit token first; otherwise, when an identity provider is configured, a JWT from it. The
+    identity dict is the same shape either way, so nothing downstream knows or cares where a
+    person signed in — the gates, the quorum and the chain treat both alike.
+    """
+    if not header:
+        return None
+    raw = header[7:].strip() if header.lower().startswith("bearer ") else header.strip()
+    if not raw:
+        return None
+    if not raw.startswith("underwrit_"):
+        return oidc.identify(raw, plane=plane)
+    want = _digest(raw)
+    now = time.time()
+    rows = conn.execute(
+        "SELECT id, digest, subject, role, tenant, expires_at, break_glass FROM tokens "
+        "WHERE revoked_at IS NULL AND (expires_at IS NULL OR expires_at > ?)", (now,)
+    ).fetchall()
+    for r in rows:
+        # Constant-time compare against every candidate rather than a lookup by digest. A SELECT on
+        # the digest is fine cryptographically, but this keeps the comparison itself uniform and the
+        # table is small; if it ever is not, index it and compare the single row the same way.
+        if hmac.compare_digest(r["digest"], want):
+            return {"tokenId": r["id"], "subject": r["subject"], "role": r["role"],
+                    "tenant": r["tenant"] or "", "expiresAt": r["expires_at"],
+                    "breakGlass": bool(r["break_glass"]), "via": "break-glass" if r["break_glass"] else "token"}
+    return None
+
+
+def break_glass(conn, *, plane: str, reason: str, by: str, role: str = "admin", ttl: float = 3600,
+                tenant: str = "") -> tuple[str, dict]:
+    """The emergency credential. Minted from the host, never over the API.
+
+    For when the identity provider is down, the last admin token is lost, or an approver is
+    needed at three in the morning and nobody with the role can be reached. It is short-lived,
+    named for who took it and why, and every request it makes is chained as `break-glass.<action>`
+    — so the trail of an emergency is the fullest trail in the log, not the thinnest.
+    """
+    if not reason.strip():
+        raise ValueError("break glass needs a reason; it goes in the record")
+    if role not in ("admin", "approver", "auditor"):
+        raise ValueError("break glass mints admin, approver or auditor")
+    subject = f"break-glass:{by or 'operator'}"
+    token, meta = mint(conn, subject=subject, role=role, tenant=tenant, ttl=ttl, break_glass=True,
+                       note=f"{plane}: {reason.strip()}")
+    return token, meta
+
+
+class Denied(Exception):
+    """Refused, with the reason a caller can act on.
+
+    401 and 403 are kept apart deliberately. They need opposite responses: an unknown token means
+    sign in again, a known token without the grant means ask somebody for access. Telling a person
+    they lack a permission they actually hold sends them somewhere they cannot fix it.
+    """
+
+    def __init__(self, status: int, reason: str):
+        super().__init__(reason)
+        self.status = status
+        self.reason = reason
+
+
+def require(identity: dict | None, action: str) -> dict:
+    if identity is None:
+        raise Denied(401, "no valid token")
+    grants = GRANTS.get(identity["role"], frozenset())
+    if action not in grants:
+        raise Denied(403, f"role {identity['role']!r} cannot {action}")
+    return identity
+
+
+# --------------------------------------------------------------------------------------------
+# Quorum
+
+
+def record_approval(conn, *, decision_id: str, subject: str, verdict: str, reason: str) -> None:
+    # ON CONFLICT DO NOTHING, not INSERT OR IGNORE: the latter is SQLite-only and this runs on
+    # Postgres too, where it is a syntax error — and the ledger silently failing to record is how a
+    # two-person rule quietly becomes a one-person rule.
+    conn.execute(
+        "INSERT INTO approvals (decision_id, subject, verdict, reason, at) VALUES (?, ?, ?, ?, ?) "
+        "ON CONFLICT (decision_id, subject) DO NOTHING",
+        (decision_id, subject, verdict, reason, time.time()),
+    )
+    conn.commit()
+
+
+def approvals_for(conn, decision_id: str) -> list[dict]:
+    rows = conn.execute(
+        "SELECT subject, verdict, reason, at FROM approvals WHERE decision_id = ? ORDER BY at ASC",
+        (decision_id,),
+    ).fetchall()
+    return [{"subject": r["subject"], "verdict": r["verdict"], "reason": r["reason"], "at": r["at"]}
+            for r in rows]
+
+
+def needs_two(environment: str, enforcing: bool) -> bool:
+    """Production, and only where enforcement is actually on.
+
+    A shadow-mode hold blocks nothing. Requiring a second person to acknowledge one would train
+    everybody to click through both, which costs the quorum its meaning by the time it matters.
+    """
+    return enforcing and environment == "production"
+
+
+def quorum(conn, *, decision_id: str, environment: str, enforcing: bool) -> dict:
+    """Whether enough distinct people have answered, and who."""
+    got = approvals_for(conn, decision_id)
+    needed = 2 if needs_two(environment, enforcing) else 1
+    # Distinct subjects. Two tokens held by one person are one person; the ledger is keyed on
+    # subject precisely so that a second token cannot become a second approver.
+    people = []
+    for a in got:
+        if a["subject"] not in people:
+            people.append(a["subject"])
+    denied = [a for a in got if a["verdict"] == "deny"]
+    return {
+        "needed": needed,
+        "have": len(people),
+        "met": bool(denied) or len(people) >= needed,
+        "approvers": people,
+        # One refusal settles it. Waiting for a second person to agree that something should not
+        # happen would be an odd kind of safety.
+        "outcome": "deny" if denied else ("allow" if len(people) >= needed else "pending"),
+    }

underwrit/backup.py

@@ -0,0 +1,125 @@
+"""Backups that end in `verify_chain()`, and restores that refuse to overwrite quietly.
+
+A backup of an audit chain that is not verified is a file. Verified, it is evidence: the copy has
+the same hashes as the live log had at the moment of copying, and a restore that verifies clean is
+a restore of the record rather than of a database that happens to contain one.
+
+SQLite only, through the online backup API — a file copy of a database with a writer open is a
+corrupt database with the right name. On Postgres use `pg_dump`, then run `python3 -m underwrit verify`
+against the restored database; the verdict is the same function either way.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import shutil
+import sqlite3
+import time
+from pathlib import Path
+
+from . import chain, db
+
+
+def _sha256(path: Path) -> str:
+    h = hashlib.sha256()
+    with path.open("rb") as f:
+        for block in iter(lambda: f.read(1 << 20), b""):
+            h.update(block)
+    return h.hexdigest()
+
+
+def verify(db_path: str | Path) -> dict:
+    """The whole-chain verdict for a database file. Never `ok: true` for a file with no chain."""
+    p = Path(db_path)
+    if not db.is_postgres() and not p.exists():
+        return {"ok": None, "checked": 0, "brokenAt": None, "detail": f"{p} does not exist"}
+    c = db.connect(p)
+    try:
+        if db.is_postgres():
+            tables = {r["name"] for r in c.execute(
+                "SELECT table_name AS name FROM information_schema.tables WHERE table_schema = 'public'")}
+        else:
+            tables = {r["name"] for r in c.execute("SELECT name FROM sqlite_master WHERE type = 'table'")}
+        if "audit_log" not in tables:
+            return {"ok": None, "checked": 0, "brokenAt": None,
+                    "detail": "no audit_log table — this is not a underwrit database"}
+        result = chain.verify_chain(c)
+        if result.get("checked") == 0 and result.get("ok"):
+            # An empty chain verifies vacuously. Say so instead of reporting a pass.
+            result = {**result, "ok": None, "detail": "the chain is empty — nothing to verify"}
+        if "checkpoints" in tables:
+            # The chain hashes agree with themselves; does the tree agree with what was signed and
+            # what the witness saw? A restore of an older copy passes the chain check and still
+            # leaves every later checkpoint refused by the witness ("the log shrank").
+            from . import checkpoint as cp_mod, merkle
+            latest = cp_mod.latest(c)
+            lv = cp_mod.leaves(c)
+            result["size"] = len(lv)
+            if latest:
+                result["checkpoint"] = {"size": latest["size"], "keyId": latest["keyId"],
+                                        "matchesTree": latest["size"] == len(lv) and latest["root"] == merkle.root(lv).hex()}
+                if latest["size"] > len(lv):
+                    result["ok"] = False
+                    result["detail"] = (f"the latest checkpoint covers {latest['size']} entries but the log holds "
+                                        f"{len(lv)}: this copy is older than what was already signed")
+            states = cp_mod.witness_states(c) if "witness_states" in tables else []
+            if states:
+                witnessed = max(st["size"] for st in states)
+                result["witnessedSize"] = witnessed
+                result["behindWitness"] = witnessed > len(lv)
+                if witnessed > len(lv):
+                    result["detail"] = ((result.get("detail") or "") + " " if result.get("detail") else "") + (
+                        f"a witness has cosigned size {witnessed}; restoring this copy ({len(lv)} entries) will make "
+                        f"every later checkpoint refused as a shrunk log until the witness is re-pinned by an operator")
+        return result
+    finally:
+        c.close()
+
+
+def backup(db_path: str | Path, dest: str | Path) -> dict:
+    """Copy the live database with the online backup API, then verify the copy."""
+    if db.is_postgres():
+        raise RuntimeError("DATABASE_URL is set: back up with pg_dump, then `python3 -m underwrit verify`")
+    src_path, dest_path = Path(db_path), Path(dest)
+    if not src_path.exists():
+        raise FileNotFoundError(f"{src_path} does not exist")
+    dest_path.parent.mkdir(parents=True, exist_ok=True)
+    src = sqlite3.connect(str(src_path))
+    dst = sqlite3.connect(str(dest_path))
+    try:
+        src.backup(dst)
+    finally:
+        dst.close()
+        src.close()
+    result = {
+        "source": str(src_path), "path": str(dest_path), "bytes": dest_path.stat().st_size,
+        "sha256": _sha256(dest_path), "at": time.time(), "chain": verify(dest_path),
+    }
+    Path(str(dest_path) + ".sha256").write_text(f"{result['sha256']}  {dest_path.name}\n")
+    return result
+
+
+def restore(src: str | Path, db_path: str | Path, *, force: bool = False) -> dict:
+    """Put a backup in place of the live database, then verify what is now live.
+
+    Refuses to overwrite a non-empty database unless told to. Stop the service first: a restore
+    under a running writer is a race that ends with two chains in one file.
+    """
+    if db.is_postgres():
+        raise RuntimeError("DATABASE_URL is set: restore with pg_restore, then `python3 -m underwrit verify`")
+    src_path, dest_path = Path(src), Path(db_path)
+    if not src_path.exists():
+        raise FileNotFoundError(f"{src_path} does not exist")
+    if dest_path.exists() and dest_path.stat().st_size > 0 and not force:
+        raise FileExistsError(f"{dest_path} exists and is not empty; pass force=True to replace it")
+    expected = verify(src_path)
+    dest_path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = dest_path.with_suffix(dest_path.suffix + ".restoring")
+    shutil.copyfile(src_path, tmp)
+    tmp.replace(dest_path)
+    for side in ("-wal", "-shm"):
+        stale = Path(str(dest_path) + side)
+        if stale.exists():
+            stale.unlink()
+    return {"source": str(src_path), "path": str(dest_path), "sha256": _sha256(dest_path),
+            "at": time.time(), "sourceChain": expected, "chain": verify(dest_path)}

underwrit/bundle.py

@@ -0,0 +1,110 @@
+"""Zip an evidence pack in memory, as format version 2.
+
+Written to a buffer rather than a temp directory because the bundle is served over HTTP and a file
+on disk between assembly and response is a copy of somebody's record sitting where nobody is
+managing its retention.
+
+Version 2 adds three things to the pack: a signed checkpoint over the whole log (size and Merkle
+root), an inclusion proof per entry against that root, and an Ed25519 signature over the manifest.
+The proofs are computed here and handed to `evidence.build`, which never queries anything but the
+chain tables — the tree lives in `checkpoint.py`.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import io
+import json
+import zipfile
+
+from . import checkpoint as cp_mod, ed25519, evidence
+from .subject import Subject
+
+
+def tree_for(conn, entries: list[dict], key: cp_mod.Key | None) -> dict | None:
+    """Proofs for these entries against a checkpoint signed now. None when there is no key."""
+    if key is None:
+        return None
+    snapshot = cp_mod.tree(conn)
+    view, proofs = cp_mod.inclusion_for(conn, [e["seq"] for e in entries], snapshot=snapshot)
+    latest = cp_mod.latest(conn)
+    if not latest or latest["size"] != view["size"] or latest["root"] != view["root"]:
+        # Sign the very leaves the proofs were built from: an append between the two reads must
+        # not leave honest proofs pointing at a tree the signature does not cover.
+        latest = cp_mod.issue(conn, key, snapshot[1])
+    note, witnessed = latest["note"], None
+    state = cp_mod.witness_state(conn)
+    if state and state.get("fork"):
+        witnessed = {"fork": True, "size": state["size"], "roots": state["roots"], "witnesses": state["detail"],
+                     "note": "witnesses disagree on the root at this size; no cosignature is shipped "
+                             "until the fork is resolved by an operator"}
+    elif state and state["size"] == latest["size"] and state["root"] == latest["root"]:
+        # The witness has cosigned this exact tree: ship the cosigned note, so the bundle carries
+        # a second party's statement that this history is the one it saw.
+        note, witnessed = state["cosignedNote"], {"witness": state["witness"], "at": state["at"]}
+    elif state:
+        # The witness saw an earlier size. The bundle says so, and an auditor can ask the control
+        # plane for the consistency proof from that size — the tree here must extend it.
+        witnessed = {"witness": state["witness"], "at": state["at"], "size": state["size"],
+                     "root": state["root"], "note": "witnessed at an earlier size; this checkpoint must be "
+                                                     "consistent with it"}
+    if witnessed and not witnessed.get("fork") and state.get("witnesses"):
+        witnessed["witnesses"] = state["witnesses"]
+    return {"size": latest["size"], "root": latest["root"], "note": note,
+            "keyId": latest["keyId"], "issuedAt": latest["at"], "proofs": proofs,
+            "key": key.public_json(), "witnessed": witnessed,
+            "timestamps": cp_mod.timestamps_for(conn, latest["size"], latest["root"])}
+
+
+def files_for(conn, subject: Subject, key: cp_mod.Key | None) -> tuple[dict, dict[str, bytes]]:
+    entries = evidence.entries_for(conn, subject)
+    tree = tree_for(conn, entries, key)
+    pack = evidence.build(conn, subject, tree=tree, entries=entries)
+    files = {
+        "evidence.json": json.dumps(pack, indent=2, sort_keys=True).encode("utf-8"),
+        "README.md": evidence.readme(pack).encode("utf-8"),
+        "verify.py": evidence.verifier().encode("utf-8"),
+    }
+    if tree:
+        files["checkpoint"] = tree["note"].encode("utf-8")
+        # External clocks, as the original bytes: `openssl ts -verify` and the ots client read these.
+        for t in tree.get("timestamps") or []:
+            name = {"rfc3161": "timestamps/checkpoint.tsr", "ots": "timestamps/checkpoint.ots"}.get(t["kind"])
+            if name and name not in files:
+                files[name] = base64.b64decode(t["token"])
+    return pack, files
+
+
+def manifest_for(files: dict[str, bytes], key: cp_mod.Key | None) -> dict:
+    """Digests of every file but itself, signed. A manifest cannot contain its own digest."""
+    manifest: dict = {"format": evidence.FORMAT_VERSION,
+                      "files": {n: hashlib.sha256(d).hexdigest() for n, d in files.items()}}
+    body = evidence.canonical(manifest["files"])
+    if key is not None:
+        manifest["signatures"] = [{
+            "alg": "ed25519", "keyId": key.key_id, "origin": key.origin,
+            "publicKey": base64.b64encode(key.public).decode(),
+            "signature": base64.b64encode(ed25519.fast_sign(key.seed, body)).decode(),
+        }]
+    legacy = evidence.signing_key()
+    if legacy:
+        # The version-1 HMAC, kept for verifiers that share the secret. It proves origin only to
+        # a party who could have forged it, which is why version 2 signs asymmetrically.
+        manifest["signature"] = hmac.new(legacy.encode("utf-8"), body, hashlib.sha256).hexdigest()
+    return manifest
+
+
+def zip_for(conn, subject: Subject, key: cp_mod.Key | None = None) -> tuple[bytes, str]:
+    _, files = files_for(conn, subject, key)
+    files["manifest.json"] = json.dumps(manifest_for(files, key), indent=2, sort_keys=True).encode("utf-8")
+    buf = io.BytesIO()
+    # Deterministic: a fixed timestamp so the same pack zips to the same bytes, which is what lets
+    # two people compare bundles by digest rather than by unpacking them.
+    with zipfile.ZipFile(buf, "w", zipfile.ZIP_DEFLATED) as z:
+        for name in sorted(files):
+            info = zipfile.ZipInfo(name, date_time=(1980, 1, 1, 0, 0, 0))
+            info.external_attr = 0o644 << 16
+            z.writestr(info, files[name])
+    return buf.getvalue(), f"underwrit-{subject.id}.zip"