trustline-cli 0.1.0__py3-none-any.whl

trustline/heuristics.py

@@ -0,0 +1,282 @@
+"""Static heuristic signals for prompt-injection / tampering in agent rules.
+
+v0.1 ships 15 read-only rules. They are intentionally conservative static
+matchers over plain text (and JSON structure for .mcp.json): no code execution,
+no network calls. A hit is a *signal* to surface to the user (or, via hooks,
+to block before the model trusts the file) -- not a verdict.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+
+# --------------------------------------------------------------------------
+# Rule plumbing
+# --------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class Rule:
+    id: str            # e.g. "T001"
+    name: str
+    severity: str      # "high" | "medium" | "low"
+    summary: str       # human explanation of what this rule looks for
+
+    # detect(text) -> list[Finding]-style hints, or empty list when clean.
+    # Implementations are plain functions below; we keep them small & testable.
+    detect: object = None  # callable(text: str) -> list[str]  (trigger descriptions)
+
+
+@dataclass(frozen=True)
+class Finding:
+    rule_id: str
+    severity: str
+    message: str
+    file: str = ""
+    line: int | None = None
+
+
+RULES: list[Rule] = []
+REGISTRY: dict[str, Rule] = {}
+
+
+def _register(rule_id: str, name: str, severity: str, summary: str):
+    def deco(fn):
+        rule = Rule(id=rule_id, name=name, severity=severity, summary=summary, detect=fn)
+        RULES.append(rule)
+        REGISTRY[rule_id] = rule
+        return rule
+    return deco
+
+
+# --------------------------------------------------------------------------
+# Shared matchers
+# --------------------------------------------------------------------------
+
+_URL = r"https?://[^\s\"'`\)\]]+"
+_SENSITIVE = r"(api[_-]?key|secret|token|password|credential|passwd|auth|env\b|env(?:ironment)?\s+variable|BEGIN\s+[A-Z ]*PRIVATE\s+KEY)"
+_EXFIL_VERB = r"(send|post|upload|exfiltrat|leak|expose|transmit|phoning?\s+home)"
+
+
+def _lines(text: str) -> list[tuple[int, str]]:
+    return [(i + 1, ln) for i, ln in enumerate(text.splitlines())]
+
+
+# --------------------------------------------------------------------------
+# T001-T015
+# --------------------------------------------------------------------------
+
+
+@_register("T001", "external-secret-exfil", "high",
+           "Instruction points at sending secrets / env vars to an external URL.")
+def _t001(text: str) -> list[str]:
+    hits = []
+    for line_no, ln in _lines(text):
+        low = ln.lower()
+        if re.search(_URL, ln) and re.search(_SENSITIVE, low, re.IGNORECASE) and re.search(_EXFIL_VERB, low):
+            hits.append(f"line {line_no}: secret-like data + exfiltration verb near a URL")
+    return hits
+
+
+@_register("T002", "download-and-execute", "high",
+           "Pipes a remote payload straight into a shell (curl|bash style).")
+def _t002(text: str) -> list[str]:
+    pat = re.compile(
+        r"(?:curl|wget|iwr|Invoke-WebRequest|powershell).{0,40}?(?:\||\b&\b|\bpipe\b).{0,40}?(?:bash|sh|zsh|fish|powershell|pwsh|python3?|node|perl)",
+        re.IGNORECASE,
+    )
+    return [f"line {n}: download-and-execute pattern" for n, ln in _lines(text) if pat.search(ln)]
+
+
+@_register("T003", "shell-profile-tamper", "high",
+           "Asks to modify the user's shell profile / rc files.")
+def _t003(text: str) -> list[str]:
+    pat = re.compile(r"(?:~?/?)\.(?:bashrc|zshrc|profile|bash_profile|zprofile|fish/config\.fish|inputrc)", re.IGNORECASE)
+    return [f"line {n}: shell-profile tampering reference" for n, ln in _lines(text) if pat.search(ln)]
+
+
+@_register("T004", "ssh-backdoor", "high",
+           "Asks to add SSH keys / authorized_keys entries.")
+def _t004(text: str) -> list[str]:
+    pat = re.compile(r"(authorized_keys|\.ssh/.*id_[a-z]+|ssh-copy-id|AddKeysToAgent)", re.IGNORECASE)
+    return [f"line {n}: SSH key / authorized_keys manipulation" for n, ln in _lines(text) if pat.search(ln)]
+
+
+@_register("T005", "privilege-escalation", "high",
+           "References sudoers / setuid / world-writable privilege changes.")
+def _t005(text: str) -> list[str]:
+    pat = re.compile(r"(sudoers|visudo|chmod\s+4777|setuid|setgid|NOPASSWD|/etc/passwd|useradd\s+-o\s+-u\s+0)", re.IGNORECASE)
+    return [f"line {n}: privilege-escalation pattern" for n, ln in _lines(text) if pat.search(ln)]
+
+
+@_register("T006", "persistence", "high",
+           "Schedules persistence: cron / systemd / launchd / startup items.")
+def _t006(text: str) -> list[str]:
+    pat = re.compile(
+        r"(crontab|@reboot|systemctl\s+enable|\[Install\].*WantedBy|LaunchAgent|launchctl|StartupItems|schtasks|HKLM\\...\\Run|HKCU\\...\\Run)",
+        re.IGNORECASE,
+    )
+    return [f"line {n}: persistence mechanism reference" for n, ln in _lines(text) if pat.search(ln)]
+
+
+@_register("T007", "obfuscated-payload", "high",
+           "Obfuscation: base64 / eval of encoded payloads.")
+def _t007(text: str) -> list[str]:
+    patterns = [
+        re.compile(r"base64\s*-d|base64\s*--decode|from\s+base64\s+import", re.IGNORECASE),
+        re.compile(r"\beval\s*\(|exec\(\s*['\"`]|perl\s+-e\s*['\"]|ruby\s+-e\s*['\"]", re.IGNORECASE),
+        re.compile(r"python3?\s+-c\s*['\"][^'\"]{200,}", re.IGNORECASE),
+        re.compile(r"node\s+-e\s*['\"][^'\"]{100,}", re.IGNORECASE),
+    ]
+    hits = []
+    for n, ln in _lines(text):
+        if any(p.search(ln) for p in patterns):
+            hits.append(f"line {n}: obfuscated / encoded payload")
+    return hits
+
+
+@_register("T008", "instruction-override", "high",
+           "Tells the agent to ignore earlier instructions / hide its actions.")
+def _t008(text: str) -> list[str]:
+    patterns = [
+        re.compile(r"(ignore|disregard|skip|forget|override)\s+(all\s+)?(prior|previous|above|system|earlier)\s*(instructions?|rules?|prompts?|directives?)", re.IGNORECASE),
+        re.compile(r"(do not|don'?t|never)\s+(tell|mention|reveal|show|inform)\s+(the\s+)?(user|human)", re.IGNORECASE),
+        re.compile(r"(reply|respond|answer)\s*(with|only)?\s*(ok|fine|done|yes|no)\b.{0,20}(regardless|ignore)", re.IGNORECASE),
+        re.compile(r"ignore\s+(all\s+)?previous\s+instructions?", re.IGNORECASE),
+    ]
+    hits = []
+    for n, ln in _lines(text):
+        if any(p.search(ln) for p in patterns):
+            hits.append(f"line {n}: instruction-override / concealment language")
+    return hits
+
+
+@_register("T009", "hide-from-git", "medium",
+           "Asks to keep changes out of git / commit history.")
+def _t009(text: str) -> list[str]:
+    patterns = [
+        re.compile(r"do not\s+(commit|push|提交|推送)", re.IGNORECASE),
+        re.compile(r"(don'?t|never)\s+(commit|push)\s+(this|these|it|the\s+file)", re.IGNORECASE),
+        re.compile(r"git\s+(rm\s+--cached|reset\s+HEAD|update-index\s+--skip-worktree)", re.IGNORECASE),
+        re.compile(r"add\s+(this\s+)?file\s+to\s+\.gitignore\s+.*(secret|token|key)", re.IGNORECASE),
+    ]
+    hits = []
+    for n, ln in _lines(text):
+        if any(p.search(ln) for p in patterns):
+            hits.append(f"line {n}: asks to hide from version control")
+    return hits
+
+
+@_register("T010", "mcp-supply-chain", "medium",
+           "MCP server runs an unpinned npx package or points at a non-official registry.")
+def _t010(text: str) -> list[str]:
+    """JSON-aware: parse inline .mcp.json fragments (best effort)."""
+    hits = []
+    try:
+        data = json.loads(text)
+        servers = data.get("mcpServers", {}) if isinstance(data, dict) else {}
+        for name, cfg in servers.items():
+            if not isinstance(cfg, dict):
+                continue
+            cmd = str(cfg.get("command", ""))
+            args = cfg.get("args", []) if isinstance(cfg.get("args"), list) else []
+            if "npx" in cmd.lower() or "uvx" in cmd.lower():
+                joined = " ".join(str(a) for a in args)
+                # unpinned: contains @latest or a bare package name with no @version
+                if "@latest" in joined or not re.search(r"@[\d.]+", joined):
+                    hits.append(f"MCP server '{name}': unpinned {cmd} package ({joined[:60]})")
+            url = cfg.get("url", "")
+            if isinstance(url, str) and re.search(_URL, url) and not re.search(r"(github|npmjs|registry\.npmjs)", url, re.IGNORECASE):
+                hits.append(f"MCP server '{name}': non-official remote url {url[:60]}")
+    except json.JSONDecodeError:
+        pass
+    return hits
+
+
+@_register("T011", "git-remote-tamper", "high",
+           "Points git remotes at unknown hosts.")
+def _t011(text: str) -> list[str]:
+    pat = re.compile(
+        r"git\s+remote\s+(add|set-url)\b.{0,60}?https?://(?![^\s]*?(github\.com|gitlab\.com|bitbucket\.org|git\.(sr\.ht|kernel\.org)))",
+        re.IGNORECASE,
+    )
+    return [f"line {n}: git remote pointing at non-official host" for n, ln in _lines(text) if pat.search(ln)]
+
+
+@_register("T012", "hardcoded-secret", "high",
+           "Asks to write real credentials into files.")
+def _t012(text: str) -> list[str]:
+    pat = re.compile(
+        r"(api[_-]?key|password|secret|token|client[_-]?secret)\s*[:=]\s*['\"][A-Za-z0-9_\-\.]{12,}['\"]",
+        re.IGNORECASE,
+    )
+    return [f"line {n}: hardcoded credential-looking literal" for n, ln in _lines(text) if pat.search(ln)]
+
+
+@_register("T013", "sensitive-file-read", "high",
+           "Reads cloud / SSH credentials or secrets from the environment.")
+def _t013(text: str) -> list[str]:
+    patterns = [
+        re.compile(r"(cat|type|print|read|open|copy|exfiltrat|upload).{0,60}?(~?/\.aws/credentials|~?/\.ssh/|/etc/(shadow|passwd|sudoers))", re.IGNORECASE),
+        re.compile(r"(print|echo|send|upload|export).{0,40}?(aws_|gcp_|azure_|OPENAI_API_KEY|ANTHROPIC_API_KEY|GITHUB_TOKEN|CI_)\w{0,30}?(=|env)", re.IGNORECASE),
+    ]
+    hits = []
+    for n, ln in _lines(text):
+        if any(p.search(ln) for p in patterns):
+            hits.append(f"line {n}: sensitive file / env access")
+    return hits
+
+
+@_register("T014", "masked-executable", "medium",
+           "Hides an executable payload behind a benign-looking name (logo, .cache...).")
+def _t014(text: str) -> list[str]:
+    pat = re.compile(
+        r"(\b(?:logo|avatar|image|icon|\.cache|\.thumbnails?|preview|banner)\w*\.(?:png|jpg|jpeg|gif|svg|ico|tmp|dat)\b)\s*(?:is|as|contains|writes?|runs?|executes?)\s*(?:a|an|the|shell|script|python|payload|binary|executable)?",
+        re.IGNORECASE,
+    )
+    return [f"line {n}: executable hidden behind benign name" for n, ln in _lines(text) if pat.search(ln)]
+
+
+@_register("T015", "encoded-interpreter", "high",
+           "Long inline interpreter payloads (python -c / node -e) inside rules.")
+def _t015(text: str) -> list[str]:
+    pat = re.compile(
+        r"\b(?:python3?|node|ruby|perl|php|bash|sh)\s+(?:-c|-e)\s*['\"][^'\"]{120,}",
+        re.IGNORECASE,
+    )
+    return [f"line {n}: long inline interpreter payload" for n, ln in _lines(text) if pat.search(ln)]
+
+
+# --------------------------------------------------------------------------
+# Public API
+# --------------------------------------------------------------------------
+
+
+def scan_text(text: str, file_rel: str = "") -> list[Finding]:
+    findings: list[Finding] = []
+    for rule in RULES:
+        fn = rule.detect
+        if fn is None:
+            continue
+        try:
+            triggers = fn(text) or []
+        except Exception:  # defensive: a rule must never crash the scan
+            continue
+        for trig in triggers:
+            findings.append(
+                Finding(
+                    rule_id=rule.id,
+                    severity=rule.severity,
+                    message=f"[{rule.name}] {trig}",
+                    file=file_rel,
+                    line=_first_line(trig) if False else None,
+                )
+            )
+    return findings
+
+
+def _first_line(trig: str) -> int | None:
+    m = re.match(r"line (\d+):", trig)
+    return int(m.group(1)) if m else None

trustline/hooks.py

@@ -0,0 +1,290 @@
+"""Claude Code hook wiring for Trustline.
+
+Installs / uninstalls hooks in ``.claude/settings.local.json`` (gitignored,
+per-machine) and implements ``hook-check`` -- the command the hooks invoke.
+
+Events (v1):
+- SessionStart          -> warn on out-of-baseline changes (cannot block)
+- PreToolUse (Write/Edit/NotebookEdit) -> block with exit 2 when the target
+  managed file carries a high-severity tamper signal
+- InstructionsLoaded    -> block when the loaded rules file is out of baseline
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import time
+from pathlib import Path
+
+from .baseline import compare, load
+from .config import Config
+
+HOOK_SECTION_KEY = "hooks"
+HOOK_COMMAND = "trustline hook-check"
+
+
+def _hook_config() -> dict:
+    """Hook commands intentionally pass no --root: Claude Code executes hooks
+    with the project directory as cwd, and {CLAUDE_PROJECT_DIR} is not
+    substituted in every Claude Code version / headless mode. hook-check falls
+    back to cwd when --root is omitted."""
+    return {
+        "SessionStart": [
+            {
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": f"{HOOK_COMMAND} --event session-start",
+                    }
+                ]
+            }
+        ],
+        "PreToolUse": [
+            {
+                "matcher": "Write|Edit|NotebookEdit",
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": f"{HOOK_COMMAND} --event pre-tool-use",
+                    }
+                ],
+            }
+        ],
+        "InstructionsLoaded": [
+            {
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": f"{HOOK_COMMAND} --event instructions-loaded",
+                    }
+                ]
+            }
+        ],
+    }
+
+
+def _settings_path(root: Path) -> Path:
+    return root / ".claude" / "settings.local.json"
+
+
+def install_hooks(root: Path) -> Path:
+    """Merge our hook section into .claude/settings.local.json."""
+    path = _settings_path(root)
+    data: dict = {}
+    if path.exists():
+        data = json.loads(path.read_text(encoding="utf-8"))
+    data.setdefault(HOOK_SECTION_KEY, {})
+    for event, groups in _hook_config().items():
+        # replace our groups for this event (idempotent), keep unrelated entries
+        existing = data[HOOK_SECTION_KEY].get(event, [])
+        ours = _hook_config()[event]
+        kept = [g for g in existing if not _is_trustline_group(g)]
+        data[HOOK_SECTION_KEY][event] = kept + ours
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    return path
+
+
+def uninstall_hooks(root: Path) -> bool:
+    path = _settings_path(root)
+    if not path.exists():
+        return False
+    data = json.loads(path.read_text(encoding="utf-8"))
+    section = data.get(HOOK_SECTION_KEY, {})
+    removed = False
+    for event in list(_hook_config().keys()):
+        groups = section.get(event, [])
+        kept = [g for g in groups if not _is_trustline_group(g)]
+        if len(kept) != len(groups):
+            removed = True
+        if kept:
+            section[event] = kept
+        else:
+            section.pop(event, None)
+    data[HOOK_SECTION_KEY] = section
+    if not section:
+        data.pop(HOOK_SECTION_KEY, None)
+    path.write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    return removed
+
+
+def _is_trustline_group(group: dict) -> bool:
+    for h in group.get("hooks", []):
+        if isinstance(h, dict) and h.get("type") == "command" and HOOK_COMMAND in str(h.get("command", "")):
+            return True
+    return False
+
+
+# --------------------------------------------------------------------------
+# hook-check
+# --------------------------------------------------------------------------
+
+_WRITE_TOOLS = {"Write", "Edit", "NotebookEdit", "MultiEdit"}
+
+
+def _extract_target_path(payload: dict) -> str | None:
+    """Best-effort extraction of the file path from a hook payload."""
+    tool_input = payload.get("tool_input") or {}
+    candidates = [tool_input.get("file_path"), tool_input.get("path"), payload.get("file_path"), payload.get("path")]
+    for c in candidates:
+        if isinstance(c, str) and c:
+            return c
+    # deep search fallback
+    for key in ("file_path", "path"):
+        val = payload.get(key)
+        if isinstance(val, str) and val:
+            return val
+    return None
+
+
+def _extract_incoming_text(payload: dict) -> str | None:
+    """Content the agent is ABOUT to write (PreToolUse fires before the write,
+    so the on-disk file is still the old one -- we must inspect the payload)."""
+    tool_input = payload.get("tool_input") or {}
+    for key in ("content", "new_string"):
+        val = tool_input.get(key)
+        if isinstance(val, str) and val:
+            return val
+    return None
+
+
+def _audit(cfg: Config, event: str, decision: str, rel: str, rules: list[str]) -> None:
+    """Append one JSONL line per hook decision so real-session behaviour is
+    observable. Never raises (auditing must not break the hook protocol)."""
+    try:
+        line = {
+            "ts": time.strftime("%Y-%m-%dT%H:%M:%S%z"),
+            "event": event,
+            "decision": decision,
+            "file": rel,
+            "rules": rules,
+        }
+        cfg.project_state.mkdir(parents=True, exist_ok=True)
+        with open(cfg.project_state / "audit.jsonl", "a", encoding="utf-8") as fh:
+            fh.write(json.dumps(line, ensure_ascii=False) + "\n")
+    except Exception:
+        pass
+
+
+def run_check(root: Path, event: str, payload: dict) -> int:
+    """Execute a hook event. Returns exit code:
+    0  -> ok (or nothing to do / no baseline)
+    1  -> non-blocking advisory (stderr already printed)
+    2  -> blocking (stderr explains why)
+    """
+    cfg = Config(root=root)
+    baseline = load(cfg)
+    if baseline is None:
+        sys.stderr.write("trustline: no baseline yet (run 'trustline init' to protect this project)\n")
+        return 0
+
+    if event == "session-start":
+        changes = compare(cfg, baseline)
+        if changes:
+            lines = "\n".join(f"  [{c.change_type}] {c.relpath}" for c in changes[:20])
+            _audit(cfg, event, "warned", "", [c.relpath for c in changes][:10])
+            sys.stderr.write(
+                f"trustline: {len(changes)} agent-config file(s) differ from trusted baseline:\n{lines}\n"
+                "Run 'trustline status' and 'trustline rollback' to inspect / restore.\n"
+            )
+        else:
+            _audit(cfg, event, "ok", "", [])
+        return 0
+
+    if event == "instructions-loaded":
+        rel = _extract_target_path(payload)
+        if rel:
+            return _block_if_out_of_baseline(cfg, baseline, rel, payload)
+        _audit(cfg, event, "ok", "", [])
+        return 0
+
+    if event == "pre-tool-use":
+        tool = payload.get("tool_name", "")
+        if tool not in _WRITE_TOOLS:
+            return 0
+        rel = _extract_target_path(payload)
+        if not rel:
+            return 0
+        resolved = _resolve_managed(cfg, rel)
+        if not resolved:
+            return 0
+        rel_norm, _target = resolved
+
+        # (1) Incoming content is the primary signal: PreToolUse runs BEFORE
+        #     the write, so scan the payload the agent wants to write.
+        incoming = _extract_incoming_text(payload)
+        if incoming:
+            from .heuristics import scan_text
+
+            incoming_findings = scan_text(incoming, file_rel=rel_norm)
+            high = [f for f in incoming_findings if f.severity == "high"]
+            if high:
+                _print_findings(high, "BLOCKED")
+                _audit(cfg, event, "blocked", rel_norm, [f.rule_id for f in high])
+                sys.stderr.write(
+                    "trustline: refusing to write tamper-like content into a managed agent-config file.\n"
+                )
+                return 2
+
+        # (2) Baseline drift on disk -> warn (do not block: the agent may be
+        #     legitimately fixing the file).
+        _warn_if_out_of_baseline(cfg, baseline, rel_norm)
+        _audit(cfg, event, "ok", rel_norm, [])
+        return 0
+
+    return 0
+
+
+def _is_managed_rel(cfg: Config, rel: str) -> bool:
+    from .config import is_managed
+
+    return is_managed(rel, cfg.patterns)
+
+
+def _resolve_managed(cfg: Config, rel: str) -> tuple[str, Path] | None:
+    rel = rel.strip()
+    while rel.startswith("./"):
+        rel = rel[2:]
+    if not _is_managed_rel(cfg, rel):
+        return None
+    target = cfg.root / Path(*rel.split("/"))
+    return rel, target
+
+
+def _block_if_out_of_baseline(cfg: Config, baseline, rel: str, payload: dict) -> int:
+    resolved = _resolve_managed(cfg, rel)
+    if not resolved:
+        return 0
+    rel_norm, target = resolved
+    changes = {c.relpath: c for c in compare(cfg, baseline)}
+    ch = changes.get(rel_norm)
+    if ch is not None and ch.change_type in ("modified", "deleted"):
+        sys.stderr.write(
+            f"trustline: BLOCKED loading '{rel_norm}' -- differs from trusted baseline ({ch.change_type}).\n"
+            "Run 'trustline status' / 'trustline rollback' to inspect and restore.\n"
+        )
+        return 2
+    if ch is not None and ch.change_type == "added":
+        sys.stderr.write(
+            f"trustline: notice: '{rel_norm}' is new (not in baseline). Review then 'trustline init' to trust it.\n"
+        )
+    return 0
+
+
+def _warn_if_out_of_baseline(cfg: Config, baseline, rel: str) -> None:
+    resolved = _resolve_managed(cfg, rel)
+    if not resolved:
+        return
+    rel_norm, _target = resolved
+    changes = {c.relpath: c for c in compare(cfg, baseline)}
+    if rel_norm in changes:
+        sys.stderr.write(
+            f"trustline: notice: '{rel_norm}' differs from trusted baseline ({changes[rel_norm].change_type}).\n"
+        )
+
+
+def _print_findings(findings, prefix: str) -> None:
+    for f in findings[:10]:
+        loc = f.file or "-"
+        sys.stderr.write(f"trustline: {prefix} {f.severity.upper()} [{f.rule_id}] {loc}: {f.message}\n")

