toolgovern-cli 0.1.1__py3-none-any.whl

toolgovern/trace/__init__.py

@@ -0,0 +1,33 @@
+from .canonical_json import canonical_json
+from .trace_reader import (
+    ChainVerificationIssue,
+    ChainVerificationResult,
+    TraceQuery,
+    VerifyChainOptions,
+    filter_trace,
+    parse_since,
+    read_trace,
+    verify_chain,
+)
+from .trace_writer import (
+    TraceWriter,
+    TraceWriterOptions,
+    compute_entry_content_hash,
+    compute_entry_signature,
+)
+
+__all__ = [
+    "canonical_json",
+    "TraceWriter",
+    "TraceWriterOptions",
+    "compute_entry_content_hash",
+    "compute_entry_signature",
+    "read_trace",
+    "filter_trace",
+    "parse_since",
+    "verify_chain",
+    "TraceQuery",
+    "ChainVerificationResult",
+    "ChainVerificationIssue",
+    "VerifyChainOptions",
+]

toolgovern/trace/canonical_json.py

@@ -0,0 +1,27 @@
+"""Deterministic JSON serialization: object keys are sorted recursively so the same logical
+content always hashes to the same bytes, regardless of the insertion order the caller used.
+
+Ported from ``packages/toolgovern/src/trace/canonical-json.ts``. This is what makes the trace's
+sha256 content hash reproducible and verifiable later.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+
+def _sort_keys_deep(value: Any) -> Any:
+    if isinstance(value, list):
+        return [_sort_keys_deep(v) for v in value]
+    if isinstance(value, dict):
+        return {key: _sort_keys_deep(value[key]) for key in sorted(value.keys())}
+    return value
+
+
+def canonical_json(value: Any) -> str:
+    """Serializes ``value`` to JSON with all object keys sorted recursively (array order is
+    preserved). ``separators`` matches JavaScript's ``JSON.stringify`` compact-by-default
+    output (no extra whitespace), so the byte sequence signed by the TypeScript and Python
+    implementations is identical for the same logical content."""
+    return json.dumps(_sort_keys_deep(value), separators=(",", ":"), ensure_ascii=False)

toolgovern/trace/trace_reader.py

@@ -0,0 +1,206 @@
+"""Reads a JSON Lines trace file for local inspection, filtering, and chain verification.
+
+Ported from ``packages/toolgovern/src/trace/trace-reader.ts``. Powers both
+``toolgovern-cli audit`` and any programmatic post-session review.
+"""
+
+from __future__ import annotations
+
+import hmac
+import json
+import re
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta, timezone
+from typing import Dict, List, Optional, Sequence
+
+from ..types import Decision, ScopeDeclaration, TraceEntry
+from .trace_writer import SecretKeyLike, compute_entry_signature
+
+
+def _signatures_match(actual: str, expected: str) -> bool:
+    """Constant-time comparison of two signature strings. ``hmac.compare_digest`` requires
+    equal-length inputs to stay constant-time; a length mismatch is checked first and
+    short-circuits to False -- this leaks nothing an attacker doesn't already know, since both
+    the scheme prefix and the hex-encoded hash length are fixed and public (``sha256:`` + 64
+    hex chars, ``hmac-sha256:`` + 64 hex chars), not a function of the secret being compared."""
+    actual_bytes = actual.encode("utf-8")
+    expected_bytes = expected.encode("utf-8")
+    if len(actual_bytes) != len(expected_bytes):
+        return False
+    return hmac.compare_digest(actual_bytes, expected_bytes)
+
+
+@dataclass(frozen=True)
+class TraceQuery:
+    since: Optional[str] = None
+    decision: Optional[Decision] = None
+    agent_id: Optional[str] = None
+    rule_id: Optional[str] = None
+    """Matches entries where this rule ID appears anywhere in rule_fired."""
+
+
+@dataclass(frozen=True)
+class ChainVerificationIssue:
+    trace_id: str
+    reason: str
+
+
+@dataclass(frozen=True)
+class ChainVerificationResult:
+    valid: bool
+    issues: Sequence[ChainVerificationIssue] = field(default_factory=tuple)
+
+
+@dataclass(frozen=True)
+class VerifyChainOptions:
+    """``secret_key`` is required to verify entries signed with ``hmac-sha256:``. Entries
+    signed with the legacy unkeyed ``sha256:`` scheme verify without it."""
+
+    secret_key: Optional[SecretKeyLike] = None
+
+
+def _entry_from_dict(raw: dict) -> TraceEntry:
+    scope_raw = raw.get("declared_scope", {})
+    scope = ScopeDeclaration(
+        network=scope_raw.get("network", False),
+        filesystem=tuple(scope_raw.get("filesystem", ())),
+        credentials=tuple(scope_raw.get("credentials", ())),
+    )
+    return TraceEntry(
+        trace_id=raw["trace_id"],
+        timestamp=raw["timestamp"],
+        session_id=raw["session_id"],
+        agent_id=raw["agent_id"],
+        tool=raw["tool"],
+        arguments_hash=raw["arguments_hash"],
+        decision=raw["decision"],
+        rule_fired=tuple(raw.get("rule_fired", ())),
+        declared_scope=scope,
+        signature=raw["signature"],
+        prior_trace_id=raw.get("prior_trace_id"),
+        agent_id_source=raw.get("agent_id_source"),
+        approved_by=raw.get("approved_by"),
+    )
+
+
+def read_trace(file_path: str) -> List[TraceEntry]:
+    """Reads and parses every line of a JSON Lines trace file. Blank lines are skipped."""
+    with open(file_path, "r", encoding="utf-8") as f:
+        raw = f.read()
+    entries: List[TraceEntry] = []
+    for index, line in enumerate(raw.split("\n")):
+        trimmed = line.strip()
+        if not trimmed:
+            continue
+        try:
+            parsed = json.loads(trimmed)
+        except json.JSONDecodeError as cause:
+            raise ValueError(
+                f"Malformed trace line {index + 1} in {file_path}: not valid JSON"
+            ) from cause
+        entries.append(_entry_from_dict(parsed))
+    return entries
+
+
+_SINCE_PATTERN = re.compile(r"^(\d+)(m|h|d)$")
+
+
+def parse_since(since: str, now: Optional[datetime] = None) -> datetime:
+    """Parses a ``since`` window string into an absolute cutoff datetime."""
+    now = now or datetime.now(timezone.utc)
+    match = _SINCE_PATTERN.match(since)
+    if not match:
+        try:
+            as_date = datetime.fromisoformat(since.replace("Z", "+00:00"))
+        except ValueError as cause:
+            raise ValueError(
+                f'Invalid --since value "{since}". Use "<n>m", "<n>h", "<n>d", or an ISO 8601 timestamp.'
+            ) from cause
+        return as_date
+    amount = int(match.group(1))
+    unit = match.group(2)
+    delta = {"m": timedelta(minutes=amount), "h": timedelta(hours=amount), "d": timedelta(days=amount)}[unit]
+    return now - delta
+
+
+def filter_trace(entries: Sequence[TraceEntry], query: TraceQuery) -> List[TraceEntry]:
+    """Filters trace entries by time window, decision, agent identity, and/or fired rule ID."""
+    cutoff = parse_since(query.since) if query.since else None
+    result = []
+    for entry in entries:
+        if cutoff is not None:
+            entry_time = datetime.fromisoformat(entry.timestamp.replace("Z", "+00:00"))
+            if entry_time < cutoff:
+                continue
+        if query.decision and entry.decision != query.decision:
+            continue
+        if query.agent_id and entry.agent_id != query.agent_id:
+            continue
+        if query.rule_id and query.rule_id not in entry.rule_fired:
+            continue
+        result.append(entry)
+    return result
+
+
+def verify_chain(
+    entries: Sequence[TraceEntry], options: Optional[VerifyChainOptions] = None
+) -> ChainVerificationResult:
+    """Recomputes each entry's signature and confirms it matches ``signature``, and confirms
+    ``prior_trace_id`` correctly links to the previous entry in the same session. Returns every
+    issue found rather than stopping at the first one, so a reviewer can see the full extent of
+    a broken or tampered trace file.
+
+    An entry signed ``hmac-sha256:`` cannot be verified without the matching ``secret_key`` --
+    that is reported as an issue (not silently skipped, and not silently treated as valid),
+    because a trace a reviewer cannot actually verify is not a trace they should trust as-is.
+    """
+    options = options or VerifyChainOptions()
+    issues: List[ChainVerificationIssue] = []
+    last_seen_by_session: Dict[str, Optional[str]] = {}
+
+    for entry in entries:
+        scheme = entry.signature.split(":", 1)[0]
+        if scheme == "hmac-sha256" and options.secret_key is None:
+            issues.append(
+                ChainVerificationIssue(
+                    trace_id=entry.trace_id,
+                    reason="Entry is signed with hmac-sha256 but no secret_key was supplied to verify it.",
+                )
+            )
+        elif scheme in ("hmac-sha256", "sha256"):
+            # Only pass the key through for entries actually signed with it. A sha256: entry
+            # must always be recomputed unkeyed, even if the caller supplied a secret_key
+            # (e.g. verifying a trace file that turns out to predate keyed signing, or a
+            # mixed-mode file) -- otherwise every legitimate unkeyed entry would spuriously
+            # fail to verify against the wrong scheme.
+            expected = compute_entry_signature(
+                entry, options.secret_key if scheme == "hmac-sha256" else None
+            )
+            if not _signatures_match(entry.signature, expected):
+                issues.append(
+                    ChainVerificationIssue(
+                        trace_id=entry.trace_id, reason="Signature does not match entry content."
+                    )
+                )
+        else:
+            issues.append(
+                ChainVerificationIssue(
+                    trace_id=entry.trace_id, reason=f'Unrecognized signature scheme "{scheme}".'
+                )
+            )
+
+        expected_prior = last_seen_by_session.get(entry.session_id)
+        if entry.prior_trace_id != expected_prior:
+            issues.append(
+                ChainVerificationIssue(
+                    trace_id=entry.trace_id,
+                    reason=(
+                        f'prior_trace_id "{entry.prior_trace_id or "null"}" does not match the '
+                        f'expected previous entry "{expected_prior or "null"}" for session '
+                        f'"{entry.session_id}".'
+                    ),
+                )
+            )
+        last_seen_by_session[entry.session_id] = entry.trace_id
+
+    return ChainVerificationResult(valid=len(issues) == 0, issues=issues)

toolgovern/trace/trace_writer.py

@@ -0,0 +1,247 @@
+"""Signed, append-only JSON Lines trace writer.
+
+Ported from ``packages/toolgovern/src/trace/trace-writer.ts``.
+
+Every gate decision -- allow, deny, or require-approval -- gets one line. ``prior_trace_id``
+chains each entry to the one before it in the same session, so a reader can walk the chain and
+detect a missing, reordered, or tampered entry.
+
+By default, "signed" means a ``sha256:`` content hash, not a keyed signature -- a deliberate
+v0.1 default that needs no key management: it proves an entry has not changed since it was
+written, but it does not stop someone with write access to the trace file from editing an entry
+and recomputing a signature that still passes, since the hash itself requires no secret to
+reproduce. Pass ``secret_key`` in ``TraceWriter`` to sign with ``hmac-sha256:`` instead, which
+closes that gap for anyone who does not also hold the key. See ``docs/security-model.md``.
+
+toolgovern does not generate, store, or rotate the key -- the caller is responsible for its
+lifecycle (e.g. a locally generated file with restrictive permissions, or a secret manager).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import os
+import threading
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any, Dict, Optional, Sequence, Union
+
+from ..types import AgentIdSource, Decision, ScopeDeclaration, TraceEntry, TraceEntryInput
+from .canonical_json import canonical_json
+
+# A raw bytes-like secret key, matching Node's BinaryLike (str/bytes) for this port's purposes.
+SecretKeyLike = Union[bytes, str]
+
+
+def _sha256_hex(content: str) -> str:
+    return hashlib.sha256(content.encode("utf-8")).hexdigest()
+
+
+def _hmac_sha256_hex(key: SecretKeyLike, content: str) -> str:
+    key_bytes = key.encode("utf-8") if isinstance(key, str) else key
+    return hmac.new(key_bytes, content.encode("utf-8"), hashlib.sha256).hexdigest()
+
+
+def _scope_to_content(scope: ScopeDeclaration) -> Dict[str, Any]:
+    return {
+        "network": scope.network if isinstance(scope.network, bool) else list(scope.network),
+        "filesystem": list(scope.filesystem),
+        "credentials": list(scope.credentials),
+    }
+
+
+def _entry_content(
+    *,
+    trace_id: Optional[str],
+    timestamp: str,
+    session_id: str,
+    agent_id: str,
+    tool: str,
+    arguments_hash: str,
+    decision: Decision,
+    rule_fired: Sequence[str],
+    declared_scope: ScopeDeclaration,
+    agent_id_source: Optional[AgentIdSource],
+    prior_trace_id: Optional[str],
+    approved_by: Optional[str],
+) -> str:
+    """Builds the canonical-JSON content that gets hashed/signed. When ``trace_id`` is
+    ``None``, the key is omitted entirely from the object (matching the TS ``withoutIds``
+    object, which has no ``trace_id`` field at all before one has been derived) rather than
+    included with an empty-string placeholder -- an empty string is still a value that would
+    change the hash output versus a genuinely absent key.
+    """
+    content: Dict[str, Any] = {}
+    if trace_id is not None:
+        content["trace_id"] = trace_id
+    content.update(
+        {
+            "timestamp": timestamp,
+            "session_id": session_id,
+            "agent_id": agent_id,
+            "tool": tool,
+            "arguments_hash": arguments_hash,
+            "decision": decision,
+            "rule_fired": list(rule_fired),
+            "declared_scope": _scope_to_content(declared_scope),
+            "agent_id_source": agent_id_source,
+            "prior_trace_id": prior_trace_id,
+            "approved_by": approved_by,
+        }
+    )
+    return canonical_json(content)
+
+
+def compute_entry_content_hash(entry: TraceEntry) -> str:
+    """Computes the content hash a TraceEntry should have, given everything except
+    ``signature``. This is the unkeyed form -- kept for backward compatibility and as the
+    fallback ``sha256:`` scheme ``compute_entry_signature()`` uses when no secret key is
+    configured."""
+    return _sha256_hex(
+        _entry_content(
+            trace_id=entry.trace_id,
+            timestamp=entry.timestamp,
+            session_id=entry.session_id,
+            agent_id=entry.agent_id,
+            tool=entry.tool,
+            arguments_hash=entry.arguments_hash,
+            decision=entry.decision,
+            rule_fired=entry.rule_fired,
+            declared_scope=entry.declared_scope,
+            agent_id_source=entry.agent_id_source,
+            prior_trace_id=entry.prior_trace_id,
+            approved_by=entry.approved_by,
+        )
+    )
+
+
+def compute_entry_signature(entry: TraceEntry, secret_key: Optional[SecretKeyLike] = None) -> str:
+    """Computes what ``signature`` should be for ``entry`` (everything except ``signature``).
+
+    With no ``secret_key``, this is ``sha256:<hex>`` of the entry's canonicalized content --
+    proves the entry has not changed since it was written, but the hash is reproducible by
+    anyone (no secret required), so it does not stop an attacker who has write access to the
+    trace file from editing an entry and recomputing a signature that still verifies.
+
+    With a ``secret_key``, this is ``hmac-sha256:<hex>`` -- only someone holding the same key
+    can produce a signature that verifies. This is what makes the trace tamper-evident against
+    an attacker who can write to the trace file but does not also hold the key. See
+    ``docs/security-model.md`` for the residual limitation (an attacker who reads both the
+    trace file and the key file can still forge a valid trace -- v0.1 has no external anchor or
+    key-management service).
+    """
+    content = _entry_content(
+        trace_id=entry.trace_id,
+        timestamp=entry.timestamp,
+        session_id=entry.session_id,
+        agent_id=entry.agent_id,
+        tool=entry.tool,
+        arguments_hash=entry.arguments_hash,
+        decision=entry.decision,
+        rule_fired=entry.rule_fired,
+        declared_scope=entry.declared_scope,
+        agent_id_source=entry.agent_id_source,
+        prior_trace_id=entry.prior_trace_id,
+        approved_by=entry.approved_by,
+    )
+    if secret_key is not None:
+        return f"hmac-sha256:{_hmac_sha256_hex(secret_key, content)}"
+    return f"sha256:{_sha256_hex(content)}"
+
+
+@dataclass(frozen=True)
+class TraceWriterOptions:
+    """Options for ``TraceWriter``.
+
+    ``secret_key``: when provided, every entry is signed with ``hmac-sha256:<hex>`` using this
+    key instead of the unkeyed ``sha256:<hex>`` content hash. toolgovern does not generate,
+    store, or rotate this key -- the caller is responsible for its lifecycle. Pass the same key
+    to ``verify_chain()``.
+    """
+
+    secret_key: Optional[SecretKeyLike] = None
+
+
+class TraceWriter:
+    """Appends signed, append-only JSON Lines trace entries to a file.
+
+    Writes are serialized with a lock so concurrent calls within one process never interleave
+    lines or race on the last-trace-id-per-session bookkeeping, which would silently break the
+    chain (the Python port's equivalent of the TS implementation's promise write-queue).
+    """
+
+    def __init__(self, file_path: str, options: Optional[TraceWriterOptions] = None) -> None:
+        self._file_path = file_path
+        self._options = options or TraceWriterOptions()
+        self._last_trace_id_by_session: Dict[str, Optional[str]] = {}
+        self._lock = threading.Lock()
+
+    def append(self, entry_input: TraceEntryInput) -> TraceEntry:
+        """Appends one gate decision to the trace file and returns the entry that was written."""
+        with self._lock:
+            prior_trace_id = self._last_trace_id_by_session.get(entry_input.session_id)
+            now = datetime.now(timezone.utc)
+            timestamp = now.strftime("%Y-%m-%dT%H:%M:%S.") + f"{now.microsecond // 1000:03d}Z"
+            arguments_hash = f"sha256:{_sha256_hex(canonical_json(dict(entry_input.args)))}"
+            rule_fired = list(entry_input.rule_fired)
+
+            # trace_id is derived from the entry's own (unkeyed) content hash of everything
+            # else -- it is an identifier, not a security boundary, so it stays
+            # reproducible/public even when the signature itself is keyed.
+            id_seed_content = _entry_content(
+                trace_id=None,
+                timestamp=timestamp,
+                session_id=entry_input.session_id,
+                agent_id=entry_input.agent_id,
+                tool=entry_input.tool,
+                arguments_hash=arguments_hash,
+                decision=entry_input.decision,
+                rule_fired=rule_fired,
+                declared_scope=entry_input.declared_scope,
+                agent_id_source=entry_input.agent_id_source,
+                prior_trace_id=prior_trace_id,
+                approved_by=entry_input.approved_by,
+            )
+            id_seed_hash = _sha256_hex(id_seed_content)
+            trace_id = f"tg_{timestamp[:10]}_{id_seed_hash[:6]}"
+
+            unsigned_entry = TraceEntry(
+                trace_id=trace_id,
+                timestamp=timestamp,
+                session_id=entry_input.session_id,
+                agent_id=entry_input.agent_id,
+                tool=entry_input.tool,
+                arguments_hash=arguments_hash,
+                decision=entry_input.decision,
+                rule_fired=rule_fired,
+                declared_scope=entry_input.declared_scope,
+                agent_id_source=entry_input.agent_id_source,
+                prior_trace_id=prior_trace_id,
+                approved_by=entry_input.approved_by,
+                signature="",
+            )
+            signature = compute_entry_signature(unsigned_entry, self._options.secret_key)
+            entry = TraceEntry(
+                trace_id=trace_id,
+                timestamp=timestamp,
+                session_id=entry_input.session_id,
+                agent_id=entry_input.agent_id,
+                tool=entry_input.tool,
+                arguments_hash=arguments_hash,
+                decision=entry_input.decision,
+                rule_fired=rule_fired,
+                declared_scope=entry_input.declared_scope,
+                agent_id_source=entry_input.agent_id_source,
+                prior_trace_id=prior_trace_id,
+                approved_by=entry_input.approved_by,
+                signature=signature,
+            )
+
+            os.makedirs(os.path.dirname(self._file_path) or ".", exist_ok=True)
+            with open(self._file_path, "a", encoding="utf-8") as f:
+                f.write(json.dumps(entry.to_dict(), ensure_ascii=False) + "\n")
+
+            self._last_trace_id_by_session[entry_input.session_id] = trace_id
+            return entry