tripwire-git 0.1.0__py3-none-any.whl

tripwire/__init__.py

@@ -0,0 +1,3 @@
+"""tripwire: approval-gated protection for blocks of code in Git."""
+
+__version__ = "0.1.0"

tripwire/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

tripwire/approvals.py

@@ -0,0 +1,30 @@
+"""Approval providers. Local provider reads .tripwire/approvals.json.
+
+Platform providers (GitHub, GitLab, ...) will implement the same shape:
+return a list of Approval for the change being checked.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import List, Optional
+
+from .config import ConfigError
+from .models import Approval
+
+
+def parse_local(text: Optional[str]) -> List[Approval]:
+    if not text or not text.strip():
+        return []
+    try:
+        raw = json.loads(text)
+        return [Approval(i["lock"], i["approver"], i["digest"]) for i in raw]
+    except (ValueError, KeyError, TypeError) as exc:
+        raise ConfigError("invalid approvals file: %s" % exc)
+
+
+def dump_local(approvals: List[Approval]) -> str:
+    return json.dumps(
+        [{"lock": a.lock_id, "approver": a.approver, "digest": a.digest} for a in approvals],
+        indent=2,
+    ) + "\n"

tripwire/blocks.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import re
+from typing import Dict, List, Tuple
+
+BEGIN = re.compile(r"@lock-begin\s+([A-Za-z0-9_.\-]+)")
+END = re.compile(r"@lock-end\s+([A-Za-z0-9_.\-]+)")
+
+Norm = Tuple[str, ...]
+
+
+def normalize(text: str) -> Norm:
+    """Strip each line and drop blank lines, so whitespace-only edits don't count."""
+    return tuple(line.strip() for line in text.splitlines() if line.strip())
+
+
+def extract_blocks(text: str) -> Dict[str, Norm]:
+    """Map block id -> normalized content between its markers.
+
+    An unclosed block extends to the end of the file (fail closed).
+    """
+    content: Dict[str, List[str]] = {}
+    open_ids: List[str] = []
+    for line in text.splitlines():
+        begin = BEGIN.search(line)
+        if begin:
+            open_ids.append(begin.group(1))
+            content.setdefault(begin.group(1), [])
+            continue
+        end = END.search(line)
+        if end:
+            if end.group(1) in open_ids:
+                open_ids.reverse()
+                open_ids.remove(end.group(1))
+                open_ids.reverse()
+            continue
+        stripped = line.strip()
+        if stripped:
+            for block_id in open_ids:
+                content[block_id].append(stripped)
+    return {k: tuple(v) for k, v in content.items()}

tripwire/cli.py