trustline/rollback.py

@@ -0,0 +1,119 @@
+"""Rollback: restore managed files to their trusted state.
+
+Strategy (v1):
+1. If the file lives in a git working tree, restore from git HEAD (the most
+   recent committed state) -- but only when HEAD content matches the trusted
+   baseline content (otherwise the baseline predates HEAD and restoring HEAD
+   would *not* restore the trusted state).
+2. Otherwise (or when git can't help), restore from the content snapshot
+   stored by ``init`` under state_dir/projects/<root>/copies/<sha256>/.
+3. Soft rollback: the current (tampered) content is preserved as ``<file>.bak``
+   before overwrite, so a mistaken rollback is reversible.
+
+Exact-match semantics are the responsibility of the caller (CLI / hooks).
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+
+from .baseline import sha256_file
+from .config import Config, normalize_relpath
+
+
+class RollbackResult:
+    def __init__(self, relpath: str, ok: bool, detail: str) -> None:
+        self.relpath = relpath
+        self.ok = ok
+        self.detail = detail
+
+
+def _in_git_repo(root: Path) -> bool:
+    r = subprocess.run(
+        ["git", "-C", str(root), "rev-parse", "--is-inside-work-tree"],
+        capture_output=True, text=True, timeout=15,
+    )
+    return r.returncode == 0 and r.stdout.strip() == "true"
+
+
+def _git_head_matches(root: Path, relpath: str, expected_sha: str) -> bool:
+    """True when the file content at git HEAD hashes to expected_sha."""
+    r = subprocess.run(
+        ["git", "-C", str(root), "show", f"HEAD:{relpath}"],
+        capture_output=True, timeout=15,
+    )
+    if r.returncode != 0:
+        return False
+    import hashlib
+
+    return hashlib.sha256(r.stdout).hexdigest() == expected_sha
+
+
+def _git_restore(root: Path, relpath: str) -> bool:
+    r = subprocess.run(
+        ["git", "-C", str(root), "restore", "--source=HEAD", "--", relpath],
+        capture_output=True, text=True, timeout=30,
+    )
+    return r.returncode == 0
+
+
+def _restore_from_copy(config: Config, relpath: str, target_sha: str, target: Path) -> bool:
+    src = config.copies_dir / target_sha
+    if not src.is_file():
+        return False
+    target.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(src, target)
+    return True
+
+
+def rollback_file(config: Config, relpath: str, target_sha: str) -> RollbackResult:
+    """Restore ``relpath`` (relative to config.root) to content with
+    ``target_sha`` (from baseline entry)."""
+    target = config.root / Path(*relpath.split("/"))
+    if not target.exists():
+        # deleted file: recreate from snapshot (git can restore too)
+        if _in_git_repo(config.root) and _git_head_matches(config.root, relpath, target_sha):
+            if _git_restore(config.root, relpath):
+                return RollbackResult(relpath, True, "restored from git HEAD")
+        if _restore_from_copy(config, relpath, target_sha, target):
+            return RollbackResult(relpath, True, "recreated from trusted snapshot")
+        return RollbackResult(relpath, False, "file is deleted and no trusted snapshot/git copy available")
+
+    current_sha = sha256_file(target)
+    if current_sha == target_sha:
+        return RollbackResult(relpath, True, "already at trusted state")
+
+    # soft rollback: preserve tampered content OUTSIDE the project tree
+    # (state dir), so it never pollutes the working tree or the baseline.
+    bak_dir = config.project_state / "baks"
+    bak_dir.mkdir(parents=True, exist_ok=True)
+    bak = bak_dir / relpath
+    bak.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(target, bak)
+
+    restored = False
+    detail = ""
+    if _in_git_repo(config.root):
+        if _git_head_matches(config.root, relpath, target_sha):
+            restored = _git_restore(config.root, relpath)
+            detail = "restored from git HEAD"
+        elif _restore_from_copy(config, relpath, target_sha, target):
+            restored = True
+            detail = "restored from trusted snapshot (git HEAD differs from baseline)"
+    else:
+        restored = _restore_from_copy(config, relpath, target_sha, target)
+        detail = "restored from trusted snapshot"
+
+    if restored and sha256_file(target) != target_sha:
+        restored = False
+        detail = "restore produced unexpected content; kept .bak"
+
+    if not restored:
+        # put the tampered file back, keep .bak as the only copy of the truth
+        if bak.exists():
+            shutil.copy2(bak, target)
+        return RollbackResult(relpath, False, f"rollback failed ({detail or 'no source available'}); original kept")
+
+    return RollbackResult(relpath, True, f"{detail}; tampered copy kept at {bak}")