codeimprint 0.5.0a11__py3-none-any.whl

codeimprint_cli/ownership.py

@@ -0,0 +1,341 @@
+"""Ownership claims (ADR 0002, D4): build claim documents and verify a project's ownership
+listing.
+
+Verification fetches every record the listing relies on and checks each receipt (format 4)
+like any seal: digest, typed ID, owner signatures, attestation, log inclusion and timestamps.
+It then checks the claim rules (every listed key signed; the claimant's identity was valid at
+level email or higher, or an organisation's disclosed domain identity) and **recomputes which
+seals each claim covers** from the seals' own receipts (their chain signer and time), the claim
+keys, membership windows, assignments and contributor agreements. The result must equal the
+server's listing.
+
+What this cannot show: that the server listed every record (a record left out of the listing
+is not seen here; the transparency log is where it would show), that the server checked the
+e-mail, GitHub or DNS evidence correctly, organisation key windows (taken from the
+organisation's public page), or whether a claim is legally valid.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import secrets
+from pathlib import Path
+
+from . import receipt, trust
+from .api import ApiError, NetworkError
+from .imprint_file import canonical
+from .receipt import FAIL, PASS, WARN, Check
+
+CLAIM = "codeimprint.claim.v1"
+CLAIM_KEY = "codeimprint.claim-key.v1"
+ASSIGNMENT = "codeimprint.assignment.v1"
+CONTRIBUTOR = "codeimprint.contributor.v1"
+REVOCATION = "codeimprint.revocation.v1"
+MEMBER = "codeimprint.org-member.v1"
+MEMBER_END = "codeimprint.org-member-end.v1"
+IDENTITY = "codeimprint.identity.v1"
+ASSIGNING = ("cla", "employment", "contract", "assignment")
+PERSON_LEVELS = ("email", "vcs")
+DISCLAIMER = ("An ownership claim records what the claimant states and the evidence they "
+              "committed. It is not a legal determination of ownership.")
+
+
+# -- documents ---------------------------------------------------------------------------
+def document_commitment(path: Path) -> dict:
+    """A salted commitment to a supporting document. Only the commitment is sent; keep the
+    salt (and the file) to reveal it later."""
+    file_hash = hashlib.sha256(Path(path).read_bytes()).hexdigest()
+    salt = trust.b64e(secrets.token_bytes(32))
+    commitment = hashlib.sha256(canonical({"salt": salt, "sha256": file_hash})).hexdigest()
+    return {"commitment": commitment, "salt": salt, "sha256": file_hash, "file": str(path)}
+
+
+def check_commitment(path: Path, salt: str, commitment: str) -> bool:
+    file_hash = hashlib.sha256(Path(path).read_bytes()).hexdigest()
+    return hashlib.sha256(canonical({"salt": salt, "sha256": file_hash})).hexdigest() == \
+        commitment
+
+
+def digest(document: dict) -> str:
+    return hashlib.sha256(canonical(document)).hexdigest()
+
+
+# -- coverage ----------------------------------------------------------------------------
+def within(window: dict, at: str) -> bool:
+    return ((window.get("valid_from") is None or window["valid_from"] <= at)
+            and (window.get("valid_until") is None or at < window["valid_until"]))
+
+
+def coverage(seals: list[dict], claims: list[dict]) -> dict[str, set[tuple[str, str]]]:
+    """``{seal: {(claim, reason)}}`` from seals ({seal, signer, attested_at, suspect}) and
+    claims ({id, windows, end}). The rule (D4): the seal's chain signer was an authorised key
+    of the claim at the seal's time, the claim had not ended, and the key was not reported
+    compromised by then."""
+    out: dict[str, set[tuple[str, str]]] = {}
+    for s in seals:
+        hits = set()
+        if s["signer"] and not s["suspect"]:
+            for c in claims:
+                if c["end"] and s["attested_at"] >= c["end"]:
+                    continue
+                why = next((w for w in c["windows"] if w["fingerprint"] == s["signer"]
+                            and within(w, s["attested_at"])), None)
+                if why:
+                    hits.add((c["id"], why["reason"]))
+        out[s["seal"]] = hits
+    return out
+
+
+class _Verifier:
+    def __init__(self, client, keys: list[dict], anchors=None):
+        self.client, self.keys, self.anchors = client, keys, anchors
+        self.cache: dict[str, dict] = {}
+        self.checks: list[Check] = []
+
+    def fail(self, name: str, detail: str) -> None:
+        self.checks.append(Check(name, FAIL, detail))
+
+    def record(self, rid: str) -> dict | None:
+        """A verified record receipt (fetched once), or None after a FAIL."""
+        if rid in self.cache:
+            return self.cache[rid]
+        try:
+            rec = self.client.public_record(rid)
+        except (ApiError, NetworkError) as exc:
+            self.fail(rid, f"cannot fetch: {exc}")
+            self.cache[rid] = None
+            return None
+        bad = [c for c in receipt.verify(rec, self.keys, anchors=self.anchors)
+               if c.status == FAIL]
+        if bad:
+            self.fail(rid, "; ".join(f"{c.name}: {c.detail}" for c in bad))
+            rec = None
+        self.cache[rid] = rec
+        return rec
+
+
+def _at(rec: dict) -> str:
+    return rec["attestation"]["statement"]["attested_at"]
+
+
+def _sigs(rec: dict) -> set[tuple[str, str]]:
+    return {(s["role"], s["fingerprint"]) for s in rec.get("signatures") or []}
+
+
+def verify(client, project: str, keys: list[dict], anchors=None) -> tuple[dict, list[Check]]:
+    """Fetch the ownership listing (every page) and verify it. Returns the listing and the
+    checks; any FAIL means the listing cannot be relied on."""
+    view, after = None, None
+    while True:
+        page = client.public_ownership(project, after)
+        if view is None:
+            view = page
+        else:
+            view["seals"] += page["seals"]
+        if page.get("next") is None:
+            break
+        after = page["next"]
+    v = _Verifier(client, keys, anchors)
+
+    # Seals: the signer and time come from each seal's own verified receipt.
+    seals, status_cache = [], {}
+    for s in view["seals"]:
+        try:
+            rec = client.public_imprint(s["seal"])
+        except (ApiError, NetworkError) as exc:
+            v.fail(f"seal {s['seal']}", f"cannot fetch: {exc}")
+            continue
+        bad = [c for c in receipt.verify(rec, keys, anchors=anchors) if c.status == FAIL]
+        signer = receipt.chain_signer(rec)
+        if bad:
+            v.fail(f"seal {s['seal']}", "; ".join(f"{c.name}: {c.detail}" for c in bad))
+            continue
+        if (signer, _at(rec)) != (s["signer"], s["attested_at"]):
+            v.fail(f"seal {s['seal']}", "the listing misstates the seal's signer or time")
+            continue
+        if signer not in status_cache:
+            status_cache[signer] = client.key_identity(signer).get("compromised_since")
+        since = status_cache[signer]
+        seals.append({"seal": s["seal"], "signer": signer, "attested_at": _at(rec),
+                      "suspect": bool(since and _at(rec) >= since)})
+
+    claims = []
+    for c in view["claims"]:
+        rules = _claim(v, c, project)
+        if rules:
+            claims.append(rules)
+    if any(ch.status == FAIL for ch in v.checks):
+        return view, v.checks
+    mine = coverage(seals, claims)
+    theirs = {s["seal"]: {(x["claim"], x["reason"]) for x in s["covered_by"]}
+              for s in view["seals"]}
+    wrong = [s for s in mine if mine[s] != theirs.get(s)]
+    if wrong:
+        v.fail("coverage", f"{len(wrong)} seal(s) are not covered as the server lists them "
+                           f"(first: {wrong[0]})")
+    else:
+        hit = sum(1 for s in mine.values() if s)
+        v.checks.append(Check("coverage", PASS, f"{len(mine)} seal(s), {hit} covered by a "
+                                                "claim; recomputed here and equal to the "
+                                                "server's listing"))
+    if view.get("disclaimer") != DISCLAIMER:
+        v.checks.append(Check("wording", WARN, "the listing does not carry the ownership "
+                                               "disclaimer"))
+    return view, v.checks
+
+
+def _claim(v: _Verifier, c: dict, project: str) -> dict | None:
+    """Check one claim and the records behind it; returns its coverage rules."""
+    name = f"claim {c['id']}"
+    rec = v.record(c["id"])
+    if rec is None:
+        return None
+    doc, at = rec["record"]["document"], _at(rec)
+    if rec["record"]["type"] != CLAIM or doc.get("project") != project:
+        v.fail(name, "not a claim on this project")
+        return None
+    if (doc["basis"], doc["effective_at"], doc["share"], doc["keys"]) != (
+            c["basis"], c["effective_at"], c["share"],
+            sorted({w["fingerprint"] for w in c["authorised"] if w["reason"] == "claim-key"
+                    and w["record"] == c["id"]}) if doc["claimant"]["kind"] == "person"
+            else doc["keys"]):
+        v.fail(name, "the listing misstates the claim")
+        return None
+    claimant = doc["claimant"]
+    idt = v.record(claimant["identity"])
+    if idt is None:
+        return None
+    idoc = idt["record"]["document"]
+    if idt["record"]["type"] != IDENTITY or not (idoc["valid_from"] <= at < idoc["valid_until"]):
+        v.fail(name, "the claimant's identity record was not valid when the claim was made")
+        return None
+    status = v.client.key_identity(idoc["key"])
+    revoked = {r["id"]: r for r in status.get("revocations") or []}
+    entry = next((i for i in status.get("identities") or [] if i["id"] == idt["imprint_id"]),
+                 None)
+    if entry and entry.get("revoked_by") and revoked.get(entry["revoked_by"], {}).get(
+            "effective_at", "9999") <= at:
+        v.fail(name, "the claimant's identity was revoked before the claim")
+        return None
+    expected = {("claimant", idoc["key"])} | {("authorised", k) for k in doc["keys"]
+                                              if k != idoc["key"]}
+    if _sigs(rec) != expected:
+        v.fail(name, "not signed by exactly the claimant and every listed key (consent)")
+        return None
+    windows = []
+    if claimant["kind"] == "person":
+        if idoc["level"] not in PERSON_LEVELS or idoc["key"] not in doc["keys"]:
+            v.fail(name, "a person's claim needs an identity at level email or higher on one "
+                         "of its keys")
+            return None
+        windows += [{"fingerprint": k, "valid_from": None, "valid_until": None,
+                     "reason": "claim-key"} for k in doc["keys"]]
+    else:
+        org = v.client.public_org(claimant["org"])
+        if idoc["level"] != "domain" or idoc.get("org") != claimant["org"]:
+            v.fail(name, "an organisation claims with its own domain identity")
+            return None
+        dom = next((d for d in org["domains"] if d["identity"] == idt["imprint_id"]
+                    and d.get("disclosure")), None)
+        dsc = v.record(dom["disclosure"]) if dom else None
+        if dsc is None:
+            v.fail(name, "the organisation's domain was not disclosed (D9)")
+            return None
+        ddoc = dsc["record"]["document"]
+        if hashlib.sha256(canonical({"salt": ddoc["salt"], "value": ddoc["value"]})) \
+                .hexdigest() != idoc["subject_commitment"] or ddoc["record"] != idt[
+                    "imprint_id"] or _at(dsc) > at:
+            v.fail(name, "the disclosure does not open the identity's commitment, or came "
+                         "after the claim")
+            return None
+        active = sorted(k["fingerprint"] for k in org["keys"] if within(k, at))
+        if doc["keys"] != active:
+            v.fail(name, "the claim does not list exactly the organisation's keys at that time")
+            return None
+        windows += [{"fingerprint": k["fingerprint"], "valid_from": k["valid_from"],
+                     "valid_until": k["valid_until"], "reason": "org-key"} for k in org["keys"]]
+        if doc["basis"] == "employer":
+            for m in org["members"]:
+                if m.get("revoked_by"):
+                    continue
+                mrec = v.record(m["membership"])
+                if mrec is None:
+                    return None
+                mdoc = mrec["record"]["document"]
+                until = None
+                if m.get("ended_by"):
+                    end = v.record(m["ended_by"])
+                    if end is None:
+                        return None
+                    edoc = end["record"]["document"]
+                    if edoc.get("membership") != m["membership"]:
+                        v.fail(name, "a membership end record is for another membership")
+                        return None
+                    until = edoc["valid_until"]
+                if (mdoc["org"], mdoc["member_key"], mdoc["valid_from"], until) != (
+                        claimant["org"], m["member_key"], m["valid_from"], m["valid_until"]):
+                    v.fail(name, "the organisation page misstates a membership window")
+                    return None
+                windows.append({"fingerprint": mdoc["member_key"], "valid_from":
+                                mdoc["valid_from"], "valid_until": until,
+                                "reason": "membership"})
+    end = None
+    for rid in c["records"]:
+        r = v.record(rid)
+        if r is None:
+            return None
+        rtype, d = r["record"]["type"], r["record"]["document"]
+        if rtype == CLAIM_KEY and d.get("claim") == c["id"]:
+            by = [fp for role, fp in _sigs(r) if role == "authorised"]
+            if not by or not any(w["fingerprint"] == by[0] and w["reason"] == "claim-key"
+                                 and within(w, _at(r)) for w in windows):
+                v.fail(name, f"{rid} is not signed by a key authorised at that time")
+                return None
+            if d["action"] == "add":
+                if ("key", d["key"]) not in _sigs(r):
+                    v.fail(name, f"{rid}: the added key did not consent")
+                    return None
+                if not any(w["fingerprint"] == d["key"] for w in windows):
+                    windows.append({"fingerprint": d["key"], "valid_from": _at(r),
+                                    "valid_until": None, "reason": "claim-key"})
+            else:
+                for w in windows:
+                    if w["fingerprint"] == d["key"] and w["reason"] == "claim-key" and \
+                            w["valid_until"] is None:
+                        w["valid_until"] = _at(r)
+        elif rtype == REVOCATION and d.get("revokes") == c["id"]:
+            holder = [fp for role, fp in _sigs(r) if role == "holder"]
+            if holder and holder != [d["key"]]:
+                v.fail(name, f"{rid} is signed by a key other than the one it names")
+                return None
+            end = min(end or d["effective_at"], d["effective_at"])
+        elif rtype == ASSIGNMENT and d.get("to_claim") == c["id"]:
+            if ("assignor", d["from_key"]) not in _sigs(r):
+                v.fail(name, f"{rid}: the contributor did not sign the assignment")
+                return None
+            windows.append({"fingerprint": d["from_key"], "valid_from": d["from"],
+                            "valid_until": d["until"], "reason": "assignment"})
+        elif rtype == CONTRIBUTOR and (d.get("agreement") or {}).get("assigns_to") == c["id"]:
+            ag = d["agreement"]
+            if ("contributor", d["contributor_key"]) not in _sigs(r) or \
+                    ag["kind"] not in ASSIGNING:
+                v.fail(name, f"{rid}: not an assigning agreement signed by the contributor")
+                return None
+            windows.append({"fingerprint": d["contributor_key"], "valid_from": ag["from"],
+                            "valid_until": ag.get("until"), "reason": "contributor-agreement"})
+        elif rtype not in (MEMBER, MEMBER_END):
+            v.fail(name, f"{rid} is listed but does not belong to this claim")
+            return None
+    if (end is None) != (c["status"] == "active") or (end and end != c["ended_at"]):
+        v.fail(name, "the listing misstates whether or when the claim ended")
+        return None
+    level = f"level {idoc['level']}" + (f", DNSSEC {idoc['dnssec']}" if idoc.get("dnssec")
+                                        else "")
+    v.checks.append(Check(name, PASS, f"{c['label']} ({doc['basis']}, {level}); signed by "
+                                      f"{len(expected)} key(s); "
+                                      + ("active" if end is None else f"ended {end}")))
+    return {"id": c["id"], "windows": windows, "end": end}
+
+
+def fingerprint_of(key) -> str:
+    return trust.fingerprint(trust.public_raw(key))

codeimprint_cli/project.py

@@ -0,0 +1,129 @@
+"""Choosing which files leave the machine, and packing them into a zip.
+
+Only source files the server reads are sent (Python in this release). Files ignored by
+.gitignore (root and nested) or excluded in .imprint/config.json are never sent, nor are
+symlinks, version-control folders and virtual environments.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import io
+import json
+import os
+import zipfile
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import pathspec
+
+CONFIG_DIR = ".imprint"
+CONFIG_FILE = "config.json"
+SOURCE_SUFFIXES = (".py",)
+SKIP_DIRS = {
+    ".git", ".hg", ".svn", ".imprint", "__pycache__", ".venv", "venv", "env", "node_modules",
+    "build", "dist", "site-packages", ".tox", ".mypy_cache", ".pytest_cache", ".ruff_cache",
+}
+DEFAULT_EXCLUDE = [
+    "vendor/*", "third_party/*", "node_modules/*", "*/site-packages/*", "*/migrations/*",
+    "build/*", "dist/*",
+]
+_ZIP_TIME = (1980, 1, 1, 0, 0, 0)     # fixed, so the same files give the same zip
+
+
+def load_config(root: Path) -> dict:
+    path = root / CONFIG_DIR / CONFIG_FILE
+    if not path.is_file():
+        return {}
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except ValueError as exc:
+        raise ValueError(f"{path} is not valid JSON: {exc}") from exc
+
+
+def _excluded(rel: str, patterns: list[str]) -> bool:
+    """Glob on the project-relative POSIX path; ``*`` also crosses folders (``vendor/*``)."""
+    return any(fnmatch.fnmatchcase(rel, p) for p in patterns)
+
+
+@dataclass
+class Selection:
+    root: Path
+    files: list[str] = field(default_factory=list)     # project-relative POSIX paths
+    total_bytes: int = 0
+    ignored: int = 0
+
+    @property
+    def count(self) -> int:
+        return len(self.files)
+
+
+def select_files(root: str | Path, suffixes: tuple[str, ...] | None = SOURCE_SUFFIXES,
+                 use_excludes: bool = True) -> Selection:
+    """The files to send: ``suffixes`` (None: every file, for the line count) that
+    .gitignore and (``use_excludes``) .imprint/config.json do not leave out."""
+    root = Path(root).resolve()
+    if not root.is_dir():
+        raise FileNotFoundError(f"no such folder: {root}")
+    excludes = list(load_config(root).get("exclude", [])) if use_excludes else []
+    ignores: list[tuple[str, pathspec.GitIgnoreSpec]] = []    # (folder prefix, its .gitignore)
+    sel = Selection(root=root)
+
+    def ignored(rel: str, is_dir: bool) -> bool:
+        for prefix, spec in ignores:
+            if prefix and not rel.startswith(prefix):
+                continue
+            sub = rel[len(prefix):] + ("/" if is_dir else "")
+            if spec.match_file(sub):
+                return True
+        return False
+
+    for dirpath, dirnames, filenames in os.walk(root):
+        here = Path(dirpath)
+        rel_dir = here.relative_to(root).as_posix()
+        prefix = "" if rel_dir == "." else rel_dir + "/"
+        gitignore = here / ".gitignore"
+        if gitignore.is_file():
+            lines = gitignore.read_text(encoding="utf-8", errors="replace").splitlines()
+            ignores.append((prefix, pathspec.GitIgnoreSpec.from_lines(lines)))
+        keep = []
+        for d in sorted(dirnames):
+            rel = prefix + d
+            if d in SKIP_DIRS or (here / d).is_symlink() or ignored(rel, True) \
+                    or _excluded(rel + "/", excludes):
+                sel.ignored += 1
+                continue
+            keep.append(d)
+        dirnames[:] = keep
+        for name in sorted(filenames):
+            rel = prefix + name
+            path = here / name
+            if (suffixes is not None and not name.endswith(suffixes)) or path.is_symlink():
+                continue
+            if ignored(rel, False) or _excluded(rel, excludes):
+                sel.ignored += 1
+                continue
+            sel.files.append(rel)
+            sel.total_bytes += path.stat().st_size
+    sel.files.sort()
+    return sel
+
+
+def build_zip(sel: Selection) -> bytes:
+    buf = io.BytesIO()
+    with zipfile.ZipFile(buf, "w", compression=zipfile.ZIP_DEFLATED) as zf:
+        for rel in sel.files:
+            info = zipfile.ZipInfo(rel, date_time=_ZIP_TIME)
+            info.compress_type = zipfile.ZIP_DEFLATED
+            info.external_attr = 0o644 << 16
+            zf.writestr(info, (sel.root / rel).read_bytes())
+    return buf.getvalue()
+
+
+def human_size(n: int) -> str:
+    size = float(n)
+    for unit in ("bytes", "kB", "MB", "GB"):
+        if size < 1000 or unit == "GB":
+            return f"{int(size)} {unit}" if unit == "bytes" else f"{size:.1f} {unit}"
+        size /= 1000
+    return f"{n} bytes"