@@ -0,0 +1,244 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from typing import List, Optional, Tuple
+
+from .approvals import dump_local, parse_local
+from .config import APPROVALS_PATH, RULES_PATH, Config, ConfigError, parse_config
+from .engine import evaluate
+from .gitio import (
+    EMPTY_TREE,
+    ZERO,
+    GitError,
+    RevSource,
+    WorktreeSource,
+    collect_changes,
+    git,
+    new_branch_base,
+    toplevel,
+)
+from .models import Approval, Decision
+
+
+def resolve_actor(explicit: Optional[str], root: str) -> str:
+    for candidate in (
+        explicit,
+        os.environ.get("TRIPWIRE_ACTOR"),
+        os.environ.get("GL_USERNAME"),
+        os.environ.get("REMOTE_USER"),
+    ):
+        if candidate:
+            return candidate
+    for key in ("tripwire.actor", "user.email"):
+        value = git(root, "config", key, check=False).decode().strip()
+        if value:
+            return value
+    raise ConfigError("cannot determine the acting user; pass --actor or set TRIPWIRE_ACTOR")
+
+
+def run_check(root: str, base: str, head: Optional[str], actor: str) -> Tuple[Optional[Config], Decision]:
+    """Rules are read from `base`, so a change cannot rewrite the rules that judge it."""
+    rules = RevSource(root, base).read(RULES_PATH)
+    if rules is None:
+        return None, Decision()
+    config = parse_config(rules)
+    head_src = RevSource(root, head) if head is not None else WorktreeSource(root)
+    approvals = parse_local(head_src.read(APPROVALS_PATH))
+    return config, evaluate(config, collect_changes(root, base, head), actor, approvals)
+
+
+def report(decision: Decision) -> int:
+    if decision.allowed:
+        print("tripwire: OK")
+        return 0
+    print("tripwire: BLOCKED", file=sys.stderr)
+    for v in decision.violations:
+        print("  - " + v.message, file=sys.stderr)
+    return 1
+
+
+def cmd_check(args, root: str) -> int:
+    actor = resolve_actor(args.actor, root)
+    _, decision = run_check(root, args.base, args.head, actor)
+    return report(decision)
+
+
+def cmd_preflight(args, root: str) -> int:
+    actor = resolve_actor(args.actor, root)
+    has_head = git(root, "rev-parse", "--verify", "-q", "HEAD", check=False).strip()
+    _, decision = run_check(root, "HEAD" if has_head else EMPTY_TREE, "" if args.staged else None, actor)
+    return report(decision)
+
+
+HOOK_MARK = "# installed by tripwire"
+HOOK = """#!/bin/sh
+%s
+# Local early warning. Bypassable with --no-verify: the server-side check is the real gate.
+if command -v tripwire >/dev/null 2>&1; then
+  exec tripwire preflight --staged
+else
+  exec python -m tripwire preflight --staged
+fi
+""" % HOOK_MARK
+
+
+def cmd_install_hook(args, root: str) -> int:
+    hooks = git(root, "rev-parse", "--git-path", "hooks").decode().strip()
+    path = os.path.join(root, hooks, "pre-commit") if not os.path.isabs(hooks) else os.path.join(hooks, "pre-commit")
+    if os.path.exists(path):
+        with open(path, encoding="utf-8", errors="replace") as fh:
+            ours = HOOK_MARK in fh.read()
+        if not ours and not args.force:
+            print("tripwire: %s already exists; use --force to replace it" % path, file=sys.stderr)
+            return 1
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    with open(path, "w", encoding="utf-8", newline="\n") as fh:
+        fh.write(HOOK)
+    os.chmod(path, 0o755)
+    print("tripwire: installed %s" % path)
+    return 0
+
+
+def cmd_pre_receive(args, root: str) -> int:
+    actor = resolve_actor(args.actor, root)
+    status = 0
+    for line in sys.stdin:
+        parts = line.split()
+        if len(parts) < 3:
+            continue
+        old, new, ref = parts[:3]
+        if new == ZERO:
+            continue
+        base = old if old != ZERO else new_branch_base(root, new)
+        if base is None:
+            continue
+        _, decision = run_check(root, base, new, actor)
+        if not decision.allowed:
+            print("tripwire: push to %s rejected" % ref, file=sys.stderr)
+            status = report(decision) or status
+    return status
+
+
+def _pull_number(explicit: Optional[int]) -> int:
+    if explicit is not None:
+        return explicit
+    event = os.environ.get("GITHUB_EVENT_PATH")
+    if not event or not os.path.isfile(event):
+        raise ConfigError("pull request number unknown; pass --pr")
+    with open(event, encoding="utf-8") as fh:
+        number = json.load(fh).get("pull_request", {}).get("number")
+    if number is None:
+        raise ConfigError("not a pull_request event; pass --pr")
+    return int(number)
+
+
+def cmd_github_check(args, root: str) -> int:
+    from .github import GitHubClient, check_pull_request
+
+    return report(check_pull_request(root, GitHubClient.from_env(args.github_repo), _pull_number(args.pr)))
+
+
+def cmd_gitea_check(args, root: str) -> int:
+    from .gitea import GiteaClient, check_pull_request
+
+    client = GiteaClient.from_env(args.gitea_repo, args.gitea_url)
+    return report(check_pull_request(root, client, _pull_number(args.pr)))
+
+
+def cmd_gitlab_check(args, root: str) -> int:
+    from .gitlab import GitLabClient, check_merge_request
+
+    iid = args.mr or os.environ.get("CI_MERGE_REQUEST_IID")
+    if not iid:
+        raise ConfigError("merge request number unknown; pass --mr or run in a merge request pipeline")
+    return report(check_merge_request(root, GitLabClient.from_env(args.gitlab_project), int(iid)))
+
+
+def cmd_approve(args, root: str) -> int:
+    config, decision = run_check(root, args.base, args.head, actor="")
+    if config is None:
+        print("tripwire: no rules file at base", file=sys.stderr)
+        return 2
+    if args.approver not in config.everyone():
+        print("tripwire: %s is not an owner, approver or leader" % args.approver, file=sys.stderr)
+        return 1
+    path = os.path.join(root, APPROVALS_PATH)
+    existing: List[Approval] = []
+    if os.path.isfile(path):
+        with open(path, encoding="utf-8") as fh:
+            existing = parse_local(fh.read())
+    added = 0
+    for v in decision.violations:
+        if v.digest and (args.lock is None or v.lock_id == args.lock):
+            lock = config.get(v.lock_id)
+            allowed = set(config.leaders) | (set(lock.owners) | set(lock.approvers) if lock else set())
+            if args.approver in allowed:
+                existing.append(Approval(v.lock_id, args.approver, v.digest))
+                added += 1
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    with open(path, "w", encoding="utf-8") as fh:
+        fh.write(dump_local(existing))
+    print("tripwire: recorded %d approval(s) in %s" % (added, APPROVALS_PATH))
+    return 0 if added else 1
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="tripwire")
+    p.add_argument("--repo", default=".", help="path inside the repository")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    c = sub.add_parser("check", help="check base..head (head defaults to the working tree)")
+    c.add_argument("--base", required=True)
+    c.add_argument("--head")
+    c.add_argument("--actor")
+    c.set_defaults(func=cmd_check)
+
+    f = sub.add_parser("preflight", help="check uncommitted changes against HEAD")
+    f.add_argument("--actor")
+    f.add_argument("--staged", action="store_true", help="check only staged changes (for pre-commit)")
+    f.set_defaults(func=cmd_preflight)
+
+    h = sub.add_parser("install-hook", help="install a local pre-commit hook")
+    h.add_argument("--force", action="store_true", help="replace an existing pre-commit hook")
+    h.set_defaults(func=cmd_install_hook)
+
+    r = sub.add_parser("pre-receive", help="server hook: read ref updates from stdin")
+    r.add_argument("--actor")
+    r.set_defaults(func=cmd_pre_receive)
+
+    g = sub.add_parser("github-check", help="check a GitHub pull request using its reviews")
+    g.add_argument("--pr", type=int, help="PR number (default: from GITHUB_EVENT_PATH)")
+    g.add_argument("--github-repo", help="owner/name (default: GITHUB_REPOSITORY)")
+    g.set_defaults(func=cmd_github_check)
+
+    gt = sub.add_parser("gitea-check", help="check a Gitea/Forgejo pull request using its reviews")
+    gt.add_argument("--pr", type=int, help="PR number (default: from GITHUB_EVENT_PATH)")
+    gt.add_argument("--gitea-repo", help="owner/name (default: GITHUB_REPOSITORY)")
+    gt.add_argument("--gitea-url", help="API base, e.g. https://git.example.com/api/v1")
+    gt.set_defaults(func=cmd_gitea_check)
+
+    gl = sub.add_parser("gitlab-check", help="check a GitLab merge request using its approvals")
+    gl.add_argument("--mr", type=int, help="MR iid (default: CI_MERGE_REQUEST_IID)")
+    gl.add_argument("--gitlab-project", help="project id or path (default: CI_PROJECT_ID)")
+    gl.set_defaults(func=cmd_gitlab_check)
+
+    a = sub.add_parser("approve", help="record an approval for the pending change")
+    a.add_argument("--base", required=True)
+    a.add_argument("--head")
+    a.add_argument("--approver", required=True)
+    a.add_argument("--lock", help="only approve this lock id")
+    a.set_defaults(func=cmd_approve)
+    return p
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        root = toplevel(args.repo) if args.command != "pre-receive" else os.path.abspath(args.repo)
+        return args.func(args, root)
+    except (ConfigError, GitError) as exc:
+        print("tripwire: error: %s" % exc, file=sys.stderr)
+        return 2

