provtrail 0.1.0__py3-none-any.whl

provtrail/__init__.py

@@ -0,0 +1,28 @@
+"""provtrail: a minimal, verifiable source chain-of-custody ledger."""
+
+from .ledger import (
+    STATE_MISSING,
+    STATE_PRESENT,
+    STATE_UNKNOWN,
+    CheckResult,
+    ContractError,
+    Ledger,
+    LedgerError,
+    LockTimeout,
+    VerifyReport,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Ledger",
+    "VerifyReport",
+    "CheckResult",
+    "ContractError",
+    "LockTimeout",
+    "LedgerError",
+    "STATE_PRESENT",
+    "STATE_MISSING",
+    "STATE_UNKNOWN",
+    "__version__",
+]

provtrail/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

provtrail/cli.py

@@ -0,0 +1,181 @@
+"""Command-line interface for provtrail.
+
+Usage:
+    provtrail add LEDGER (--url U | --content-file F | --content-text S) ...
+    provtrail verify LEDGER [--check-files] [--json]
+    provtrail check LEDGER [--since ISO] [--until ISO] [--session-id ID] [--enforce] [--json]
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from typing import List, Optional
+
+from .ledger import (
+    STATE_MISSING,
+    CheckResult,
+    ContractError,
+    Ledger,
+    LedgerError,
+    LockTimeout,
+    VerifyReport,
+)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="provtrail", description=__doc__)
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    add_p = sub.add_parser("add", help="append one record to a ledger")
+    add_p.add_argument("ledger", help="path to the ledger JSONL file")
+    add_p.add_argument("--url", dest="source_url", default=None, help="source URL")
+    add_p.add_argument(
+        "--content-file", dest="content_file", default=None,
+        help="path to a file whose content is hashed for content_hash",
+    )
+    add_p.add_argument(
+        "--content-text", dest="content_text", default=None,
+        help="literal text content hashed for content_hash",
+    )
+    add_p.add_argument("--kind", default="url", help="record kind (default: url)")
+    add_p.add_argument("--tool", default=None, help="capturing tool/backend name")
+    add_p.add_argument("--query", default=None, help="search query, if applicable")
+    add_p.add_argument("--title", default=None, help="source title")
+    add_p.add_argument("--claim", default=None, help="the claim this source supports")
+    add_p.add_argument("--snippet", default=None, help="short supporting excerpt")
+    add_p.add_argument("--archived-url", default=None, help="archived copy URL")
+    add_p.add_argument(
+        "--path", default=None,
+        help="artifact path, relative to the ledger's directory",
+    )
+    add_p.add_argument(
+        "--session-id",
+        default=os.environ.get("CLAUDE_CODE_SESSION_ID"),
+        help="session identifier (default: $CLAUDE_CODE_SESSION_ID)",
+    )
+
+    verify_p = sub.add_parser("verify", help="verify a ledger's integrity")
+    verify_p.add_argument("ledger", help="path to the ledger JSONL file")
+    verify_p.add_argument(
+        "--check-files", action="store_true",
+        help="also re-hash referenced artifact files and compare",
+    )
+    verify_p.add_argument("--json", action="store_true", help="print JSON output")
+
+    check_p = sub.add_parser("check", help="report whether a source was captured")
+    check_p.add_argument("ledger", help="path to the ledger JSONL file")
+    check_p.add_argument(
+        "--since", default=None,
+        help="only count records captured at/after this RFC3339 timestamp",
+    )
+    check_p.add_argument(
+        "--until", default=None,
+        help="only count records captured at/before this RFC3339 timestamp",
+    )
+    check_p.add_argument(
+        "--session-id", default=None,
+        help="only count records with this exact session_id",
+    )
+    check_p.add_argument(
+        "--enforce", action="store_true",
+        help="exit 2 if state is MISSING (UNKNOWN never blocks)",
+    )
+    check_p.add_argument("--json", action="store_true", help="print JSON output")
+
+    return parser
+
+
+def _cmd_add(args: argparse.Namespace) -> int:
+    content = args.content_text
+    content_path = args.content_file
+    ledger = Ledger(args.ledger)
+    try:
+        record = ledger.add(
+            source_url=args.source_url,
+            content=content,
+            content_path=content_path,
+            kind=args.kind,
+            tool=args.tool,
+            query=args.query,
+            title=args.title,
+            claim=args.claim,
+            snippet=args.snippet,
+            archived_url=args.archived_url,
+            path=args.path,
+            session_id=args.session_id,
+        )
+    except LockTimeout as e:
+        print(f"provtrail add: {e}", file=sys.stderr)
+        return 1
+    except (ContractError, ValueError, LedgerError, OSError) as e:
+        print(f"provtrail add: rejected: {e}", file=sys.stderr)
+        return 1
+    print(json.dumps(record, ensure_ascii=False, indent=2))
+    return 0
+
+
+def _print_verify_report(report: VerifyReport, as_json: bool) -> None:
+    if as_json:
+        print(json.dumps(report.to_dict(), ensure_ascii=False, indent=2))
+        return
+    if report.ok:
+        print(f"OK: {report.record_count} record(s) verified, no violations.")
+        return
+    print(
+        f"FAILED: {report.record_count} record(s) checked, "
+        f"{len(report.violations)} violation(s):"
+    )
+    for v in report.violations:
+        print(f"  seq/line {v['seq_or_line']}: {v['code']}: {v['message']}")
+
+
+def _cmd_verify(args: argparse.Namespace) -> int:
+    ledger = Ledger(args.ledger)
+    try:
+        report = ledger.verify(check_files=args.check_files)
+    except LedgerError as e:
+        if args.json:
+            print(json.dumps({"ok": False, "error": str(e)}, ensure_ascii=False))
+        else:
+            print(f"provtrail verify: {e}", file=sys.stderr)
+        return 1
+    _print_verify_report(report, args.json)
+    return 0 if report.ok else 1
+
+
+def _print_check_result(result: CheckResult, as_json: bool) -> None:
+    if as_json:
+        print(json.dumps(result.to_dict(), ensure_ascii=False, indent=2))
+        return
+    print(f"{result.state}: {result.reason}")
+
+
+def _cmd_check(args: argparse.Namespace) -> int:
+    ledger = Ledger(args.ledger)
+    result = ledger.check(since=args.since, session_id=args.session_id, until=args.until)
+    _print_check_result(result, args.json)
+    if args.enforce and result.state == STATE_MISSING:
+        return 2
+    return 0
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "add":
+        return _cmd_add(args)
+    if args.command == "verify":
+        return _cmd_verify(args)
+    if args.command == "check":
+        return _cmd_check(args)
+
+    parser.print_help(sys.stderr)
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

provtrail/config.py

@@ -0,0 +1,89 @@
+"""Shared configuration resolution for provtrail integrations.
+
+Used by both the Claude Code Stop hook (``integrations/claude-code/
+stop_hook.py``) and the MCP server (``integrations/mcp/provtrail_mcp.py``)
+so the two agree on where the ledger lives and which mode applies.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any, Dict, Optional, Tuple
+
+MODE_REPORT = "report"
+MODE_ENFORCE = "enforce"
+MODE_STRICT = "strict"
+VALID_MODES = (MODE_REPORT, MODE_ENFORCE, MODE_STRICT)
+
+CONFIG_FILENAME = ".provtrail.json"
+
+
+def _load_config_file(cwd: str) -> Dict[str, Any]:
+    config_path = os.path.join(cwd, CONFIG_FILENAME)
+    if not os.path.isfile(config_path):
+        return {}
+    with open(config_path, "r", encoding="utf-8") as f:
+        cfg = json.load(f)
+    if not isinstance(cfg, dict):
+        raise ValueError(f"{config_path}: expected a JSON object")
+    return cfg
+
+
+def _validate_mode(value: Any) -> str:
+    if value not in VALID_MODES:
+        raise ValueError(
+            f"invalid provtrail mode {value!r}; must be one of {list(VALID_MODES)}"
+        )
+    return value
+
+
+def _resolve_mode(cfg: Dict[str, Any]) -> str:
+    env_mode = os.environ.get("PROVTRAIL_MODE")
+    if env_mode:
+        return _validate_mode(env_mode)
+
+    if os.environ.get("PROVTRAIL_ENFORCE") == "1":
+        return MODE_ENFORCE
+
+    cfg_mode = cfg.get("mode")
+    if cfg_mode:
+        return _validate_mode(cfg_mode)
+
+    if bool(cfg.get("enforce", False)):
+        return MODE_ENFORCE
+
+    return MODE_REPORT
+
+
+def resolve_config(cwd: str) -> Tuple[Optional[str], str]:
+    """Resolve the ledger path and mode for the project at ``cwd``.
+
+    Ledger path: the ``PROVTRAIL_LEDGER`` environment variable if set,
+    else the ``"ledger"`` field of ``<cwd>/.provtrail.json``. A relative
+    path is joined to ``cwd``. Returns ``None`` if neither is configured.
+
+    Mode is resolved independently of the ledger path, so setting only
+    ``PROVTRAIL_LEDGER`` does not reset a mode configured in the file.
+    Precedence, highest first:
+        1. ``PROVTRAIL_MODE`` environment variable.
+        2. legacy ``PROVTRAIL_ENFORCE=1`` environment variable -> "enforce".
+        3. the config file's ``"mode"`` field.
+        4. legacy config ``"enforce": true`` -> "enforce".
+        5. default: "report".
+
+    Raises ``ValueError`` if the config file is not valid JSON, or if an
+    explicit mode value (env or config) is not one of "report",
+    "enforce", "strict".
+    """
+    cfg = _load_config_file(cwd)
+
+    env_ledger = os.environ.get("PROVTRAIL_LEDGER")
+    if env_ledger:
+        ledger_path: Optional[str] = os.path.join(cwd, env_ledger)
+    else:
+        cfg_ledger = cfg.get("ledger")
+        ledger_path = os.path.join(cwd, cfg_ledger) if cfg_ledger else None
+
+    mode = _resolve_mode(cfg)
+    return ledger_path, mode

