proofpacket 0.1.0__py3-none-any.whl

proofpacket/__init__.py

@@ -0,0 +1,9 @@
+"""ProofPacket: privacy-safe evidence packets for AI agent runs."""
+
+from proofpacket.hashing import VerificationResult, verify_receipt
+from proofpacket.receipt import Receipt
+
+Packet = Receipt
+
+__all__ = ["Packet", "Receipt", "VerificationResult", "verify_receipt"]
+__version__ = "0.1.0"

proofpacket/cli.py

@@ -0,0 +1,129 @@
+"""Command line interface for ProofPacket."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from proofpacket.exporters import export_markdown
+from proofpacket.hashing import verify_receipt
+from proofpacket.receipt import Receipt
+from proofpacket.schema import load_schema
+
+app = typer.Typer(help="Create, validate, verify, summarize, and export ProofPacket evidence packets.")
+
+
+def _load_receipt(path: Path) -> dict:
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+@app.command()
+def init(directory: Path = typer.Argument(Path("."), help="Directory to initialize.")) -> None:
+    """Create a minimal local ProofPacket policy and template packet."""
+    directory.mkdir(parents=True, exist_ok=True)
+    config_path = directory / "proofpacket.config.json"
+    template_path = directory / "proofpacket-template.json"
+    config_path.write_text(
+        json.dumps(
+            {
+                "privacy_mode": "hash_only",
+                "raw_capture_default": False,
+                "require_human_review_for_external_actions": True,
+            },
+            indent=2,
+        )
+        + "\n",
+        encoding="utf-8",
+    )
+    receipt = Receipt(task="example_task", actor="ai_agent")
+    receipt.note("Template packet initialized.")
+    receipt.finish(status="completed")
+    receipt.export_json(template_path)
+    typer.echo(f"Created {config_path}")
+    typer.echo(f"Created {template_path}")
+
+
+@app.command()
+def validate(receipt_path: Path) -> None:
+    """Validate a packet against the JSON schema."""
+    try:
+        from jsonschema import validate as jsonschema_validate
+    except ImportError as exc:  # pragma: no cover
+        raise typer.Exit(f"jsonschema is required for validation: {exc}")
+
+    receipt = _load_receipt(receipt_path)
+    jsonschema_validate(instance=receipt, schema=load_schema())
+    typer.echo("valid")
+
+
+@app.command()
+def verify(receipt_path: Path) -> None:
+    """Verify hash chain and packet hash."""
+    result = verify_receipt(_load_receipt(receipt_path))
+    if result.valid:
+        typer.echo("valid")
+        return
+    typer.echo("invalid")
+    for error in result.errors:
+        typer.echo(f"- {error}")
+    raise typer.Exit(1)
+
+
+@app.command()
+def summarize(receipt_path: Path) -> None:
+    """Print a human-readable packet summary."""
+    receipt = _load_receipt(receipt_path)
+    events = receipt.get("events", [])
+    providers = sorted(
+        {
+            event.get("metadata", {}).get("provider")
+            for event in events
+            if event.get("event_type") == "llm_call" and event.get("metadata", {}).get("provider")
+        }
+    )
+    tools = sorted(
+        {
+            event.get("metadata", {}).get("tool")
+            for event in events
+            if event.get("event_type") == "tool_call" and event.get("metadata", {}).get("tool")
+        }
+    )
+    source_buckets = sorted({event.get("bucket") for event in events if event.get("event_type") == "source_used"})
+    reviews = [event for event in events if event.get("event_type") == "human_review"]
+    typer.echo(f"Task: {receipt.get('task')}")
+    typer.echo(f"Status: {receipt.get('status')}")
+    typer.echo(f"Started: {receipt.get('started_at')}")
+    typer.echo(f"Finished: {receipt.get('finished_at')}")
+    typer.echo(f"Events: {len(events)}")
+    typer.echo(f"Model providers: {', '.join(providers) if providers else 'none'}")
+    typer.echo(f"Tools: {', '.join(tools) if tools else 'none'}")
+    typer.echo(f"Source buckets: {', '.join(source_buckets) if source_buckets else 'none'}")
+    typer.echo(f"Human reviews: {len(reviews)}")
+    typer.echo(f"Risk flags: {len(receipt.get('risk_flags', []))}")
+
+
+@app.command()
+def export(
+    receipt_path: Path,
+    markdown: Optional[Path] = typer.Option(None, "--markdown", "-m"),
+    force: bool = typer.Option(False, "--force", help="Export even if verification fails."),
+) -> None:
+    """Export a packet to another format."""
+    if markdown is None:
+        raise typer.BadParameter("Only --markdown is supported in v0.1.")
+    receipt = _load_receipt(receipt_path)
+    result = verify_receipt(receipt)
+    if not result.valid and not force:
+        typer.echo("Packet verification failed; use --force to export anyway.")
+        for error in result.errors:
+            typer.echo(f"- {error}")
+        raise typer.Exit(1)
+    export_markdown(receipt, markdown)
+    typer.echo(f"Created {markdown}")
+
+
+if __name__ == "__main__":
+    app()

proofpacket/events.py

@@ -0,0 +1,14 @@
+"""Event type constants."""
+
+EVENT_TYPES = {
+    "run_started",
+    "llm_call",
+    "tool_call",
+    "source_used",
+    "file_access",
+    "human_review",
+    "external_action",
+    "risk_flag",
+    "note",
+    "run_finished",
+}

proofpacket/exporters.py

@@ -0,0 +1,94 @@
+"""JSON and Markdown export helpers."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Dict, Iterable
+
+from proofpacket.hashing import verify_receipt
+
+
+def export_json(receipt: Dict[str, Any], path: str | Path) -> None:
+    Path(path).parent.mkdir(parents=True, exist_ok=True)
+    Path(path).write_text(json.dumps(receipt, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+
+
+def export_markdown(receipt: Dict[str, Any], path: str | Path) -> None:
+    Path(path).parent.mkdir(parents=True, exist_ok=True)
+    Path(path).write_text(receipt_to_markdown(receipt), encoding="utf-8")
+
+
+def _unique(values: Iterable[str | None]) -> list[str]:
+    seen: set[str] = set()
+    result: list[str] = []
+    for value in values:
+        if value and value not in seen:
+            seen.add(value)
+            result.append(value)
+    return result
+
+
+def receipt_to_markdown(receipt: Dict[str, Any]) -> str:
+    events = receipt.get("events", [])
+    tools = _unique(event.get("metadata", {}).get("tool") for event in events if event.get("event_type") == "tool_call")
+    sources = [
+        f"{event.get('bucket')}: {event.get('metadata', {}).get('title') or event.get('metadata', {}).get('uri') or 'Untitled source'}"
+        for event in events
+        if event.get("event_type") == "source_used"
+    ]
+    reviews = [
+        f"{event.get('metadata', {}).get('decision')} by {event.get('metadata', {}).get('reviewer')}"
+        for event in events
+        if event.get("event_type") == "human_review"
+    ]
+    verification = verify_receipt(receipt)
+
+    lines = [
+        "# ProofPacket Evidence Packet",
+        "",
+        "## Run Summary",
+        "",
+        f"- Packet ID: {receipt.get('receipt_id')}",
+        f"- Run ID: {receipt.get('run_id')}",
+        f"- Task: {receipt.get('task')}",
+        f"- Status: {receipt.get('status')}",
+        f"- Started: {receipt.get('started_at')}",
+        f"- Finished: {receipt.get('finished_at')}",
+        f"- Privacy Mode: {receipt.get('privacy_mode')}",
+        f"- Attested By: {', '.join(attestor.get('name', 'unknown') for attestor in receipt.get('attested_by', [])) or 'unknown'}",
+        f"- Packet Hash: {receipt.get('receipt_hash')}",
+        "",
+        "## Event Summary",
+        "",
+        "| Time | Type | Bucket | Summary |",
+        "|---|---|---|---|",
+    ]
+    for event in events:
+        lines.append(
+            f"| {event.get('timestamp')} | {event.get('event_type')} | {event.get('bucket')} | {event.get('summary')} |"
+        )
+
+    lines.extend(["", "## Tools Used", ""])
+    lines.extend([f"- {tool}" for tool in tools] or ["- None recorded"])
+    lines.extend(["", "## Sources Used", ""])
+    lines.extend([f"- {source}" for source in sources] or ["- None recorded"])
+    lines.extend(["", "## Human Reviews", ""])
+    lines.extend([f"- {review}" for review in reviews] or ["- None recorded"])
+    lines.extend(["", "## Risk Flags", ""])
+    if receipt.get("risk_flags"):
+        for flag in receipt["risk_flags"]:
+            lines.append(f"- {flag.get('severity', '').title()}: {flag.get('message')}")
+    else:
+        lines.append("- None recorded")
+    lines.extend(
+        [
+            "",
+            "## Verification",
+            "",
+            f"- Event hash chain: {'valid' if verification.event_hash_chain_valid else 'invalid'}",
+            f"- Packet hash: {'valid' if verification.receipt_hash_valid else 'invalid'}",
+            "",
+        ]
+    )
+    return "\n".join(lines)

proofpacket/hashing.py

@@ -0,0 +1,133 @@
+"""Deterministic hashing and receipt verification helpers."""
+
+from __future__ import annotations
+
+import copy
+import hashlib
+import json
+import math
+import unicodedata
+from dataclasses import dataclass, field
+from typing import Any, Dict, List
+
+from jsonschema import ValidationError, validate
+
+
+ZERO_HASH = "sha256:" + ("0" * 64)
+
+
+def _normalize_for_canonical_json(value: Any) -> Any:
+    if isinstance(value, str):
+        return unicodedata.normalize("NFC", value)
+    if isinstance(value, bool) or value is None or isinstance(value, int):
+        return value
+    if isinstance(value, float):
+        if not math.isfinite(value):
+            raise ValueError("canonical JSON does not support non-finite floats")
+        if value.is_integer():
+            return int(value)
+        return value
+    if isinstance(value, list):
+        return [_normalize_for_canonical_json(item) for item in value]
+    if isinstance(value, dict):
+        return {
+            unicodedata.normalize("NFC", str(key)): _normalize_for_canonical_json(item)
+            for key, item in value.items()
+        }
+    raise TypeError(f"unsupported canonical JSON value: {type(value).__name__}")
+
+
+def canonical_json(obj: Dict[str, Any]) -> str:
+    """Return ProofPacket canonical JSON for deterministic hashing.
+
+    v0.1 uses a documented JSON subset rather than full RFC 8785 JCS. See
+    docs/canonicalization.md before implementing cross-language verification.
+    """
+    normalized = _normalize_for_canonical_json(obj)
+    return json.dumps(normalized, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+
+
+def hash_text(text: str) -> str:
+    """Hash text with SHA-256 and return a prefixed digest."""
+    digest = hashlib.sha256(text.encode("utf-8")).hexdigest()
+    return f"sha256:{digest}"
+
+
+def hash_json(obj: Dict[str, Any]) -> str:
+    """Hash a JSON-like dict using canonical JSON."""
+    return hash_text(canonical_json(obj))
+
+
+def hash_event(event: Dict[str, Any]) -> str:
+    payload = copy.deepcopy(event)
+    payload.pop("event_hash", None)
+    return hash_json(payload)
+
+
+def hash_receipt(receipt: Dict[str, Any]) -> str:
+    payload = copy.deepcopy(receipt)
+    payload.pop("receipt_hash", None)
+    return hash_json(payload)
+
+
+@dataclass
+class VerificationResult:
+    """Result of verifying a ProofPacket hash chain."""
+
+    valid: bool
+    event_hash_chain_valid: bool
+    receipt_hash_valid: bool
+    schema_valid: bool | None = None
+    errors: List[str] = field(default_factory=list)
+
+
+def verify_receipt(receipt: Dict[str, Any]) -> VerificationResult:
+    """Verify event hashes, previous-event links, receipt hash, and schema if available."""
+    errors: List[str] = []
+    events = receipt.get("events", [])
+    previous_hash = ZERO_HASH
+    event_chain_valid = True
+
+    for index, event in enumerate(events):
+        expected_previous = previous_hash
+        actual_previous = event.get("previous_event_hash")
+        if actual_previous != expected_previous:
+            event_chain_valid = False
+            errors.append(
+                f"event {index} previous_event_hash mismatch: expected {expected_previous}, got {actual_previous}"
+            )
+
+        expected_event_hash = hash_event(event)
+        actual_event_hash = event.get("event_hash")
+        if actual_event_hash != expected_event_hash:
+            event_chain_valid = False
+            errors.append(
+                f"event {index} event_hash mismatch: expected {expected_event_hash}, got {actual_event_hash}"
+            )
+        previous_hash = actual_event_hash or expected_event_hash
+
+    expected_receipt_hash = hash_receipt(receipt)
+    receipt_hash_valid = receipt.get("receipt_hash") == expected_receipt_hash
+    if not receipt_hash_valid:
+        errors.append(
+            f"receipt_hash mismatch: expected {expected_receipt_hash}, got {receipt.get('receipt_hash')}"
+        )
+
+    schema_valid = None
+    try:
+        from proofpacket.schema import load_schema
+
+        validate(instance=receipt, schema=load_schema())
+        schema_valid = True
+    except ValidationError as exc:
+        schema_valid = False
+        errors.append(f"schema validation failed: {exc}")
+
+    valid = event_chain_valid and receipt_hash_valid and schema_valid is not False
+    return VerificationResult(
+        valid=valid,
+        event_hash_chain_valid=event_chain_valid,
+        receipt_hash_valid=receipt_hash_valid,
+        schema_valid=schema_valid,
+        errors=errors,
+    )