underwrit 0.3.0__py3-none-any.whl

underwrit/checkpoint.py

@@ -0,0 +1,428 @@
+"""Signed checkpoints over the chain, and the key that signs them.
+
+A checkpoint is a commitment to the whole log at one moment: its size and its Merkle root, signed
+by the data plane's log key. It is the thing a bundle's inclusion proofs are checked against, the
+thing a witness cosigns, and the thing an auditor keeps from one visit to the next so that the
+consistency proof at the next visit shows the log only grew.
+
+Format: the C2SP signed-note checkpoint (https://c2sp.org/tlog-checkpoint), which is what Sigstore
+and Go's transparency logs use and what any witness in that ecosystem expects:
+
+    underwrit/<node>            origin line
+    <tree size>            ASCII decimal
+    <root, base64>
+
+    — underwrit/<node> <base64(key hash[4] ‖ Ed25519 signature)>
+
+The leaf for entry i is `SHA-256(0x00 ‖ hash_i)` where `hash_i` is the entry's own chain hash as
+hex bytes — so the tree commits to exactly what the chain commits to, and the two verify each other.
+
+**The key lives in a file, not the database.** A database is backed up and copied; a key in it
+is a key in every copy. The file is created 0600 on first start unless `UNDERWRIT_SIGNING_KEY_FILE`
+points at one an operator provisioned (a mounted secret, a KMS-fetched file). The public key and
+its id are served openly at `/v1/keys` and shipped in every bundle — and a verifier that has only
+the bundle's copy proves self-consistency, not origin, which is why `verify.py` says so and accepts
+a pinned key.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import os
+import time
+from pathlib import Path
+
+from . import db, ed25519, merkle
+
+SCHEMA = [
+    """CREATE TABLE IF NOT EXISTS checkpoints (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        size INTEGER NOT NULL,
+        root TEXT NOT NULL,
+        note TEXT NOT NULL,
+        key_id TEXT NOT NULL,
+        at REAL NOT NULL
+    )""",
+    "CREATE INDEX IF NOT EXISTS checkpoints_size ON checkpoints (size)",
+    # The last checkpoint each witness cosigned, keyed by where we send checkpoints. The primary
+    # witness is the control plane ("control"); UNDERWRIT_WITNESSES adds more. Each row holds that
+    # witness's cosigned note; `witness_state()` merges the lines of every witness at the latest
+    # size into one note, which is what the bundle ships.
+    """CREATE TABLE IF NOT EXISTS witness_states (
+        url TEXT PRIMARY KEY,
+        witness TEXT NOT NULL DEFAULT '',
+        size INTEGER NOT NULL,
+        root TEXT NOT NULL,
+        cosigned_note TEXT NOT NULL,
+        at REAL NOT NULL
+    )""",
+    # External clocks: RFC 3161 time-stamp tokens and OpenTimestamps proofs over a checkpoint's
+    # body. The token is stored whole (base64) so the bundle ships the original bytes.
+    """CREATE TABLE IF NOT EXISTS timestamps (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        size INTEGER NOT NULL,
+        root TEXT NOT NULL,
+        kind TEXT NOT NULL,
+        token TEXT NOT NULL,
+        meta_json TEXT NOT NULL DEFAULT '{}',
+        at REAL NOT NULL
+    )""",
+    "CREATE INDEX IF NOT EXISTS timestamps_size ON timestamps (size, root)",
+    # Every key that has signed a checkpoint on this plane, so a bundle from before a rotation can
+    # still be pinned and an auditor can see when each key was in use.
+    """CREATE TABLE IF NOT EXISTS log_keys (
+        key_id TEXT PRIMARY KEY,
+        public_key TEXT NOT NULL,
+        origin TEXT NOT NULL DEFAULT '',
+        first_seen REAL NOT NULL,
+        last_seen REAL NOT NULL
+    )""",
+]
+
+
+def init(conn) -> None:
+    for ddl in SCHEMA:
+        conn.execute(db.ddl(ddl))
+    conn.commit()
+
+
+# --------------------------------------------------------------------------------------------
+# Keys
+
+
+class Key:
+    def __init__(self, seed: bytes, origin: str):
+        self.seed = seed
+        self.public = ed25519.public_key(seed)
+        self.origin = origin
+
+    @property
+    def key_hash(self) -> bytes:
+        """C2SP signed-note key hash: first four bytes of SHA-256(name ‖ 0x0A ‖ 0x01 ‖ public key)."""
+        return hashlib.sha256(self.origin.encode() + b"\n\x01" + self.public).digest()[:4]
+
+    @property
+    def cosig_key_hash(self) -> bytes:
+        """The key hash a witness line carries: SHA-256(name ‖ 0x0A ‖ 0x04 ‖ public key)[:4]. C2SP
+        gives cosignature/v1 keys their own algorithm byte (0x04) so external tooling can tell a
+        witness line from a log line by its hash."""
+        return hashlib.sha256(self.origin.encode() + b"\n\x04" + self.public).digest()[:4]
+
+    @property
+    def key_id(self) -> str:
+        return self.key_hash.hex()
+
+    @property
+    def cosig_key_id(self) -> str:
+        return self.cosig_key_hash.hex()
+
+    def public_json(self) -> dict:
+        return {"alg": "ed25519", "keyId": self.key_id, "cosigKeyId": self.cosig_key_id, "origin": self.origin,
+                "publicKey": base64.b64encode(self.public).decode(),
+                "fingerprint": hashlib.sha256(self.public).hexdigest()}
+
+
+def load_or_create(path: str | Path, origin: str) -> tuple[Key, bool]:
+    """The log key from `path`, created if absent. Returns (key, created)."""
+    p = Path(path)
+    if p.exists() and p.read_text().strip():
+        seed = bytes.fromhex(p.read_text().strip())
+        return Key(seed, origin), False
+    seed = ed25519.generate_seed()
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(seed.hex() + "\n")
+    try:
+        os.chmod(p, 0o600)
+    except OSError:
+        pass
+    return Key(seed, origin), True
+
+
+def default_key_path(db_path: str) -> str:
+    return os.environ.get("UNDERWRIT_SIGNING_KEY_FILE") or str(Path(db_path).with_suffix(".signing.key"))
+
+
+# --------------------------------------------------------------------------------------------
+# The tree over the chain
+
+
+def leaves(conn) -> list[bytes]:
+    """One leaf per live chain entry, in sequence order."""
+    rows = conn.execute("SELECT hash FROM audit_log ORDER BY seq ASC").fetchall()
+    return [merkle.leaf_hash((r["hash"] or "").encode("ascii")) for r in rows]
+
+
+def seqs(conn) -> list[int]:
+    return [int(r["seq"]) for r in conn.execute("SELECT seq FROM audit_log ORDER BY seq ASC")]
+
+
+def tree(conn) -> tuple[list[int], list[bytes]]:
+    """(sequence numbers, leaves) so a caller can map a seq to its leaf index."""
+    rows = conn.execute("SELECT seq, hash FROM audit_log ORDER BY seq ASC").fetchall()
+    return ([int(r["seq"]) for r in rows],
+            [merkle.leaf_hash((r["hash"] or "").encode("ascii")) for r in rows])
+
+
+# --------------------------------------------------------------------------------------------
+# Notes
+
+
+def note_body(origin: str, size: int, root: bytes) -> str:
+    return f"{origin}\n{size}\n{base64.b64encode(root).decode()}\n"
+
+
+def sign_note(key: Key, size: int, root: bytes) -> str:
+    body = note_body(key.origin, size, root)
+    sig = ed25519.fast_sign(key.seed, body.encode())
+    line = f"— {key.origin} {base64.b64encode(key.key_hash + sig).decode()}"
+    return body + "\n" + line + "\n"
+
+
+def parse_note(note: str) -> dict:
+    """{origin, size, root (bytes), signatures: [(name, keyHash hex, sig bytes)]}."""
+    body, _, sigs = note.partition("\n\n")
+    lines = body.split("\n")
+    if len(lines) < 3:
+        raise ValueError("checkpoint note is too short")
+    out = {"origin": lines[0], "size": int(lines[1]), "root": base64.b64decode(lines[2]),
+           "signatures": []}
+    for line in sigs.splitlines():
+        if not line.startswith("— "):
+            continue
+        _, name, blob = line.split(" ", 2)
+        raw = base64.b64decode(blob)
+        out["signatures"].append((name, raw[:4].hex(), raw[4:]))
+    return out
+
+
+def verify_note(note: str, public: bytes, origin: str) -> bool:
+    """True when a signature by `public` for `origin` covers the note body."""
+    parsed = parse_note(note)
+    body = note_body(parsed["origin"], parsed["size"], parsed["root"]).encode()
+    want = hashlib.sha256(origin.encode() + b"\n\x01" + public).digest()[:4].hex()
+    return any(name == origin and kh == want and ed25519.fast_verify(public, body, sig)
+               for name, kh, sig in parsed["signatures"])
+
+
+# --------------------------------------------------------------------------------------------
+# Issuing
+
+
+def issue(conn, key: Key, lv: list[bytes] | None = None) -> dict:
+    """Sign the log as it stands now (or as the given leaf snapshot) and record the checkpoint."""
+    lv = leaves(conn) if lv is None else lv
+    root = merkle.root(lv)
+    note = sign_note(key, len(lv), root)
+    now = time.time()
+    conn.execute("INSERT INTO checkpoints (size, root, note, key_id, at) VALUES (?, ?, ?, ?, ?)",
+                 (len(lv), root.hex(), note, key.key_id, now))
+    conn.execute("INSERT INTO log_keys (key_id, public_key, origin, first_seen, last_seen) VALUES (?, ?, ?, ?, ?) "
+                 "ON CONFLICT (key_id) DO UPDATE SET last_seen = excluded.last_seen",
+                 (key.key_id, base64.b64encode(key.public).decode(), key.origin, now, now))
+    conn.commit()
+    return {"size": len(lv), "root": root.hex(), "note": note, "keyId": key.key_id, "at": now}
+
+
+def key_history(conn) -> list[dict]:
+    rows = conn.execute("SELECT * FROM log_keys ORDER BY first_seen ASC").fetchall()
+    return [{"alg": "ed25519", "keyId": r["key_id"], "publicKey": r["public_key"], "origin": r["origin"],
+             "firstSeen": r["first_seen"], "lastSeen": r["last_seen"]} for r in rows]
+
+
+def latest(conn) -> dict | None:
+    r = conn.execute("SELECT * FROM checkpoints ORDER BY id DESC LIMIT 1").fetchone()
+    return ({"size": r["size"], "root": r["root"], "note": r["note"], "keyId": r["key_id"],
+             "at": r["at"]} if r else None)
+
+
+def history(conn, limit: int = 50) -> list[dict]:
+    rows = conn.execute("SELECT * FROM checkpoints ORDER BY id DESC LIMIT ?", (limit,)).fetchall()
+    return [{"size": r["size"], "root": r["root"], "keyId": r["key_id"], "at": r["at"]} for r in rows]
+
+
+def consistency(conn, old_size: int) -> dict:
+    """A consistency proof from an earlier size to the log as it stands now."""
+    lv = leaves(conn)
+    if old_size < 1 or old_size > len(lv):
+        raise ValueError(f"old size {old_size} outside 1..{len(lv)}")
+    proof = merkle.consistency_proof(old_size, lv)
+    return {"oldSize": old_size, "newSize": len(lv), "oldRoot": merkle.root(lv[:old_size]).hex(),
+            "newRoot": merkle.root(lv).hex(), "proof": [p.hex() for p in proof]}
+
+
+def inclusion_for(conn, wanted_seqs: list[int], snapshot: tuple[list[int], list[bytes]] | None = None
+                  ) -> tuple[dict, dict[int, dict]]:
+    """A fresh unsigned tree view plus, for each wanted seq, its leaf index and inclusion proof.
+
+    Unsigned: the caller signs the checkpoint (or uses one already issued at this size) so the
+    tree the proofs are against is the tree the signature covers. Pass `snapshot` (from `tree()`)
+    to build the proofs and the checkpoint from one read of the log.
+    """
+    all_seqs, lv = snapshot if snapshot is not None else tree(conn)
+    index_of = {s: i for i, s in enumerate(all_seqs)}
+    root = merkle.root(lv)
+    out: dict[int, dict] = {}
+    for s in wanted_seqs:
+        i = index_of.get(s)
+        if i is None:
+            continue  # not in the live log (sealed into the archive): no place in this tree
+        out[s] = {"leafIndex": i, "proof": [p.hex() for p in merkle.inclusion_proof(i, lv)]}
+    return {"size": len(lv), "root": root.hex()}, out
+
+
+# --------------------------------------------------------------------------------------------
+# Cosignatures (https://c2sp.org/tlog-cosignature)
+#
+# A cosignature is a witness's statement: "as of time T, the largest consistent tree I have seen
+# for this log has this size and root." It is a signature over
+#
+#     cosignature/v1
+#     time <unix seconds>
+#     <the checkpoint body>
+#
+# carried as a signed-note line whose blob is key hash[4] ‖ time (8 bytes, big-endian) ‖ Ed25519
+# signature. Verifiers ignore signature lines from names they do not know, so a log signature and
+# any number of cosignatures share one note.
+
+COSIG_PREFIX = "cosignature/v1\n"
+
+
+def cosign_note(witness: Key, note: str, at: float | None = None) -> str:
+    """Append this witness's cosignature line to a checkpoint note."""
+    parsed = parse_note(note)
+    body = note_body(parsed["origin"], parsed["size"], parsed["root"])
+    t = int(time.time() if at is None else at)
+    msg = f"{COSIG_PREFIX}time {t}\n{body}".encode()
+    sig = ed25519.fast_sign(witness.seed, msg)
+    blob = witness.cosig_key_hash + t.to_bytes(8, "big") + sig
+    line = f"— {witness.origin} {base64.b64encode(blob).decode()}"
+    return note.rstrip("\n") + "\n" + line + "\n"
+
+
+def verify_cosignature(note: str, witness_public: bytes, witness_origin: str) -> int | None:
+    """The cosignature's timestamp when `witness_origin` cosigned this note, else None."""
+    parsed = parse_note(note)
+    body = note_body(parsed["origin"], parsed["size"], parsed["root"])
+    want = hashlib.sha256(witness_origin.encode() + b"\n\x04" + witness_public).digest()[:4].hex()
+    for name, kh, rest in parsed["signatures"]:
+        if name != witness_origin or kh != want or len(rest) != 72:
+            continue
+        t = int.from_bytes(rest[:8], "big")
+        msg = f"{COSIG_PREFIX}time {t}\n{body}".encode()
+        if ed25519.fast_verify(witness_public, msg, rest[8:]):
+            return t
+    return None
+
+
+def witness_states(conn) -> list[dict]:
+    """What each configured witness last cosigned."""
+    rows = conn.execute("SELECT * FROM witness_states ORDER BY url").fetchall()
+    return [{"url": r["url"], "witness": r["witness"], "size": r["size"], "root": r["root"],
+             "cosignedNote": r["cosigned_note"], "at": r["at"]} for r in rows]
+
+
+def witness_state_for(conn, url: str) -> dict | None:
+    r = conn.execute("SELECT * FROM witness_states WHERE url = ?", (url,)).fetchone()
+    return ({"url": r["url"], "witness": r["witness"], "size": r["size"], "root": r["root"],
+             "cosignedNote": r["cosigned_note"], "at": r["at"]} if r else None)
+
+
+def merge_notes(notes: list[str]) -> str:
+    """One note carrying every distinct signature line of several notes over the same body."""
+    if not notes:
+        return ""
+    body, _, _ = notes[0].partition("\n\n")
+    lines: list[str] = []
+    for n in notes:
+        b, _, sigs = n.partition("\n\n")
+        if b != body:
+            continue
+        for line in sigs.splitlines():
+            if line.startswith("— ") and line not in lines:
+                lines.append(line)
+    return body + "\n\n" + "\n".join(lines) + "\n"
+
+
+def witness_state(conn) -> dict | None:
+    """The witnessed view at the largest size any witness has cosigned: the merged note of every
+    witness at that exact tree, with their origins. None until a witness has cosigned anything."""
+    states = witness_states(conn)
+    if not states:
+        return None
+    # A fork: two witnesses cosigned different roots at the same size. That is the split-view
+    # event witnesses exist to expose; it is surfaced, never merged or ranked away.
+    by_size: dict[int, set[str]] = {}
+    for st in states:
+        by_size.setdefault(st["size"], set()).add(st["root"])
+    forks = {n: roots for n, roots in by_size.items() if len(roots) > 1}
+    if forks:
+        n = max(forks)
+        return {"fork": True, "size": n, "roots": sorted(forks[n]), "cosignedNote": "",
+                "witness": "", "witnesses": [], "at": max(st["at"] for st in states),
+                "detail": [{"witness": st["witness"], "url": st["url"], "size": st["size"], "root": st["root"]}
+                           for st in states if st["size"] == n],
+                "behind": []}
+    top = max(states, key=lambda st: (st["size"], st["at"]))
+    at_top = [st for st in states if st["size"] == top["size"] and st["root"] == top["root"]]
+    return {"size": top["size"], "root": top["root"], "cosignedNote": merge_notes([st["cosignedNote"] for st in at_top]),
+            "witness": ", ".join(st["witness"] for st in at_top), "witnesses": [st["witness"] for st in at_top],
+            "at": max(st["at"] for st in at_top),
+            "behind": [{"witness": st["witness"], "url": st["url"], "size": st["size"]}
+                       for st in states if st not in at_top]}
+
+
+def save_witness_state(conn, *, size: int, root: str, cosigned_note: str, witness: str, url: str = "control") -> None:
+    conn.execute("INSERT INTO witness_states (url, witness, size, root, cosigned_note, at) VALUES (?, ?, ?, ?, ?, ?) "
+                 "ON CONFLICT (url) DO UPDATE SET witness = excluded.witness, size = excluded.size, "
+                 "root = excluded.root, cosigned_note = excluded.cosigned_note, at = excluded.at",
+                 (url, witness, size, root, cosigned_note, time.time()))
+    conn.commit()
+
+
+# --------------------------------------------------------------------------------------------
+# External clocks
+
+
+def imprint(cp: dict) -> bytes:
+    """What a time-stamping authority signs over: SHA-256 of the checkpoint body. The TSA sees
+    only this digest, never the note — nothing about the log leaves the plane."""
+    body = note_body(parse_note(cp["note"])["origin"], cp["size"], bytes.fromhex(cp["root"]))
+    return hashlib.sha256(body.encode()).digest()
+
+
+def timestamps_for(conn, size: int, root: str) -> list[dict]:
+    rows = conn.execute("SELECT * FROM timestamps WHERE size = ? AND root = ? ORDER BY id", (size, root)).fetchall()
+    return [{"kind": r["kind"], "token": r["token"], "at": r["at"], **json.loads(r["meta_json"] or "{}")}
+            for r in rows]
+
+
+def anchor(conn, cp: dict) -> list[dict]:
+    """Ask every configured external clock to stamp this checkpoint; store what comes back.
+
+    Idempotent per (size, root): a checkpoint re-issued at the same tree is not re-stamped.
+    Failures are silent here (the plane logs them); a bundle says which clocks it carries.
+    """
+    from . import tsa
+
+    have = {t["kind"] for t in timestamps_for(conn, cp["size"], cp["root"])}
+    out = []
+    digest = imprint(cp)
+    if "rfc3161" not in have:
+        tok = tsa.stamp(digest)
+        if tok:
+            meta = {k: tok.get(k) for k in ("tsa", "genTime", "serial", "imprint", "status", "hashAlg")}
+            conn.execute("INSERT INTO timestamps (size, root, kind, token, meta_json, at) VALUES (?, ?, ?, ?, ?, ?)",
+                         (cp["size"], cp["root"], "rfc3161", tok["token"], json.dumps(meta), time.time()))
+            out.append({"kind": "rfc3161", **meta})
+    if "ots" not in have:
+        proof = tsa.ots_submit(digest)
+        if proof:
+            meta = {k: proof[k] for k in ("calendar", "status", "submittedAt", "note")}
+            conn.execute("INSERT INTO timestamps (size, root, kind, token, meta_json, at) VALUES (?, ?, ?, ?, ?, ?)",
+                         (cp["size"], cp["root"], "ots", proof["proof"], json.dumps(meta), time.time()))
+            out.append({"kind": "ots", **meta})
+    if out:
+        conn.commit()
+    return out

