corrlog-core 0.1.0__py3-none-any.whl

corrlog_autogen/__init__.py

@@ -0,0 +1,112 @@
+"""corrlog-autogen — drop-in correction log for AutoGen agents.
+
+AutoGen has NO merged tool-call middleware as of this build (verified against the
+cloned source). The seams we need — `BaseTool.run_json()` / `Workbench.call_tool()` —
+are exactly what the still-open proposals target (#7405 GuardrailProvider, #7353 AAR
+receipts). So this adapter wraps `run_json` rather than relying on a shipped hook.
+
+Import-safe: if autogen is not installed, `is_available()` returns False and the
+wrapper class still imports.
+
+Usage (when autogen is installed):
+    from corrlog_autogen import GuardedTool
+    tool = GuardedTool(my_autogen_tool, sink, private_key, agent_id="agent-1")
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from corrlog_core import record, retract
+
+try:
+    from autogen_core.tools import BaseTool  # type: ignore
+    _AUTOGEN_AVAILABLE = True
+except Exception:  # pragma: no cover
+    _AUTOGEN_AVAILABLE = False
+
+
+def is_available() -> bool:
+    return _AUTOGEN_AVAILABLE
+
+
+class GuardedTool:
+    """Wraps an AutoGen tool, adding before/after correction-logging around `run_json`.
+
+    Structured to match the proposed GuardrailProvider signature from #7405, so it
+    upgrades cleanly when that lands upstream.
+    """
+
+    def __init__(self, tool, sink, private_key, agent_id: str, principal_id: str = "organization") -> None:
+        self._tool = tool
+        self.sink = sink
+        self.private_key = private_key
+        self.agent_id = agent_id
+        self.principal_id = principal_id
+
+    def __getattr__(self, name: str):
+        # Delegate everything else to the wrapped tool.
+        return getattr(self._tool, name)
+
+    @property
+    def name(self) -> str:
+        return getattr(self._tool, "name", "unknown_tool")
+
+    async def run_json(self, args, cancellation_token=None, call_id=None):
+        tool_name = self.name
+        rec = record(
+            agent_id=self.agent_id,
+            principal_id=self.principal_id,
+            action_type=f"autogen.tool.{tool_name}",
+            action_args=args if isinstance(args, dict) else {"args": args},
+            private_key=self.private_key,
+            metadata={"call_id": call_id} if call_id else None,
+        )
+        self.sink.append(rec)
+
+        try:
+            result = await self._tool.run_json(args, cancellation_token, call_id)
+        except Exception as e:  # noqa: BLE001
+            corr = retract(
+                prior_record=rec,
+                reason=f"tool raised: {e}",
+                trigger="check_failed",
+                agent_id=self.agent_id,
+                private_key=self.private_key,
+                principal_id=self.principal_id,
+                fix_type="replace",
+                fix_note=f"autogen tool {tool_name} raised",
+            )
+            self.sink.append(corr)
+            raise
+
+        # Result-level error detection (best-effort, framework-dependent shape).
+        if isinstance(result, dict) and result.get("error"):
+            corr = retract(
+                prior_record=rec,
+                reason=str(result["error"]),
+                trigger="check_failed",
+                agent_id=self.agent_id,
+                private_key=self.private_key,
+                principal_id=self.principal_id,
+                fix_type="replace",
+                fix_note=f"autogen tool {tool_name} errored",
+            )
+            self.sink.append(corr)
+
+        return result
+
+    def mark_wrong(self, prior_record: dict[str, Any], reason: str, fix_note: str | None = None) -> dict[str, Any]:
+        """Human-flag a prior record as wrong -> signed correction."""
+        corr = retract(
+            prior_record=prior_record,
+            reason=reason,
+            trigger="human_flagged",
+            agent_id=self.agent_id,
+            private_key=self.private_key,
+            principal_id=self.principal_id,
+            fix_type="replace",
+            fix_note=fix_note,
+        )
+        self.sink.append(corr)
+        return corr

corrlog_claude_code/__init__.py

@@ -0,0 +1,8 @@
+"""corrlog-claude-code — plugin surface. The actual hook logic is in cli.py."""
+
+from __future__ import annotations
+
+
+def is_available() -> bool:
+    """Claude Code hooks are external processes — always 'available' if python is."""
+    return True

corrlog_claude_code/cli.py

@@ -0,0 +1,147 @@
+"""corrlog-claude-code — CLI for Claude Code hooks.
+
+Invoked by hooks/hooks.json as an external process. Reads the hook's stdin JSON,
+emits a signed correction-log record.
+
+Modes:
+  - PreToolUse   : hash the tool input, mint an action id (emit to stderr-free stdout)
+  - PostToolUse  : hash the tool result, sign the action record
+  - human-flag   : `corrlog human-flag --receipt <id> --reason "..."` to flag wrong
+
+The key lives in $CORRLOG_KEY_PATH (a PEM/raw Ed25519 private key file).
+Records append to $CORRLOG_SINK (JSONL path) or ./corrections.jsonl.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from corrlog_core import generate_keypair, record, retract, JsonlSink
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric import ed25519
+
+
+def _load_or_create_key(path: str):
+    if path and os.path.exists(path):
+        with open(path, "rb") as f:
+            return serialization.load_pem_private_key(f.read(), password=None)
+    priv = ed25519.Ed25519PrivateKey.generate()
+    if path:
+        with open(path, "wb") as f:
+            f.write(priv.private_bytes(
+                serialization.Encoding.PEM,
+                serialization.PrivateFormat.PKCS8,
+                serialization.NoEncryption(),
+            ))
+    return priv
+
+
+def _sink_path() -> str:
+    return os.environ.get("CORRLOG_SINK", os.path.join(os.getcwd(), "corrections.jsonl"))
+
+
+def _key_path() -> str:
+    return os.environ.get("CORRLOG_KEY_PATH", os.path.join(os.getcwd(), "corrlog_key.pem"))
+
+
+def _agent_id() -> str:
+    return os.environ.get("CORRLOG_AGENT_ID", "claude-code-agent")
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = argv if argv is not None else sys.argv[1:]
+
+    # Subcommand: human-flag
+    if argv and argv[0] == "human-flag":
+        p = argparse.ArgumentParser(prog="corrlog human-flag")
+        p.add_argument("--receipt", required=True)
+        p.add_argument("--reason", required=True)
+        p.add_argument("--fix-note")
+        args = p.parse_args(argv[1:])
+        priv = _load_or_create_key(_key_path())
+        sink = JsonlSink(_sink_path())
+        # Find the prior record.
+        prior = sink.get(args.receipt)
+        if prior is None:
+            print(json.dumps({"ok": False, "error": f"receipt {args.receipt} not found"}), file=sys.stderr)
+            return 1
+        corr = retract(
+            prior_record=prior, reason=args.reason, trigger="human_flagged",
+            agent_id=_agent_id(), private_key=priv, fix_type="replace", fix_note=args.fix_note,
+        )
+        sink.append(corr)
+        print(json.dumps({"ok": True, "correctionId": corr["correctionId"]}))
+        return 0
+
+    # Hook mode: read stdin JSON (Claude Code hook contract).
+    try:
+        data = json.load(sys.stdin)
+    except Exception:
+        data = {}
+
+    hook = data.get("hook_event_name", "")
+    tool_name = data.get("tool_name", "")
+    tool_input = data.get("tool_input", {})
+
+    priv = _load_or_create_key(_key_path())
+    sink = JsonlSink(_sink_path())
+
+    if hook == "PreToolUse":
+        rec = record(
+            agent_id=_agent_id(), action_type=f"claude.tool.{tool_name}",
+            action_args=tool_input if isinstance(tool_input, dict) else {"input": tool_input},
+            private_key=priv,
+        )
+        sink.append(rec)
+        # Allow the call; stash the action id in a sidecar file for PostToolUse.
+        _sidecar = os.path.join(os.getcwd(), ".corrlog_inflight.json")
+        try:
+            inflight = json.load(open(_sidecar)) if os.path.exists(_sidecar) else {}
+            inflight[tool_name] = rec["correctionId"]
+            json.dump(inflight, open(_sidecar, "w"))
+        except Exception:
+            pass
+        print(json.dumps({"continue": True}))
+
+    elif hook == "PostToolUse":
+        tool_result = data.get("tool_result", "")
+        _sidecar = os.path.join(os.getcwd(), ".corrlog_inflight.json")
+        prior_id = None
+        try:
+            inflight = json.load(open(_sidecar)) if os.path.exists(_sidecar) else {}
+            prior_id = inflight.pop(tool_name, None)
+            json.dump(inflight, open(_sidecar, "w"))
+        except Exception:
+            pass
+        rec = record(
+            agent_id=_agent_id(), action_type=f"claude.tool.{tool_name}",
+            action_args=tool_input if isinstance(tool_input, dict) else {"input": tool_input},
+            action_result=tool_result, private_key=priv,
+        )
+        sink.append(rec)
+        # Detect error in result -> check_failed correction.
+        if isinstance(tool_result, str) and any(
+            m in tool_result.lower() for m in ("error", "failed", "exception", "denied")
+        ):
+            corr = retract(
+                prior_record=rec, reason="tool returned error", trigger="check_failed",
+                agent_id=_agent_id(), private_key=priv, fix_type="replace",
+                fix_note=f"claude tool {tool_name} errored",
+            )
+            sink.append(corr)
+        print(json.dumps({"continue": True}))
+
+    else:
+        # Unhandled hook event: no-op, allow.
+        print(json.dumps({"continue": True}))
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