tripwire/config.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+import fnmatch
+import json
+from dataclasses import dataclass
+from typing import Optional, Tuple
+
+RULES_PATH = ".tripwire/locks.json"
+APPROVALS_PATH = ".tripwire/approvals.json"
+
+
+class ConfigError(Exception):
+    pass
+
+
+@dataclass(frozen=True)
+class Lock:
+    id: str
+    owners: Tuple[str, ...] = ()
+    approvers: Tuple[str, ...] = ()
+    paths: Tuple[str, ...] = ()
+
+    def matches_path(self, path: str) -> bool:
+        for pat in self.paths:
+            if pat.endswith("/"):
+                if path.startswith(pat):
+                    return True
+            elif fnmatch.fnmatchcase(path, pat):
+                return True
+        return False
+
+
+@dataclass(frozen=True)
+class Config:
+    leaders: Tuple[str, ...]
+    locks: Tuple[Lock, ...]
+
+    def get(self, lock_id: str) -> Optional[Lock]:
+        for lock in self.locks:
+            if lock.id == lock_id:
+                return lock
+        return None
+
+    def everyone(self) -> set:
+        people = set(self.leaders)
+        for lock in self.locks:
+            people.update(lock.owners)
+            people.update(lock.approvers)
+        return people
+
+
+def _names(obj, key: str) -> Tuple[str, ...]:
+    value = obj.get(key, [])
+    if not isinstance(value, list) or not all(isinstance(v, str) for v in value):
+        raise ConfigError("'%s' must be a list of strings" % key)
+    return tuple(value)
+
+
+def parse_config(text: str) -> Config:
+    try:
+        raw = json.loads(text)
+    except ValueError as exc:
+        raise ConfigError("invalid JSON in %s: %s" % (RULES_PATH, exc))
+    if not isinstance(raw, dict):
+        raise ConfigError("%s must be a JSON object" % RULES_PATH)
+    locks = []
+    seen = set()
+    for item in raw.get("locks", []):
+        if not isinstance(item, dict) or not isinstance(item.get("id"), str):
+            raise ConfigError("every lock needs a string 'id'")
+        if item["id"] in seen:
+            raise ConfigError("duplicate lock id '%s'" % item["id"])
+        seen.add(item["id"])
+        locks.append(
+            Lock(
+                id=item["id"],
+                owners=_names(item, "owners"),
+                approvers=_names(item, "approvers"),
+                paths=_names(item, "paths"),
+            )
+        )
+    return Config(leaders=_names(raw, "leaders"), locks=tuple(locks))

tripwire/engine.py