provtrail/hashing.py

@@ -0,0 +1,92 @@
+"""Canonical JSON encoding and hashing helpers for provtrail.
+
+The chain-of-custody guarantee rests on one rule: every record hash is
+computed from a deterministic byte representation of the record. This
+module is the single place that defines that representation, so ledger
+writing and ledger verification can never silently drift apart.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any, Mapping
+
+SHA256_PREFIX = "sha256:"
+
+
+def canonical_json_bytes(obj: Mapping[str, Any]) -> bytes:
+    """Return the canonical JSON byte encoding used for hashing.
+
+    Canonical JSON = ``json.dumps(obj, sort_keys=True,
+    separators=(",", ":"), ensure_ascii=False)`` encoded as UTF-8.
+    """
+    return json.dumps(
+        obj, sort_keys=True, separators=(",", ":"), ensure_ascii=False
+    ).encode("utf-8")
+
+
+def sha256_hex(data: bytes) -> str:
+    """Return the lowercase hex sha256 digest of ``data``."""
+    return hashlib.sha256(data).hexdigest()
+
+
+def sha256_prefixed(data: bytes) -> str:
+    """Return ``sha256:<hex>`` for ``data``."""
+    return SHA256_PREFIX + sha256_hex(data)
+
+
+def sha256_of_text(text: str) -> str:
+    """Return ``sha256:<hex>`` for a text payload (UTF-8 encoded)."""
+    return sha256_prefixed(text.encode("utf-8"))
+
+
+def sha256_of_bytes(data: bytes) -> str:
+    """Return ``sha256:<hex>`` for a raw bytes payload."""
+    return sha256_prefixed(data)
+
+
+def sha256_of_file(path: str, chunk_size: int = 1024 * 1024) -> str:
+    """Stream-hash a file on disk and return ``sha256:<hex>``."""
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        while True:
+            chunk = f.read(chunk_size)
+            if not chunk:
+                break
+            h.update(chunk)
+    return SHA256_PREFIX + h.hexdigest()
+
+
+def is_valid_content_hash(value: Any) -> bool:
+    """Check whether ``value`` is a well-formed ``sha256:<64 hex>`` string."""
+    if not isinstance(value, str):
+        return False
+    if not value.startswith(SHA256_PREFIX):
+        return False
+    digest = value[len(SHA256_PREFIX):]
+    if len(digest) != 64:
+        return False
+    try:
+        int(digest, 16)
+    except ValueError:
+        return False
+    return True
+
+
+def record_hash(record: Mapping[str, Any]) -> str:
+    """Compute the ``record_hash`` for a record dict.
+
+    The hash is computed over the canonical JSON of the record WITHOUT
+    the ``record_hash`` key itself (a record cannot include its own hash
+    inside the hashed payload).
+
+    The ``id`` key is excluded for the same reason: ``id`` is defined as
+    ``"ev_" + record_hash[:16]`` (after the ``sha256:`` prefix), so it is
+    derived FROM ``record_hash`` and cannot also be an input to it without
+    circularity. ``record_hash`` is computed once, before ``id`` is
+    assigned, over a payload that contains neither key; excluding both
+    during verification recomputes the same payload.
+    """
+    payload = {k: v for k, v in record.items() if k not in ("record_hash", "id")}
+    return sha256_prefixed(canonical_json_bytes(payload))