corrlog_claude_code/hooks.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "*",
+        "command": "python3 -m corrlog_claude_code.cli"
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "*",
+        "command": "python3 -m corrlog_claude_code.cli"
+      }
+    ]
+  }
+}

corrlog_core/__init__.py

@@ -0,0 +1,385 @@
+"""corrlog-core — the Agent Correction Record (ACR) core.
+
+Framework-independent implementation of the ACR v1.0 spec (see SPEC.md):
+sign, verify, record, retract. Ed25519 over RFC 8785 (JCS) canonical JSON.
+
+The only runtime dependency is `cryptography` (for Ed25519).
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import uuid
+from datetime import datetime, timezone
+from typing import Any, Protocol
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives import serialization
+
+__version__ = "0.1.0"
+from cryptography.hazmat.primitives.asymmetric import ed25519
+
+CANONICALIZATION = "RFC8785"
+VALID_TRIGGERS = ("supersede", "check_failed", "human_flagged", "self_correction")
+VALID_FIX_TYPES = ("replace", "delete", "rollback", "noop", "other")
+
+
+# ---------------------------------------------------------------------------
+# Canonical JSON per RFC 8785 (JCS — JSON Canonicalization Scheme)
+# ---------------------------------------------------------------------------
+def canonical_json(obj: dict[str, Any]) -> bytes:
+    """Return RFC 8785 (JCS) canonical bytes.
+
+    RFC 8785 requires: recursive key sort by UTF-16 code unit order, no
+    insignificant whitespace, and specific string escaping — control
+    characters and non-ASCII MUST be escaped as ``\\uXXXX``/surrogate pairs so
+    every conforming implementation (Python, Rust, Go, TS) produces
+    byte-identical output. Python's ``json.dumps`` with ``ensure_ascii=True``
+    and ``separators=(",", ":")`` satisfies this for strings; numbers MUST be
+    serialized per RFC 8785 §3.2.3 (ES6 Number::toString) — this reference
+    avoids the float ambiguity by representing non-integer values as strings
+    (see `record`/`retract`), matching AAR's practice.
+    """
+    def _sorted(o: Any) -> Any:
+        if isinstance(o, dict):
+            # sort_keys sorts by Unicode code point, which matches UTF-16
+            # code unit order for the BMP (all keys here are ASCII-safe).
+            return {k: _sorted(v) for k, v in sorted(o.items())}
+        if isinstance(o, list):
+            return [_sorted(v) for v in o]
+        return o
+
+    return json.dumps(
+        _sorted(obj), separators=(",", ":"), ensure_ascii=True, sort_keys=True
+    ).encode("utf-8")
+
+
+# ---------------------------------------------------------------------------
+# Key helpers
+# ---------------------------------------------------------------------------
+def generate_keypair() -> tuple[ed25519.Ed25519PrivateKey, ed25519.Ed25519PublicKey]:
+    """Return (private_key, public_key) as cryptography Ed25519 objects."""
+    priv = ed25519.Ed25519PrivateKey.generate()
+    return priv, priv.public_key()
+
+
+def public_key_b64url(pub: ed25519.Ed25519PublicKey) -> str:
+    """Base64url (no padding) encoding of the raw Ed25519 public key bytes."""
+    raw = pub.public_bytes(
+        serialization.Encoding.Raw, serialization.PublicFormat.Raw
+    )
+    return base64.urlsafe_b64encode(raw).decode("ascii").rstrip("=")
+
+
+def load_private_key(seed: str) -> ed25519.Ed25519PrivateKey:
+    """Load an Ed25519 private key from a 32-byte seed string.
+
+    Accepts the seed as base64url (no padding) or hex. This is the loading
+    counterpart to ``generate_keypair`` — adapters use it to turn an operator's
+    secret (from an env var) into a signing key without inventing their own
+    serialization.
+    """
+    s = seed.strip()
+    if s.startswith(("sk_", "priv_", "ed25519:")):
+        # allow a small prefix for readability; strip it
+        s = s.split(":", 1)[-1] if ":" in s else s[2:] if s.startswith("sk_") else s[5:]
+    try:
+        raw = base64.urlsafe_b64decode(s + "=" * (-len(s) % 4))
+    except Exception:
+        raw = b""
+    if len(raw) != 32:
+        # fall back to hex
+        try:
+            raw = bytes.fromhex(s)
+        except Exception:
+            raw = b""
+    if len(raw) != 32:
+        raise ValueError(
+            "seed must decode to exactly 32 bytes (base64url or hex)"
+        )
+    return ed25519.Ed25519PrivateKey.from_private_bytes(raw)
+
+
+# ---------------------------------------------------------------------------
+# Record construction
+# ---------------------------------------------------------------------------
+def _hash_object(data: bytes) -> dict[str, str]:
+    return {"alg": "sha256", "digest": _b64url(hashlib.sha256(data).digest())}
+
+
+def _b64url(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).decode("ascii").rstrip("=")
+
+
+def record(
+    *,
+    agent_id: str,
+    agent_name: str | None = None,
+    principal_id: str = "unknown",
+    principal_type: str = "organization",
+    action_type: str,
+    action_target: str | None = None,
+    action_args: Any = None,
+    action_result: Any = None,
+    private_key: ed25519.Ed25519PrivateKey,
+    kid: str | None = None,
+    metadata: dict[str, Any] | None = None,
+    correction_id: str | None = None,
+    timestamp: str | None = None,
+) -> dict[str, Any]:
+    """Build a signed ACR-compatible *action* record (the receipt a correction can supersede).
+
+    This is the lightweight action record; corrections are built with `retract`.
+
+    ``correction_id`` and ``timestamp`` are OPTIONAL and exist for deterministic
+    test vectors (reproducible records, cross-implementation verification).
+    When omitted they default to a fresh UUID / current UTC time.
+    """
+    ts = timestamp if timestamp is not None else datetime.now(timezone.utc).isoformat()
+    public_key = private_key.public_key()
+    pk_b64 = public_key_b64url(public_key)
+    if kid is None:
+        kid = pk_b64
+
+    body: dict[str, Any] = {
+        "correctionId": correction_id if correction_id is not None else str(uuid.uuid4()),
+        "agent": {"id": agent_id, "publicKey": pk_b64},
+        "principal": {"id": principal_id, "type": principal_type},
+        "action": {"type": action_type},
+        "reason": "",
+        "trigger": "supersede",  # placeholder; corrected on retract
+        "fix": {"type": "noop"},
+        "timestamp": ts,
+        "metadata": metadata or {},
+    }
+    if agent_name:
+        body["agent"]["name"] = agent_name
+    if action_target:
+        body["action"]["target"] = action_target
+
+    # Store hashes of args/result (privacy-preserving) in metadata.
+    if action_args is not None:
+        body["metadata"]["inputHash"] = _hash_object(
+            canonical_json(action_args) if isinstance(action_args, dict) else str(action_args).encode()
+        )
+    if action_result is not None:
+        body["metadata"]["outputHash"] = _hash_object(
+            canonical_json(action_result) if isinstance(action_result, dict) else str(action_result).encode()
+        )
+
+    _sign(body, private_key, kid)
+    return body
+
+
+def retract(
+    *,
+    prior_record: dict[str, Any],
+    reason: str,
+    trigger: str,
+    agent_id: str,
+    private_key: ed25519.Ed25519PrivateKey,
+    principal_id: str = "unknown",
+    principal_type: str = "organization",
+    fix_type: str = "replace",
+    fix_note: str | None = None,
+    corrected_content: Any = None,
+    kid: str | None = None,
+    metadata: dict[str, Any] | None = None,
+    correction_id: str | None = None,
+    timestamp: str | None = None,
+) -> dict[str, Any]:
+    """Build a signed correction record that supersedes `prior_record`.
+
+    `prior_record` is the action record (or prior correction) being amended.
+    The supersedes pointer is a SHA-256 content hash of the prior record's
+    canonical bytes — not just an id — so the chain is verifiable offline.
+
+    ``correction_id`` and ``timestamp`` are OPTIONAL and exist for deterministic
+    test vectors (reproducible records, cross-implementation verification).
+    """
+    if trigger not in VALID_TRIGGERS:
+        raise ValueError(f"trigger must be one of {VALID_TRIGGERS}, got {trigger!r}")
+    if fix_type not in VALID_FIX_TYPES:
+        raise ValueError(f"fix.type must be one of {VALID_FIX_TYPES}, got {fix_type!r}")
+
+    ts = timestamp if timestamp is not None else datetime.now(timezone.utc).isoformat()
+    public_key = private_key.public_key()
+    pk_b64 = public_key_b64url(public_key)
+    if kid is None:
+        kid = pk_b64
+
+    prior_digest = _hash_object(canonical_json(prior_record))
+
+    body: dict[str, Any] = {
+        "correctionId": correction_id if correction_id is not None else str(uuid.uuid4()),
+        "agent": {"id": agent_id, "publicKey": pk_b64},
+        "principal": {"id": principal_id, "type": principal_type},
+        "supersedes": {
+            "receiptId": prior_record.get("correctionId") or prior_record.get("receiptId"),
+            "digest": prior_digest,
+        },
+        "action": {"type": prior_record.get("action", {}).get("type", "unknown")},
+        "reason": reason,
+        "trigger": trigger,
+        "fix": {"type": fix_type},
+        "timestamp": ts,
+        "metadata": metadata or {},
+    }
+    if fix_note:
+        body["fix"]["note"] = fix_note
+    if corrected_content is not None:
+        body["fix"]["contentHash"] = _hash_object(
+            canonical_json(corrected_content)
+            if isinstance(corrected_content, dict)
+            else str(corrected_content).encode()
+        )
+
+    _sign(body, private_key, kid)
+    return body
+
+
+def _sign(body: dict[str, Any], private_key: ed25519.Ed25519PrivateKey, kid: str) -> None:
+    body["signature"] = {
+        "alg": "Ed25519",
+        "kid": kid,
+        "publicKey": public_key_b64url(private_key.public_key()),
+        "canonicalization": CANONICALIZATION,
+        "sig": "",
+    }
+    # Canonicalize with sig removed (empty), then sign.
+    sig_bytes = private_key.sign(canonical_json(body))
+    body["signature"]["sig"] = _b64url(sig_bytes)
+
+
+# ---------------------------------------------------------------------------
+# Verification
+# ---------------------------------------------------------------------------
+def verify(record: dict[str, Any], public_key: ed25519.Ed25519PublicKey | None = None) -> bool:
+    """Verify an ACR record's Ed25519 signature.
+
+    If `public_key` is None, the key embedded in `record["signature"]["publicKey"]`
+    is used (self-authenticating). Pass a key explicitly to pin trust to a known key.
+    """
+    sig_meta = record.get("signature") or {}
+    if sig_meta.get("alg") != "Ed25519":
+        return False
+    if sig_meta.get("canonicalization") != CANONICALIZATION:
+        return False
+
+    sig_b64 = sig_meta.get("sig") or ""
+    if not sig_b64:
+        return False
+
+    try:
+        sig_bytes = base64.urlsafe_b64decode(sig_b64 + "=" * (-len(sig_b64) % 4))
+    except Exception:
+        return False
+
+    if public_key is None:
+        pk_b64 = sig_meta.get("publicKey") or record.get("agent", {}).get("publicKey")
+        if not pk_b64:
+            return False
+        try:
+            raw = base64.urlsafe_b64decode(pk_b64 + "=" * (-len(pk_b64) % 4))
+            public_key = ed25519.Ed25519PublicKey.from_public_bytes(raw)
+        except Exception:
+            return False
+
+    # Re-canonicalize with sig removed.
+    payload = {k: v for k, v in record.items() if k != "signature"}
+    payload["signature"] = {**sig_meta, "sig": ""}
+
+    try:
+        public_key.verify(sig_bytes, canonical_json(payload))
+        return True
+    except InvalidSignature:
+        return False
+    except Exception:
+        return False
+
+
+def verify_chain(records: list[dict[str, Any]], public_key: ed25519.Ed25519PublicKey | None = None) -> bool:
+    """Verify a chain of records: each signature valid, and each correction's
+    `supersedes.digest` matches the canonical bytes of the prior record."""
+    for i, rec in enumerate(records):
+        if not verify(rec, public_key):
+            return False
+        if i == 0:
+            continue
+        sup = rec.get("supersedes")
+        if not sup:
+            # A chain where a later record doesn't supersede is broken.
+            return False
+        expected_digest = sup.get("digest", {}).get("digest")
+        if not expected_digest:
+            return False
+        actual_digest = _b64url(hashlib.sha256(canonical_json(records[i - 1])).digest())
+        if actual_digest != expected_digest:
+            return False
+    return True
+
+
+def tamper_evident(record: dict[str, Any]) -> bool:
+    """True if any mutation of the signed body invalidates the signature."""
+    # A record is tamper-evident by construction; this checks the signature
+    # still holds for the current body (i.e. it has NOT been mutated).
+    return verify(record)
+
+
+# ---------------------------------------------------------------------------
+# Pluggable sink
+# ---------------------------------------------------------------------------
+class Sink(Protocol):
+    def append(self, record: dict[str, Any]) -> None: ...
+    def get(self, correction_id: str) -> dict[str, Any] | None: ...
+    def all(self) -> list[dict[str, Any]]: ...
+
+
+class MemorySink:
+    """In-memory append-only sink (for demos/tests)."""
+
+    def __init__(self) -> None:
+        self._records: list[dict[str, Any]] = []
+
+    def append(self, record: dict[str, Any]) -> None:
+        self._records.append(record)
+
+    def get(self, correction_id: str) -> dict[str, Any] | None:
+        for r in self._records:
+            if r.get("correctionId") == correction_id:
+                return r
+        return None
+
+    def all(self) -> list[dict[str, Any]]:
+        return list(self._records)
+
+
+class JsonlSink:
+    """Append-only JSONL file sink — durable, hash-chained by file order."""
+
+    def __init__(self, path: str) -> None:
+        self.path = path
+
+    def append(self, record: dict[str, Any]) -> None:
+        with open(self.path, "a", encoding="utf-8") as f:
+            f.write(json.dumps(record, separators=(",", ":"), ensure_ascii=False) + "\n")
+
+    def get(self, correction_id: str) -> dict[str, Any] | None:
+        for r in self.all():
+            if r.get("correctionId") == correction_id:
+                return r
+        return None
+
+    def all(self) -> list[dict[str, Any]]:
+        out: list[dict[str, Any]] = []
+        try:
+            with open(self.path, "r", encoding="utf-8") as f:
+                for line in f:
+                    line = line.strip()
+                    if line:
+                        out.append(json.loads(line))
+        except FileNotFoundError:
+            pass
+        return out