@@ -0,0 +1,77 @@
+"""Platform-neutral core: diff + actor + rules + approvals -> allow / block."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Iterable, List, Optional
+
+from .blocks import Norm, extract_blocks, normalize
+from .config import RULES_PATH, Config, Lock
+from .models import Approval, Decision, FileChange, Violation
+
+
+def change_digest(lock_id: str, path: str, old: Optional[Norm], new: Optional[Norm]) -> str:
+    payload = json.dumps(
+        [lock_id, path, None if old is None else list(old), None if new is None else list(new)]
+    )
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
+
+def _norm(text: Optional[str]) -> Optional[Norm]:
+    return None if text is None else normalize(text)
+
+
+def evaluate(
+    config: Config,
+    changes: Iterable[FileChange],
+    actor: str,
+    approvals: Iterable[Approval] = (),
+) -> Decision:
+    approvals = list(approvals)
+    decision = Decision()
+
+    def authorized_for(lock: Lock) -> set:
+        return set(lock.owners) | set(config.leaders)
+
+    def check(lock_id: str, lock: Optional[Lock], path: str, what: str, old, new) -> None:
+        owners_and_leaders = authorized_for(lock) if lock else set(config.leaders)
+        if actor in owners_and_leaders:
+            return
+        approvers = owners_and_leaders | (set(lock.approvers) if lock else set())
+        digest = change_digest(lock_id, path, old, new)
+        for a in approvals:
+            if (
+                a.lock_id == lock_id
+                and a.digest == digest
+                and a.approver != actor
+                and a.approver in approvers
+            ):
+                return
+        ask = ", ".join(sorted(approvers)) or "(nobody configured)"
+        decision.violations.append(
+            Violation(lock_id, path, "%s '%s' in %s is locked; ask: %s" % (what, lock_id, path, ask), digest)
+        )
+
+    for ch in changes:
+        old, new = _norm(ch.old), _norm(ch.new)
+
+        if ch.path == RULES_PATH:
+            if old != new and actor not in config.leaders:
+                decision.violations.append(
+                    Violation("<rules>", ch.path, "the rules file may only be changed by leaders: " + ", ".join(sorted(config.leaders)))
+                )
+            continue
+
+        for lock in config.locks:
+            if lock.matches_path(ch.path) and old != new:
+                check(lock.id, lock, ch.path, "path lock", old, new)
+
+        old_blocks = extract_blocks(ch.old) if ch.old is not None else {}
+        new_blocks = extract_blocks(ch.new) if ch.new is not None else {}
+        for block_id in sorted(set(old_blocks) | set(new_blocks)):
+            o, n = old_blocks.get(block_id), new_blocks.get(block_id)
+            if o != n:
+                check(block_id, config.get(block_id), ch.path, "block", o, n)
+
+    return decision

tripwire/gitea.py

@@ -0,0 +1,71 @@
+"""Gitea / Forgejo adapter: approvals come from pull-request reviews.
+
+A review counts when it is the reviewer's latest decisive review, its state is
+APPROVED, it is neither stale nor dismissed, and it was made on the PR's
+current head commit.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Dict, Iterable, List, Optional, Set
+from urllib.parse import quote
+
+from .config import ConfigError
+from .httpjson import Fetch, get_all, urlopen_fetch
+from .models import Decision
+from .review import check_review
+
+
+class GiteaClient:
+    def __init__(self, repo: str, api_url: str, token: Optional[str] = None, fetch: Optional[Fetch] = None):
+        self.repo, self.api_url = repo, api_url.rstrip("/")
+        headers = {"Accept": "application/json"}
+        if token:
+            headers["Authorization"] = "token " + token
+        self._fetch = fetch or urlopen_fetch(headers)
+
+    @classmethod
+    def from_env(cls, repo: Optional[str] = None, api_url: Optional[str] = None) -> "GiteaClient":
+        repo = repo or os.environ.get("GITEA_REPOSITORY") or os.environ.get("GITHUB_REPOSITORY")
+        if not repo:
+            raise ConfigError("repository unknown; pass --gitea-repo or set GITHUB_REPOSITORY")
+        api_url = api_url or os.environ.get("GITEA_API_URL") or os.environ.get("GITHUB_API_URL")
+        if not api_url and os.environ.get("GITHUB_SERVER_URL"):
+            api_url = os.environ["GITHUB_SERVER_URL"].rstrip("/") + "/api/v1"
+        if not api_url:
+            raise ConfigError("server unknown; pass --gitea-url (e.g. https://git.example.com/api/v1)")
+        return cls(repo, api_url, os.environ.get("GITEA_TOKEN") or os.environ.get("GITHUB_TOKEN"))
+
+    def _all(self, path: str, query: str = "") -> List[dict]:
+        return get_all(self._fetch, "%s/repos/%s/%s%s" % (self.api_url, self.repo, path, query))
+
+    def get_pull(self, number: int) -> dict:
+        return self._all("pulls/%d" % number)[0]
+
+    def get_reviews(self, number: int) -> List[dict]:
+        return self._all("pulls/%d/reviews" % number, "?limit=50")
+
+    def get_branch_sha(self, branch: str) -> str:
+        return self._all("branches/" + quote(branch, safe="/"))[0]["commit"]["id"]
+
+
+def approved_logins(reviews: Iterable[dict], head_sha: str) -> Set[str]:
+    latest: Dict[str, dict] = {}
+    for review in reviews:  # oldest first
+        user = (review.get("user") or {}).get("login")
+        if user and review.get("state") in ("APPROVED", "REQUEST_CHANGES"):
+            latest[user] = review
+    return {
+        u
+        for u, r in latest.items()
+        if r["state"] == "APPROVED" and not r.get("stale") and not r.get("dismissed") and r.get("commit_id") == head_sha
+    }
+
+
+def check_pull_request(root: str, client: GiteaClient, number: int) -> Decision:
+    pr = client.get_pull(number)
+    head_sha = pr["head"]["sha"]
+    approvers = approved_logins(client.get_reviews(number), head_sha)
+    target_sha = client.get_branch_sha(pr["base"]["ref"])
+    return check_review(root, target_sha, head_sha, pr["user"]["login"], approvers)

tripwire/github.py