underwrit/cli.py

@@ -0,0 +1,155 @@
+"""Entry points.
+
+    python3 -m underwrit serve [port]        # data plane    :8787
+    python3 -m underwrit control [port]      # control plane :8788
+    python3 -m underwrit demo                # drive sessions through a running data plane
+    python3 -m underwrit demo --live         # the incident scenario, live, waiting on the console
+    python3 -m underwrit demo-stack          # both planes + console + seeded data + sign-in links
+    python3 -m underwrit migrate             # apply schema migrations and print the versions
+    python3 -m underwrit verify [db]         # whole-chain verdict for a database file
+    python3 -m underwrit backup <dest>       # online copy of the data plane database, verified
+    python3 -m underwrit restore <src> [--force]   # put a backup in place; ends in verify_chain()
+    python3 -m underwrit sweep [--dry-run]   # run a retention sweep now
+    python3 -m underwrit mcp                 # serve the data plane as MCP tools over stdio
+    python3 -m underwrit policy-diff cand.json   # the shadow report for a candidate policy, from the CLI
+    python3 -m underwrit break-glass --plane data|control --reason "..." [--role admin] [--ttl 3600]
+
+Environment: UNDERWRIT_DB, UNDERWRIT_CONTROL_DB, UNDERWRIT_CONTROL_URL, UNDERWRIT_NODE_TOKEN[_FILE], UNDERWRIT_HOST,
+UNDERWRIT_RETENTION_DAYS, UNDERWRIT_RETENTION, UNDERWRIT_RATE_LIMIT_PER_MINUTE, UNDERWRIT_TOKEN_TTL_SECONDS.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+
+def _out(obj) -> None:
+    print(json.dumps(obj, indent=2, sort_keys=True, default=str), flush=True)
+
+
+def _enterprise(cmd: str, rest: list, port) -> int:
+    """Hand a command to Underwrit Control Plane when it is installed; say so plainly when it is not."""
+    try:
+        from underwrit_controlplane import cli as ecli
+    except ImportError:
+        print(f"`underwrit {cmd}` needs Underwrit Control Plane (the control plane, console and stack), which is "
+              "licensed commercially and distributed as container images, not on PyPI: see https://underwrit.io/#pricing. "
+              "The data plane runs alone with `underwrit serve`.", file=sys.stderr)
+        return 2
+    return ecli.main([cmd, *([str(port)] if port else []), *rest])
+
+
+def main(argv=None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    cmd = argv[0] if argv else "serve"
+    rest = argv[1:]
+    port = int(rest[0]) if rest and rest[0].isdigit() else None
+
+    if cmd == "serve":
+        from . import api
+        api.serve(port=port or 8787)
+    elif cmd == "control":
+        return _enterprise("control", rest, port)
+    elif cmd == "demo":
+        from .demo import run
+        return run()
+    elif cmd == "demo-stack":
+        return _enterprise("demo-stack", rest, port)
+    elif cmd == "mcp":
+        from . import mcp
+        return mcp.main()
+    elif cmd == "migrate":
+        from . import api, db, migrate
+        c = db.connect(api.DB_PATH)
+        _out({"dataPlane": {"db": api.DB_PATH, "applied": migrate.data_plane(c),
+                            "version": migrate.current(c, "data-plane")}})
+        try:
+            from underwrit_controlplane import control  # the commercial control plane, when installed
+        except ImportError:
+            control = None
+        if control is not None:
+            cc = db.connect(control.DB_PATH)
+            _out({"controlPlane": {"db": control.DB_PATH, "applied": control.migrate_db(cc),
+                                   "version": migrate.current(cc, "control-plane")}})
+    elif cmd == "verify":
+        from . import api, backup
+        r = backup.verify(rest[0] if rest else api.DB_PATH)
+        _out(r)
+        return 0 if r.get("ok") else 1
+    elif cmd == "backup":
+        if not rest:
+            print("usage: python3 -m underwrit backup <dest>", file=sys.stderr)
+            return 2
+        from . import api, backup
+        r = backup.backup(api.DB_PATH, rest[0])
+        _out(r)
+        return 0 if r["chain"].get("ok") is not False else 1
+    elif cmd == "restore":
+        if not rest:
+            print("usage: python3 -m underwrit restore <src> [--force]", file=sys.stderr)
+            return 2
+        from . import api, backup
+        r = backup.restore(rest[0], api.DB_PATH, force="--force" in rest)
+        _out(r)
+        return 0 if r["chain"].get("ok") else 1
+    elif cmd == "break-glass":
+        import getpass
+        opts = {rest[i].lstrip("-"): rest[i + 1] for i in range(0, len(rest) - 1, 2) if rest[i].startswith("--")}
+        plane = opts.get("plane", "data")
+        reason = opts.get("reason", "")
+        if not reason:
+            print("break glass needs --reason; it goes in the record", file=sys.stderr)
+            return 2
+        from . import auth, chain, db
+        who = opts.get("by") or getpass.getuser()
+        ttl = float(opts.get("ttl", "3600"))
+        role = opts.get("role", "admin")
+        if plane == "control":
+            try:
+                from underwrit_controlplane import control
+            except ImportError:
+                print("the control plane is part of Underwrit Control Plane, licensed commercially and shipped as container images, not on PyPI", file=sys.stderr)
+                return 2
+            token, meta = control.mint_break_glass(reason=reason, by=who, role=role, ttl=ttl, tenant=opts.get("tenant", ""))
+        else:
+            from . import api
+            c = api.conn()
+            token, meta = auth.break_glass(c, plane="data", reason=reason, by=who, role=role, ttl=ttl)
+            chain.record(c, actor=meta["subject"], actor_id=meta["id"], action="token.break_glass",
+                         outcome="allowed", environment="", target=meta["subject"], reason=reason,
+                         detail={"role": role, "ttlSeconds": ttl, "plane": "data"}, source_ip="")
+        print(f"BREAK GLASS — {plane} plane, role {role}, {int(ttl // 60)} minutes, taken by {who}")
+        print(f"  reason: {reason}")
+        print(f"  every request made with this credential is recorded by name.")
+        print(f"  {token}")
+        print(f"  revoke early: POST /v1/tokens/{meta['id']}/revoke")
+    elif cmd == "policy-diff":
+        if not rest:
+            print("usage: python3 -m underwrit policy-diff <candidate.json>", file=sys.stderr)
+            return 2
+        from . import api, policy as policy_mod, replay
+        current, _ = api.current_policy()
+        doc = json.loads(open(rest[0]).read())
+        candidate = policy_mod.Policy.from_json({**current.to_json(), **doc})
+        r = replay.replay(api.conn(), candidate, attribute_changes=True, current=current)
+        print(f"  {r['decisions']} decisions in {r['sessions']} sessions re-judged")
+        print(f"  callers stopped: {r['interrupts']['was']} -> {r['interrupts']['would']}")
+        for k, v in (r.get("attribution") or {}).items():
+            print(f"    {k:<22} moved {v['changed']:>4}   stopped {v['interruptsWas']} -> {v['interruptsWould']}")
+        for c in r["changed"][:50]:
+            print(f"  {c['sessionId']:<18} {c['tool']:<28} {c['was']:<15} -> {c['would']:<15} {c['reasons'][0][:70] if c['reasons'] else ''}")
+        if len(r["changed"]) > 50:
+            print(f"  … and {len(r['changed']) - 50} more")
+        return 0 if not r["changed"] else 3
+    elif cmd == "sweep":
+        from . import api, retention
+        r = retention.sweep(api.conn(), actor="operator:cli", dry_run="--dry-run" in rest)
+        _out(r)
+    elif cmd in ("version", "--version"):
+        from . import __version__
+        print(__version__)
+    else:
+        print(__doc__)
+        return 2
+    return 0