codeimprint 0.5.0a11__py3-none-any.whl

codeimprint_cli/chainseal.py

@@ -0,0 +1,175 @@
+"""Incremental Git seals, the project chain and offline-safe hooks (client side).
+
+The server's protocol (see docs/how-sealing-works.md): send the commit's file list (paths and
+Git blob IDs), upload only the blobs the server asks for, let it prepare the seal, sign the
+statement it returns with your developer key, and finalise. Nothing here looks inside the
+code: blobs are uploaded as they are and fingerprinted by the server.
+
+Local state lives in the Git directory, never in the working tree:
+  .git/codeimprint/chain.jsonl   the seals made from this clone (with their commits)
+  .git/codeimprint/queue         commits a hook could not seal yet (offline or an error)
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+
+from . import gitrepo, linecount, trust
+from .imprint_file import canonical
+
+PAGE = 5000                          # files per plan request
+BATCH_BYTES = 40 * 1024 * 1024       # blobs per upload request (the server takes 50 MB)
+JOB_WAIT_SECONDS = 1800
+
+
+def sign(key, statement: dict) -> str:
+    return trust.b64e(key.sign(canonical(statement)))
+
+
+def public_key(key) -> str:
+    return trust.b64e(trust.public_raw(key))
+
+
+def create_project(client, key, name: str | None = None) -> dict:
+    """Create a project for this developer key and finalise its genesis seal (an empty tree).
+    ``name`` is the project's display name (shown on its public page)."""
+    pub = public_key(key)
+    made = client.create_project(pub, sign(key, {"type": "codeimprint.project-create.v1",
+                                                 "public_key": pub}), name)
+    g = made["genesis"]
+    genesis = client.finalise(made["project_id"], g["pending_id"], pub,
+                              sign(key, g["statement"]))
+    return {"project_id": made["project_id"], "genesis": genesis}
+
+
+def _wait(client, job_id: str) -> dict:
+    deadline = time.monotonic() + JOB_WAIT_SECONDS
+    while time.monotonic() < deadline:
+        job = client.job(job_id)
+        if job["status"] == "done":
+            return job["result"]
+        if job["status"] == "failed":
+            raise RuntimeError(f"the server could not prepare the seal: {job.get('error')}")
+        time.sleep(0.5)
+    raise RuntimeError("the server took too long to prepare the seal")
+
+
+def seal_commit(client, root: Path, project: str, commit: str, kind: str, key,
+                exclude: list[str] | None = None, confirm=None, tag: str | None = None,
+                public_tag: bool = False) -> dict:
+    """Seal one commit. Returns {already: ID}, {already, released: REL ID}, {release: result}
+    or {result, uploaded, upload_bytes, files}.
+
+    A release of a tree that is already sealed becomes a release record pointing at that seal;
+    ``tag`` stays private (a salted commitment is public) unless ``public_tag``.
+    ``confirm(count, size)`` is asked before any blob is uploaded; returning False stops.
+    """
+    top = gitrepo.toplevel(root)
+    info = gitrepo.commit_info(top, commit)
+    under = gitrepo.prefix(root)
+    files = [f for f in gitrepo.ls_tree(top, commit, under)
+             if not f["path"].startswith(".imprint/")]     # seals and receipts: not content
+    lines = linecount.count_commit(top, commit, files, under).payload()
+    pages = [files[i:i + PAGE] for i in range(0, len(files), PAGE)] or [[]]
+    plan_id, resp = None, {}
+    for i, page in enumerate(pages):
+        body = {"files": page, "more": i < len(pages) - 1}
+        if plan_id:
+            body["plan_id"] = plan_id
+        else:
+            body.update(tree=info["tree"], commit=commit, parents=info["parents"],
+                        ref=info["ref"], kind=kind, exclude=list(exclude or []), lines=lines)
+            if kind == "release" and tag:
+                body.update(tag=tag, public_tag=public_tag)
+        resp = client.plan(project, body)
+        if "release" in resp:
+            rel = resp["release"]
+            result = client.finalise(project, rel["pending_id"], public_key(key),
+                                     sign(key, rel["statement"]))
+            return {"release": result, "commit": commit, "info": info, "tag": tag}
+        if "already_sealed" in resp:
+            # Engine 0.7.0a5+: already_sealed true and the earlier seal in full (its id);
+            # earlier engines: already_sealed is the seal's ID.
+            seal = resp["id"] if resp["already_sealed"] is True else resp["already_sealed"]
+            return {"already": seal, "released": resp.get("already_released"),
+                    "commit": commit, "info": info}
+        plan_id = resp.get("plan_id", plan_id)
+    need = resp["need"]
+    sizes = {f["blob"]: f["size"] for f in files}
+    size = sum(sizes.get(b, 0) for b in need)
+    if need and confirm is not None and not confirm(len(need), size):
+        return {"cancelled": True}
+    batch, batch_size = [], 0
+    for blob, data in gitrepo.read_blobs(top, need):
+        if batch and batch_size + len(data) > BATCH_BYTES:
+            client.upload_blobs(project, batch)
+            batch, batch_size = [], 0
+        batch.append((blob, data))
+        batch_size += len(data)
+    if batch:
+        client.upload_blobs(project, batch)
+    prep = client.prepare(project, plan_id)
+    if "job_id" in prep:
+        prep = _wait(client, prep["job_id"])
+    result = client.finalise(project, prep["pending_id"], public_key(key),
+                             sign(key, prep["statement"]))
+    check_lines(lines, result)
+    return {"result": result, "uploaded": len(need), "upload_bytes": size, "tag": tag,
+            "files": resp.get("files", 0), "commit": commit, "info": info, "lines": lines}
+
+
+def check_lines(sent: dict, result: dict) -> None:
+    """The Imprint you signed carries the count this client sent (older servers keep none)."""
+    kept = (result.get("imprint") or {}).get("lines")
+    if kept is not None and not result.get("already_sealed") and kept != sent:
+        raise RuntimeError("the server recorded a different line count than this client "
+                           "counted; the seal is logged, but report this")
+
+
+# -- local state ---------------------------------------------------------------------------
+def _state(root: Path) -> Path:
+    path = gitrepo.git_dir(root) / "codeimprint"
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def record(root: Path, seal: dict, commit: str, ref: str | None) -> None:
+    st = seal["receipt"]["attestation"]["statement"]
+    line = {"seal": seal["id"], "kind": st.get("kind"), "parents": st.get("parents", []),
+            "attested_at": st["attested_at"], "log_index": seal["receipt"]["log"]["index"],
+            "commit": commit, "ref": ref}
+    with (_state(root) / "chain.jsonl").open("a", encoding="utf-8") as f:
+        f.write(json.dumps(line, sort_keys=True) + "\n")
+
+
+def local_chain(root: Path) -> list[dict]:
+    path = _state(root) / "chain.jsonl"
+    if not path.is_file():
+        return []
+    return [json.loads(line) for line in path.read_text(encoding="utf-8").splitlines() if line]
+
+
+def load_queue(root: Path) -> list[dict]:
+    path = _state(root) / "queue"
+    if not path.is_file():
+        return []
+    return [json.loads(line) for line in path.read_text(encoding="utf-8").splitlines() if line]
+
+
+def save_queue(root: Path, items: list[dict]) -> None:
+    path = _state(root) / "queue"
+    path.write_text("".join(json.dumps(i, sort_keys=True) + "\n" for i in items),
+                    encoding="utf-8")
+
+
+HOOK_MARK = "# Added by `imprint hook install` (CodeImprint)"
+HOOK_FILES = {"commit": "post-commit", "push": "pre-push"}
+
+
+def hook_script(python: str, on: str) -> str:
+    """A hook that never blocks: whatever happens, it exits 0."""
+    return (f"#!/bin/sh\n{HOOK_MARK}. It never blocks a {on}: when the server cannot be\n"
+            f"# reached, the seal is queued in .git/codeimprint/queue and sent on the next run.\n"
+            f'"{python}" -m codeimprint_cli hook run --on {on} || true\nexit 0\n')