@@ -0,0 +1,64 @@
+"""GitHub adapter: approvals come from pull-request reviews.
+
+A review only counts when it is the reviewer's latest review, its state is
+APPROVED, and it was made on the PR's current head commit. Pushing new commits
+therefore voids earlier approvals (the head sha changes).
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Dict, Iterable, List, Optional, Set
+from urllib.parse import quote
+
+from .config import ConfigError
+from .httpjson import Fetch, get_all, urlopen_fetch
+from .models import Decision
+from .review import check_review
+
+
+class GitHubClient:
+    def __init__(self, repo: str, token: Optional[str] = None, api_url: str = "https://api.github.com", fetch: Optional[Fetch] = None):
+        self.repo, self.api_url = repo, api_url.rstrip("/")
+        headers = {"Accept": "application/vnd.github+json"}
+        if token:
+            headers["Authorization"] = "Bearer " + token
+        self._fetch = fetch or urlopen_fetch(headers)
+
+    @classmethod
+    def from_env(cls, repo: Optional[str] = None) -> "GitHubClient":
+        repo = repo or os.environ.get("GITHUB_REPOSITORY")
+        if not repo:
+            raise ConfigError("repository unknown; pass --github-repo or set GITHUB_REPOSITORY")
+        return cls(repo, os.environ.get("GITHUB_TOKEN"), os.environ.get("GITHUB_API_URL", "https://api.github.com"))
+
+    def _all(self, path: str) -> List[dict]:
+        return get_all(self._fetch, "%s/repos/%s/%s?per_page=100" % (self.api_url, self.repo, path))
+
+    def get_pull(self, number: int) -> dict:
+        return self._all("pulls/%d" % number)[0]
+
+    def get_reviews(self, number: int) -> List[dict]:
+        return self._all("pulls/%d/reviews" % number)
+
+    def get_branch_sha(self, branch: str) -> str:
+        return self._all("branches/" + quote(branch, safe="/"))[0]["commit"]["sha"]
+
+
+def approved_logins(reviews: Iterable[dict], head_sha: str) -> Set[str]:
+    """Logins whose latest decisive review is an approval of `head_sha`."""
+    latest: Dict[str, dict] = {}
+    for review in reviews:  # the API returns reviews oldest-first
+        user = (review.get("user") or {}).get("login")
+        if user and review.get("state") in ("APPROVED", "CHANGES_REQUESTED", "DISMISSED"):
+            latest[user] = review
+    return {u for u, r in latest.items() if r["state"] == "APPROVED" and r.get("commit_id") == head_sha}
+
+
+def check_pull_request(root: str, client: GitHubClient, number: int) -> Decision:
+    pr = client.get_pull(number)
+    head_sha = pr["head"]["sha"]
+    approvers = approved_logins(client.get_reviews(number), head_sha)
+    # pr["base"]["sha"] is stale once the target branch moves; use its current tip for the rules.
+    target_sha = client.get_branch_sha(pr["base"]["ref"])
+    return check_review(root, target_sha, head_sha, pr["user"]["login"], approvers)

tripwire/gitio.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import os
+import subprocess
+from typing import List, Optional
+
+from .models import FileChange
+
+EMPTY_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904"
+ZERO = "0" * 40
+
+
+class GitError(Exception):
+    pass
+
+
+def git(cwd: str, *args: str, check: bool = True) -> bytes:
+    proc = subprocess.run(["git", *args], cwd=cwd, capture_output=True)
+    if check and proc.returncode != 0:
+        raise GitError("git %s failed: %s" % (" ".join(args), proc.stderr.decode("utf-8", "replace").strip()))
+    return proc.stdout if proc.returncode == 0 else b""
+
+
+def toplevel(cwd: str) -> str:
+    return git(cwd, "rev-parse", "--show-toplevel").decode().strip()
+
+
+class RevSource:
+    def __init__(self, cwd: str, rev: str):
+        self.cwd, self.rev = cwd, rev
+
+    def read(self, path: str) -> Optional[str]:
+        proc = subprocess.run(["git", "show", "%s:%s" % (self.rev, path)], cwd=self.cwd, capture_output=True)
+        return proc.stdout.decode("utf-8", "replace") if proc.returncode == 0 else None
+
+
+class WorktreeSource:
+    def __init__(self, root: str):
+        self.root = root
+
+    def read(self, path: str) -> Optional[str]:
+        full = os.path.join(self.root, path)
+        if not os.path.isfile(full):
+            return None
+        with open(full, "rb") as fh:
+            return fh.read().decode("utf-8", "replace")
+
+
+def _split(raw: bytes) -> List[str]:
+    return [p.decode("utf-8") for p in raw.split(b"\0") if p]
+
+
+def changed_paths(cwd: str, base: str, head: Optional[str]) -> List[str]:
+    """head=None is the working tree, head="" is the index (staged changes)."""
+    if head == "":
+        return _split(git(cwd, "diff", "--cached", "--name-only", "-z", "--no-renames", base))
+    if head is not None:
+        return _split(git(cwd, "diff", "--name-only", "-z", "--no-renames", base, head))
+    tracked = _split(git(cwd, "diff", "--name-only", "-z", "--no-renames", base))
+    untracked = _split(git(cwd, "ls-files", "--others", "--exclude-standard", "-z"))
+    return sorted(set(tracked) | set(untracked))
+
+
+def collect_changes(cwd: str, base: str, head: Optional[str]) -> List[FileChange]:
+    old_src = RevSource(cwd, base)
+    new_src = RevSource(cwd, head) if head is not None else WorktreeSource(cwd)
+    return [FileChange(p, old_src.read(p), new_src.read(p)) for p in changed_paths(cwd, base, head)]
+
+
+def new_branch_base(cwd: str, new: str) -> Optional[str]:
+    """Base for a newly created branch: parent of its first not-yet-known commit."""
+    out = git(cwd, "rev-list", "--reverse", new, "--not", "--all").decode().split()
+    if not out:
+        return None
+    proc = subprocess.run(["git", "rev-parse", out[0] + "^"], cwd=cwd, capture_output=True)
+    return proc.stdout.decode().strip() if proc.returncode == 0 else EMPTY_TREE

tripwire/gitlab.py

@@ -0,0 +1,66 @@
+"""GitLab adapter: approvals come from merge-request approvals.
+
+The approvals endpoint is not tied to a commit, so stale approvals are only
+voided if the project setting "Remove all approvals when commits are added to
+the source branch" is enabled. Turn it on; tripwire cannot verify it.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Iterable, List, Optional, Set
+from urllib.parse import quote
+
+from .config import ConfigError
+from .httpjson import Fetch, get_all, urlopen_fetch
+from .models import Decision
+from .review import check_review
+
+
+class GitLabClient:
+    def __init__(self, project: str, token: Optional[str] = None, api_url: str = "https://gitlab.com/api/v4",
+                 job_token: bool = False, fetch: Optional[Fetch] = None):
+        self.project, self.api_url = quote(str(project), safe=""), api_url.rstrip("/")
+        headers = {}
+        if token:
+            headers["JOB-TOKEN" if job_token else "PRIVATE-TOKEN"] = token
+        self._fetch = fetch or urlopen_fetch(headers)
+
+    @classmethod
+    def from_env(cls, project: Optional[str] = None) -> "GitLabClient":
+        project = project or os.environ.get("CI_PROJECT_ID")
+        if not project:
+            raise ConfigError("project unknown; pass --gitlab-project or set CI_PROJECT_ID")
+        api_url = os.environ.get("CI_API_V4_URL", "https://gitlab.com/api/v4")
+        token = os.environ.get("GITLAB_TOKEN")
+        if token:
+            return cls(project, token, api_url)
+        return cls(project, os.environ.get("CI_JOB_TOKEN"), api_url, job_token=True)
+
+    def _all(self, path: str) -> List[dict]:
+        return get_all(self._fetch, "%s/projects/%s/merge_requests/%s" % (self.api_url, self.project, path))
+
+    def get_merge_request(self, iid: int) -> dict:
+        return self._all("%d" % iid)[0]
+
+    def get_approvals(self, iid: int) -> dict:
+        return self._all("%d/approvals" % iid)[0]
+
+    def get_branch_sha(self, branch: str) -> str:
+        url = "%s/projects/%s/repository/branches/%s" % (self.api_url, self.project, quote(branch, safe=""))
+        return get_all(self._fetch, url)[0]["commit"]["id"]
+
+
+def approved_usernames(approvals: dict) -> Set[str]:
+    return {(a.get("user") or {}).get("username") for a in approvals.get("approved_by", [])} - {None}
+
+
+def check_merge_request(root: str, client: GitLabClient, iid: int) -> Decision:
+    mr = client.get_merge_request(iid)
+    refs = mr.get("diff_refs") or {}
+    head_sha = mr.get("sha") or refs.get("head_sha")
+    if not head_sha:
+        raise ConfigError("merge request has no diff refs yet; try again once GitLab has computed the diff")
+    # diff_refs.start_sha is stale once the target branch moves; use its current tip for the rules.
+    target_sha = client.get_branch_sha(mr["target_branch"])
+    return check_review(root, target_sha, head_sha, mr["author"]["username"], approved_usernames(client.get_approvals(iid)))

tripwire/httpjson.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import json
+import urllib.request
+from typing import Callable, Dict, List, Optional, Tuple
+
+Fetch = Callable[[str], Tuple[bytes, str]]  # url -> (body, Link header)
+
+
+def urlopen_fetch(headers: Dict[str, str]) -> Fetch:
+    def fetch(url: str) -> Tuple[bytes, str]:
+        req = urllib.request.Request(url, headers=headers)
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            return resp.read(), resp.headers.get("Link", "")
+
+    return fetch
+
+
+def next_link(link: str) -> Optional[str]:
+    for part in link.split(","):
+        if 'rel="next"' in part and "<" in part:
+            return part[part.index("<") + 1 : part.index(">")]
+    return None
+
+
+def get_all(fetch: Fetch, url: Optional[str]) -> List[dict]:
+    """GET a URL and follow Link rel=next; a single object becomes a 1-item list."""
+    items: List[dict] = []
+    while url:
+        body, link = fetch(url)
+        data = json.loads(body)
+        items.extend(data if isinstance(data, list) else [data])
+        url = next_link(link)
+    return items

tripwire/models.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+
+@dataclass(frozen=True)
+class FileChange:
+    path: str
+    old: Optional[str]  # None: file did not exist before
+    new: Optional[str]  # None: file no longer exists
+
+
+@dataclass(frozen=True)
+class Approval:
+    lock_id: str
+    approver: str
+    digest: str  # binds the approval to the exact before/after content
+
+
+@dataclass(frozen=True)
+class Violation:
+    lock_id: str
+    path: str
+    message: str
+    digest: str = ""
+
+
+@dataclass
+class Decision:
+    violations: List[Violation] = field(default_factory=list)
+
+    @property
+    def allowed(self) -> bool:
+        return not self.violations

tripwire/review.py

@@ -0,0 +1,33 @@
+"""Platform-neutral review check shared by the GitHub and GitLab adapters."""
+
+from __future__ import annotations
+
+from typing import Dict, Iterable
+
+from .config import RULES_PATH, parse_config
+from .engine import evaluate
+from .gitio import RevSource, collect_changes, git
+from .models import Approval, Decision
+
+
+def check_review(root: str, target_sha: str, head_sha: str, author: str, approvers: Iterable[str]) -> Decision:
+    """Evaluate a pull/merge request.
+
+    Rules come from the target branch tip (`target_sha`), the diff from the
+    merge base to `head_sha`. `approvers` are platform user names whose approval
+    applies to the current head; names are matched to the rules case-insensitively.
+    """
+    rules = RevSource(root, target_sha).read(RULES_PATH)
+    if rules is None:
+        return Decision()
+    config = parse_config(rules)
+    names: Dict[str, str] = {name.lower(): name for name in config.everyone()}
+    actor = names.get(author.lower(), author)
+
+    merge_base = git(root, "merge-base", target_sha, head_sha).decode().strip()
+    changes = collect_changes(root, merge_base, head_sha)
+
+    first = evaluate(config, changes, actor, [])
+    reviewers = sorted({names[u.lower()] for u in approvers if u.lower() in names})
+    approvals = [Approval(v.lock_id, who, v.digest) for v in first.violations if v.digest for who in reviewers]
+    return evaluate(config, changes, actor, approvals)

tripwire_git-0.1.0.dist-info/METADATA

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: tripwire-git
+Version: 0.1.0
+Summary: Protect blocks of code in Git: changes need approval from an owner, an approver or a leader.
+License: MIT
+Keywords: git,code-owners,approval,pre-receive,ci
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# tripwire
+
+Protect blocks of code in Git. A protected block can only be changed by its
+owner or a leader, or by someone whose change an authorized person approved.
+Works from a local pre-commit check, a self-hosted `pre-receive` hook, or as a
+required check on GitHub, GitLab and Gitea / Forgejo.
+
+## Quick start
+
+1. Mark a block in any language, inside a comment:
+
+   ```python
+   # @lock-begin billing
+   RATE = 5
+   # @lock-end billing
+   ```
+
+2. Create `.tripwire/locks.json` (see `locks.example.json`):
+
+   ```json
+   {
+     "leaders": ["alice"],
+     "locks": [
+       {"id": "billing", "owners": ["bob"], "approvers": ["carol"]},
+       {"id": "prod-config", "owners": ["bob"], "paths": ["config/prod/", "*.pem"]}
+     ]
+   }
+   ```
+
+3. Check a change:
+
+   ```bash
+   pip install tripwire-git
+   tripwire preflight --actor dave        # uncommitted changes vs HEAD
+   ```
+
+   Output: `tripwire: BLOCKED` with `block 'billing' in app.py is locked; ask:
+   alice, bob, carol`, exit code 1.
+
+## Concepts
+
+- Blocks are marked with `@lock-begin <id>` / `@lock-end <id>`; files and
+  folders are locked with path patterns (`dir/` prefix or glob).
+- Owners and leaders may edit freely. Anyone else needs an approval from an
+  owner, an approver or a leader. You cannot approve your own change.
+- Approvals are bound to the exact before/after content of the protected
+  block (a SHA-256 digest). Edit the code again and the approval is void.
+- Rules are always read from the **base** revision (the target branch), so a
+  change cannot rewrite the rules that judge it. Changing the rules file is
+  leaders-only and cannot be approved.
+- Whitespace-only edits are ignored. Deleting markers counts as a change.
+  Unclosed blocks extend to end of file. A marker whose id is missing from the
+  rules is leaders-only.
+
+## Commands
+
+```bash
+tripwire preflight --actor alice                              # uncommitted changes vs HEAD
+tripwire check --base origin/main --head HEAD --actor alice   # a commit range
+tripwire approve --base origin/main --head HEAD --approver carol  # local approvals file
+tripwire preflight --staged                                   # staged changes only
+tripwire install-hook                                         # local pre-commit hook
+tripwire pre-receive                                          # server hook, reads stdin
+tripwire github-check | gitlab-check | gitea-check            # pull / merge requests
+```
+
+Exit codes: 0 allowed, 1 blocked, 2 error (fails closed).
+
+## Local early warning
+
+`tripwire install-hook` installs a `pre-commit` hook that checks staged changes
+and refuses the commit when a protected block is touched without permission
+(or use `.pre-commit-hooks.yaml` with the pre-commit framework). Your Git
+identity (`git config user.email`, or `TRIPWIRE_ACTOR`) must match a name in
+`locks.json`. This is a convenience: `git commit --no-verify` skips it, so the
+server-side or CI check below remains the real gate. Nothing can stop someone
+from editing files in their own clone; tripwire stops unapproved changes from
+landing on protected branches.
+
+## Platforms
+
+| Platform | Enforce with | Approvals from | Verified |
+|---|---|---|---|
+| Self-hosted Git | `hooks/pre-receive` | `.tripwire/approvals.json` | real git repos |
+| GitHub | required check, `templates/github-actions.yml` | PR reviews | real GitHub |
+| GitLab | required pipeline, `templates/gitlab-ci.yml` | MR approvals | simulated API only |
+| Gitea / Forgejo | required check, `templates/gitea-actions.yml` | PR reviews | simulated API only |
+
+On hosted services, also forbid direct pushes to the protected branch and add a
+path lock for the CI configuration, otherwise a PR can delete the check.
+
+**Self-hosted Git.** Copy `hooks/pre-receive` into the bare repo and set
+`TRIPWIRE_ACTOR` from your server's authenticated user.
+
+**GitHub.** Only a reviewer's latest review counts; it must be `APPROVED` on
+the PR's current head commit, so a new push voids it. Reviewer logins are
+matched to names in `locks.json` case-insensitively; teams are not supported.
+
+**GitLab.** Store a `read_api` project access token as `GITLAB_TOKEN`. GitLab's
+approvals endpoint is not bound to a commit, so enable "Remove all approvals
+when commits are added to the source branch"; tripwire cannot verify it.
+
+**Gitea / Forgejo.** Enable "Dismiss stale approvals". Stale and dismissed
+reviews are ignored. The API base comes from `--gitea-url`, `GITEA_API_URL`,
+`GITHUB_API_URL` or `GITHUB_SERVER_URL`.
+
+## Architecture
+
+- `engine.py`: platform-neutral core (diff + actor + rules + approvals -> decision)
+- `review.py`: shared pull / merge request check used by the platform adapters
+- `github.py`, `gitlab.py`, `gitea.py`: API clients and approval mapping
+- `approvals.py`: local approvals file
+- `gitio.py`, `cli.py`: Git access and command line
+
+## Limits
+
+- Identity comes from `--actor` / `TRIPWIRE_ACTOR` locally; it is only as
+  trustworthy as whatever sets it. On hosted platforms it is the PR author.
+- The local approvals file is trust-based: anyone able to commit could write an
+  entry naming an approver. Use platform approvals for real deployments.
+- On every platform, people who can edit branch protection or CI settings are
+  trusted; tripwire cannot stop an admin from switching the rule off.
+- Pushes with several authors are checked as one cumulative diff by the pusher.
+- Whitespace-insensitive comparison also ignores indentation changes.
+- Not yet: platform teams, Bitbucket, Azure DevOps, Gerrit, CODEOWNERS import.
+
+## Development
+
+```bash
+pip install -e .[dev]
+pytest
+```
+
+## License
+
+MIT

tripwire_git-0.1.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+tripwire/__init__.py,sha256=Tspa12_SJOhu1FozTxrEaul0g-Svx_SrnbgZf1Y7Bm8,92
+tripwire/__main__.py,sha256=E6Gls0DNz8GQK2K-kOUIx8cYhgANW_CH54VKrfCfs14,52
+tripwire/approvals.py,sha256=4J5-zM9E_CDPluCPCEUJRgw8ya2ULPxI8KMmhEE1Qjk,894
+tripwire/blocks.py,sha256=q1upIMSmoQKzrDWe4OFxt4mdhqxHkEzsfwmlgJSyDQ0,1299
+tripwire/cli.py,sha256=hLFCc2nQ34Qv4_QXZv1SxcutrLVHHKEF-DHvclbHDXQ,9433
+tripwire/config.py,sha256=kzRjuKPWs3Vb3rde8sk73PXThTtJu1Mlnbx4HVopyBw,2339
+tripwire/engine.py,sha256=CgKqt2lMhj9an6gqeMDCKhkjaKsj_NmzO6_5HYoO1r8,2832
+tripwire/gitea.py,sha256=y_f_VOgcZwb6GM-Q0G-IS_YIF9qFQPSMKYCjgcruzds,3065
+tripwire/github.py,sha256=XAy3SsjVlIKEv8MywgPs-Z5w3mhM4Tg2HPddxlZ-IHw,2828
+tripwire/gitio.py,sha256=20b9mTeh4qgW0GR9Kt1jTjAw5tfHOwj_uIP8v9ZKHmY,2802
+tripwire/gitlab.py,sha256=x_a0HkteJ4_9jP_5_1xP627E2sSQ-8XoBQ-8V4C1T0Q,2921
+tripwire/httpjson.py,sha256=HH0NXYqROcuUPoU4E0AzI9IYUAt5wJGg4l4OaiF-0-s,1074
+tripwire/models.py,sha256=8FldPQdHMuDSxzyUjqbPnzCfGOXG5MzjtiCtsIaGtHw,714
+tripwire/review.py,sha256=lvMtbt0iyaaJx-q7EBsOuQrBjzIKfhp8GiFSfa9dhS4,1419
+tripwire_git-0.1.0.dist-info/licenses/LICENSE,sha256=CKxFnG2lCnx7ytEwNI9slqCiZcIyV3FLWTE8ufLtL0M,1078
+tripwire_git-0.1.0.dist-info/METADATA,sha256=Aw1pkN3RCTlORl52LXi2AaRE9SfuFz4DCW7kqCR29go,6443
+tripwire_git-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+tripwire_git-0.1.0.dist-info/entry_points.txt,sha256=BDrNZ8ucyqLLgBgUG5f7gF1GQZ-RW7MEGNdQrRLr-H8,47
+tripwire_git-0.1.0.dist-info/top_level.txt,sha256=Te7fsf-kKieL2zXPlqn5J6WVkel0JEr5Heqg66N3FuM,9
+tripwire_git-0.1.0.dist-info/RECORD,,

tripwire_git-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

tripwire_git-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tripwire = tripwire.cli:main

tripwire_git-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 codelock contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tripwire_git-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+tripwire