proofledger 0.2.0__tar.gz → 0.3.0__tar.gz

{proofledger-0.2.0 → proofledger-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: proofledger
-Version: 0.2.0
+Version: 0.3.0
 Summary: Framework-agnostic, tamper-evident audit layer for AI agents. Hash chains verify byte-for-byte against the ProofLedger TypeScript SDK and dashboard.
 Project-URL: Homepage, https://proofledger.dev
 Project-URL: Repository, https://github.com/jorama/proofledger

{proofledger-0.2.0 → proofledger-0.3.0}/proofledger/__init__.py

@@ -18,7 +18,7 @@ from __future__ import annotations
 
 from typing import Any, Callable, Dict, Optional, TypeVar
 
-from .client import RunHandle, ProofLedgerClient, iso_now
+from .client import RunHandle, ProofLedgerClient, PolicyBlockedError, iso_now
 from .hashing import (
     GENESIS_HASH,
     ChainVerificationResult,
@@ -49,6 +49,20 @@ __all__ = [
     "require_approval",
     "register_agent_identity",
     "send_agent_message",
+    # Phase 1 AI Trust Platform
+    "register_agent",
+    "identify_agent",
+    "log_decision",
+    "log_tool_call",
+    "log_api_call",
+    "log_workflow_step",
+    "log_trust_event",
+    "evaluate_policy",
+    "sign_event",
+    "verify_event",
+    "get_trust_score",
+    "flush",
+    "PolicyBlockedError",
     # Adapters
     "instrument",
     "wrap_openai",
@@ -106,6 +120,13 @@ def enable(
     local_dir: Optional[str] = None,
     silent: bool = False,
     disabled: bool = False,
+    agent_name: Optional[str] = None,
+    owner: Optional[str] = None,
+    framework: Optional[str] = None,
+    model: Optional[str] = None,
+    version: Optional[str] = None,
+    auto_capture: bool = True,
+    policy_mode: str = "monitor",
 ) -> ProofLedgerClient:
     """Initialize the global client and return it for advanced use."""
     global _global_client
@@ -118,6 +139,13 @@ def enable(
         local_dir=local_dir,
         silent=silent,
         disabled=disabled,
+        agent_name=agent_name,
+        owner=owner,
+        framework=framework,
+        model=model,
+        version=version,
+        auto_capture=auto_capture,
+        policy_mode=policy_mode,
     )
     return _global_client
 
@@ -185,13 +213,70 @@ def send_agent_message(**kwargs: Any) -> Dict[str, Any]:
     return _get_client().send_agent_message(**kwargs)
 
 
+# --- Phase 1: AI Trust Platform ----------------------------------------------
+
+
+def register_agent(**kwargs: Any) -> Dict[str, Any]:
+    """Register this agent's identity. See ProofLedgerClient.register_agent."""
+    return _get_client().register_agent(**kwargs)
+
+
+def identify_agent(agent_id: str, private_key: Optional[str] = None) -> None:
+    """Set the active agent identity (and optional signing key)."""
+    return _get_client().identify_agent(agent_id, private_key)
+
+
+def log_trust_event(**kwargs: Any) -> Dict[str, Any]:
+    """Log one event through the trust pipeline."""
+    return _get_client().log_trust_event(**kwargs)
+
+
+def log_decision(**kwargs: Any) -> Dict[str, Any]:
+    """Log an agent decision."""
+    return _get_client().log_decision(**kwargs)
+
+
+def log_tool_call(tool_name: str, **kwargs: Any) -> Dict[str, Any]:
+    """Log a tool/MCP call."""
+    return _get_client().log_tool_call(tool_name, **kwargs)
+
+
+def log_api_call(api_endpoint: str, **kwargs: Any) -> Dict[str, Any]:
+    """Log an outbound API call."""
+    return _get_client().log_api_call(api_endpoint, **kwargs)
+
+
+def log_workflow_step(
+    workflow_id: str, status: Optional[str] = None, **kwargs: Any
+) -> Dict[str, Any]:
+    """Log a workflow step (status="completed"/"failed" closes the workflow)."""
+    return _get_client().log_workflow_step(workflow_id, status, **kwargs)
+
+
+def evaluate_policy(**kwargs: Any) -> Dict[str, Any]:
+    """Dry-run the policy engine without logging or changing trust."""
+    return _get_client().evaluate_policy(**kwargs)
+
+
+def get_trust_score(agent_id: Optional[str] = None) -> Dict[str, Any]:
+    """Fetch the agent's live trust score and level."""
+    return _get_client().get_trust_score(agent_id)
+
+
+def flush() -> None:
+    """Await pending sends (no-op in the sync Python SDK; API parity)."""
+    return _get_client().flush()
+
+
 # Adapters (imported lazily-safe; they resolve the global client at call time).
 from .adapters import instrument, wrap_openai, create_langchain_handler  # noqa: E402
 
-# Signing (Phase 6) — needs the optional `cryptography` extra.
+# Signing — needs the optional `cryptography` extra.
 from .signing import (  # noqa: E402
     create_agent_identity,
     sign_message,
     verify_message,
+    sign_event,
+    verify_event,
     signing_available,
 )

{proofledger-0.2.0 → proofledger-0.3.0}/proofledger/client.py

@@ -22,7 +22,7 @@ from .hashing import (
 from .pricing import estimate_cost
 from .transport import HttpTransport, LocalTransport, Transport
 
-__all__ = ["ProofLedgerClient", "RunHandle", "iso_now"]
+__all__ = ["ProofLedgerClient", "RunHandle", "PolicyBlockedError", "iso_now"]
 
 T = TypeVar("T")
 
@@ -90,6 +90,13 @@ class ProofLedgerClient:
         local_dir: Optional[str] = None,
         silent: bool = False,
         disabled: bool = False,
+        agent_name: Optional[str] = None,
+        owner: Optional[str] = None,
+        framework: Optional[str] = None,
+        model: Optional[str] = None,
+        version: Optional[str] = None,
+        auto_capture: bool = True,
+        policy_mode: str = "monitor",
     ) -> None:
         use_local = local is True or not api_key
         self.config: Dict[str, Any] = {
@@ -99,8 +106,21 @@ class ProofLedgerClient:
             "base_url": base_url,
             "disabled": disabled is True,
             "silent": silent is True,
+            # Phase 1 trust platform defaults.
+            "agent_name": agent_name,
+            "owner": owner,
+            "framework": framework,
+            "model": model,
+            "version": version,
+            "auto_capture": auto_capture is not False,
+            "policy_mode": policy_mode if policy_mode in ("monitor", "enforce") else "monitor",
         }
 
+        #: Active agent identity for trust events. The private key lives in
+        #: memory only — never sent to the backend, never logged.
+        self._current_agent_id: Optional[str] = agent_name
+        self._current_private_key: Optional[str] = None
+
         self.transport: Transport = (
             LocalTransport(local_dir or ".proofledger")
             if use_local
@@ -551,6 +571,209 @@ class ProofLedgerClient:
             }
         )
 
+    # --- Phase 1: AI Trust Platform ------------------------------------------
+
+    def _require_agent_id(self, agent_id: Optional[str] = None) -> str:
+        resolved = agent_id or self._current_agent_id or self.config.get("agent_name")
+        if not resolved:
+            raise ValueError(
+                "ProofLedger: no agent_id. Pass one, call identify_agent(), "
+                "or set agent_name in enable()."
+            )
+        return resolved
+
+    def register_agent(self, **kwargs: Any) -> Dict[str, Any]:
+        """Register (or update) this agent's identity in the registry.
+
+        Uses ``enable()`` config as defaults. With ``generate_keys=True`` (the
+        default when no public key is supplied) the server returns the private
+        key ONCE; the client keeps it in memory for event signing.
+        """
+        agent_id = self._require_agent_id(kwargs.get("agent_id"))
+        payload = {
+            "projectId": self.config["project_id"],
+            "agentId": agent_id,
+            "name": kwargs.get("name") or self.config.get("agent_name") or agent_id,
+            "description": kwargs.get("description"),
+            "owner": kwargs.get("owner") or self.config.get("owner"),
+            "framework": kwargs.get("framework") or self.config.get("framework"),
+            "model": kwargs.get("model") or self.config.get("model"),
+            "version": kwargs.get("version") or self.config.get("version"),
+            "environment": kwargs.get("environment") or self.config["environment"],
+            "publicKey": kwargs.get("public_key"),
+            "generateKeys": kwargs.get(
+                "generate_keys", kwargs.get("public_key") is None
+            ),
+        }
+        result = self.transport.register_agent(payload)
+        self._current_agent_id = agent_id
+        if result.get("privateKey"):
+            self._current_private_key = result["privateKey"]
+        return result
+
+    def identify_agent(self, agent_id: str, private_key: Optional[str] = None) -> None:
+        """Set the active agent identity (and optional signing key)."""
+        self._current_agent_id = agent_id
+        if private_key:
+            self._current_private_key = private_key
+
+    def sign_event(self, event: Dict[str, Any], private_key: Optional[str] = None) -> str:
+        """Sign an event body (eventId, agentId, eventType, action, timestamp)."""
+        from .signing import sign_event as _sign_event
+
+        key = private_key or self._current_private_key
+        if not key:
+            raise ValueError(
+                "ProofLedger: no private key. register_agent() with generate_keys "
+                "or identify_agent(agent_id, private_key)."
+            )
+        return _sign_event(key, event)
+
+    def verify_event(
+        self, public_key: str, event: Dict[str, Any], signature: str
+    ) -> bool:
+        """Verify an event signature against a public key (offline check)."""
+        from .signing import verify_event as _verify_event
+
+        return _verify_event(public_key, event, signature)
+
+    def log_trust_event(self, **kwargs: Any) -> Dict[str, Any]:
+        """Log one event through the trust pipeline (policy → security → trust
+        → hash chain). Signs automatically when a private key is held. In
+        enforce mode raises :class:`PolicyBlockedError` on a block decision.
+        """
+        from .signing import signing_available
+
+        agent_id = self._require_agent_id(kwargs.get("agent_id"))
+        action = kwargs.get("action")
+        if not action:
+            raise ValueError("ProofLedger: action is required")
+        event_id = kwargs.get("event_id") or ids.new_id("evt")
+        timestamp = iso_now()
+        event_type = kwargs.get("event_type") or kwargs.get("event_category") or "custom"
+        signature = None
+        if (
+            not kwargs.get("unsigned")
+            and self._current_private_key
+            and signing_available()
+            and agent_id == (self._current_agent_id or agent_id)
+        ):
+            signature = self.sign_event(
+                {
+                    "eventId": event_id,
+                    "agentId": agent_id,
+                    "eventType": event_type,
+                    "action": action,
+                    "timestamp": timestamp,
+                }
+            )
+        if self.config["disabled"]:
+            return {
+                "event": {"eventId": event_id, "agentId": agent_id, "action": action},
+                "policy": {"decision": "allow", "matched": [], "reason": "SDK disabled"},
+                "trust": {"before": 100, "after": 100, "level": "trusted"},
+            }
+        payload = {
+            "projectId": self.config["project_id"],
+            "agentId": agent_id,
+            "eventId": event_id,
+            "eventType": event_type,
+            "eventCategory": kwargs.get("event_category"),
+            "action": action,
+            "inputSummary": kwargs.get("input_summary"),
+            "outputSummary": kwargs.get("output_summary"),
+            "toolName": kwargs.get("tool_name"),
+            "toolType": kwargs.get("tool_type"),
+            "mcpServer": kwargs.get("mcp_server"),
+            "apiEndpoint": kwargs.get("api_endpoint"),
+            "workflowId": kwargs.get("workflow_id"),
+            "workflowName": kwargs.get("workflow_name"),
+            "userId": kwargs.get("user_id"),
+            "sensitiveAction": kwargs.get("sensitive_action"),
+            "metadata": kwargs.get("metadata"),
+            "timestamp": timestamp,
+            "signature": signature,
+        }
+        result = self.transport.send_trust_event(payload)
+        policy = result.get("policy") or {}
+        if self.config["policy_mode"] == "enforce" and policy.get("decision") == "block":
+            raise PolicyBlockedError(policy)
+        return result
+
+    def log_decision(self, **kwargs: Any) -> Dict[str, Any]:
+        """Log an agent decision (reasoning step, plan, choice)."""
+        kwargs.update(event_type="decision", event_category="decision")
+        return self.log_trust_event(**kwargs)
+
+    def log_tool_call(self, tool_name: str, **kwargs: Any) -> Dict[str, Any]:
+        """Log a tool/MCP call (unknown tools auto-register as unapproved)."""
+        kwargs.setdefault("action", f"Tool call: {tool_name}")
+        kwargs.update(
+            tool_name=tool_name, event_type="tool_call", event_category="tool_call"
+        )
+        return self.log_trust_event(**kwargs)
+
+    def log_api_call(self, api_endpoint: str, **kwargs: Any) -> Dict[str, Any]:
+        """Log an outbound API call."""
+        kwargs.setdefault("action", f"API call: {api_endpoint}")
+        kwargs.update(
+            api_endpoint=api_endpoint, event_type="api_call", event_category="api_call"
+        )
+        return self.log_trust_event(**kwargs)
+
+    def log_workflow_step(
+        self, workflow_id: str, status: Optional[str] = None, **kwargs: Any
+    ) -> Dict[str, Any]:
+        """Log a workflow step; pass status="completed"/"failed" to close it."""
+        event_type = (
+            "workflow_completed"
+            if status == "completed"
+            else "workflow_failed"
+            if status == "failed"
+            else kwargs.pop("event_type", None) or "workflow_step"
+        )
+        kwargs.update(
+            workflow_id=workflow_id, event_type=event_type, event_category="workflow"
+        )
+        return self.log_trust_event(**kwargs)
+
+    def evaluate_policy(self, **kwargs: Any) -> Dict[str, Any]:
+        """Dry-run the policy engine WITHOUT logging or changing trust."""
+        if self.config["disabled"]:
+            return {"decision": "allow", "matched": [], "reason": "SDK disabled"}
+        return self.transport.evaluate_policy(
+            {
+                "projectId": self.config["project_id"],
+                "agentId": self._require_agent_id(kwargs.get("agent_id")),
+                "eventType": kwargs.get("event_type"),
+                "eventCategory": kwargs.get("event_category"),
+                "toolName": kwargs.get("tool_name"),
+                "mcpServer": kwargs.get("mcp_server"),
+                "apiEndpoint": kwargs.get("api_endpoint"),
+                "sensitiveAction": kwargs.get("sensitive_action"),
+            }
+        )
+
+    def get_trust_score(self, agent_id: Optional[str] = None) -> Dict[str, Any]:
+        """Fetch the agent's live trust score and level."""
+        return self.transport.get_trust_score(
+            self.config["project_id"], self._require_agent_id(agent_id)
+        )
+
+    def flush(self) -> None:
+        """No-op for API parity — the Python SDK sends synchronously."""
+        return None
+
+
+class PolicyBlockedError(RuntimeError):
+    """Raised by log_* methods in enforce mode when policy blocks the action."""
+
+    def __init__(self, evaluation: Dict[str, Any]) -> None:
+        super().__init__(
+            f"ProofLedger policy blocked this action: {evaluation.get('reason')}"
+        )
+        self.evaluation = evaluation
+
 
 def _now_ms() -> float:
     """Epoch milliseconds, matching JS ``Date.now()``."""

{proofledger-0.2.0 → proofledger-0.3.0}/proofledger/signing.py

@@ -21,7 +21,14 @@ try:  # optional dependency
 except Exception:  # pragma: no cover - exercised only without the extra
     _HAS_CRYPTO = False
 
-__all__ = ["create_agent_identity", "sign_message", "verify_message", "signing_available"]
+__all__ = [
+    "create_agent_identity",
+    "sign_message",
+    "verify_message",
+    "sign_event",
+    "verify_event",
+    "signing_available",
+]
 
 
 def signing_available() -> bool:
@@ -64,6 +71,46 @@ def sign_message(private_key_b64: str, envelope: Dict[str, Any]) -> str:
     return base64.b64encode(priv.sign(data)).decode("ascii")
 
 
+def _signable_event_body(event: Dict[str, Any]) -> str:
+    """Canonical body signed for a Phase 1 trust event.
+
+    Must stay in lockstep with the backend's ``signableEventBody`` and the TS
+    SDK's ``signEvent`` — the server verifies against exactly this JSON.
+    """
+    return canonicalize(
+        {
+            "eventId": event["eventId"],
+            "agentId": event["agentId"],
+            "eventType": event["eventType"],
+            "action": event["action"],
+            "timestamp": event["timestamp"],
+        }
+    )
+
+
+def sign_event(private_key_b64: str, event: Dict[str, Any]) -> str:
+    """Sign a trust-platform event body. Returns a base64 signature.
+
+    ``event`` must contain eventId, agentId, eventType, action, timestamp.
+    """
+    _require()
+    priv = serialization.load_der_private_key(base64.b64decode(private_key_b64), password=None)
+    return base64.b64encode(priv.sign(_signable_event_body(event).encode("utf-8"))).decode("ascii")
+
+
+def verify_event(public_key_b64: str, event: Dict[str, Any], signature_b64: str) -> bool:
+    """Verify a trust-platform event signature against an agent's public key."""
+    if not _HAS_CRYPTO:
+        return False
+    try:
+        pub = serialization.load_der_public_key(base64.b64decode(public_key_b64))
+        data = _signable_event_body(event).encode("utf-8")
+        pub.verify(base64.b64decode(signature_b64), data)  # type: ignore[union-attr]
+        return True
+    except Exception:
+        return False
+
+
 def verify_message(public_key_b64: str, envelope: Dict[str, Any], signature_b64: str) -> bool:
     """Verify a signature against an agent's public key."""
     if not _HAS_CRYPTO:

{proofledger-0.2.0 → proofledger-0.3.0}/proofledger/transport.py

@@ -64,6 +64,20 @@ class Transport(abc.ABC):
     @abc.abstractmethod
     def send_agent_message(self, payload: Dict[str, Any]) -> Dict[str, Any]: ...
 
+    # --- Phase 1 trust platform (non-abstract for backward compatibility) ----
+
+    def register_agent(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+        raise NotImplementedError
+
+    def send_trust_event(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+        raise NotImplementedError
+
+    def evaluate_policy(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+        raise NotImplementedError
+
+    def get_trust_score(self, project_id: str, agent_id: str) -> Dict[str, Any]:
+        raise NotImplementedError
+
 
 class HttpTransport(Transport):
     """HTTP transport using only ``urllib`` from the standard library."""
@@ -145,6 +159,28 @@ class HttpTransport(Transport):
         data = self._request("/api/proofledger/messages", "POST", _drop_none(payload))
         return (data or {}).get("message", {})
 
+    # --- Phase 1 trust platform ----------------------------------------------
+
+    def register_agent(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+        return self._request("/api/agents", "POST", _drop_none(payload)) or {}
+
+    def send_trust_event(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+        return self._request("/api/events", "POST", _drop_none(payload)) or {}
+
+    def evaluate_policy(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+        data = self._request("/api/policies/evaluate", "POST", _drop_none(payload))
+        return (data or {}).get("evaluation", {})
+
+    def get_trust_score(self, project_id: str, agent_id: str) -> Dict[str, Any]:
+        quoted_agent = urllib.parse.quote(agent_id, safe="")
+        quoted_project = urllib.parse.quote(project_id, safe="")
+        return (
+            self._request(
+                f"/api/agents/{quoted_agent}/trust?projectId={quoted_project}", "GET"
+            )
+            or {}
+        )
+
 
 class LocalTransport(Transport):
     """Local-first transport: in-memory store + best-effort JSONL log.
@@ -208,6 +244,98 @@ class LocalTransport(Transport):
         verified = bool(public_key) and verify_message(public_key, envelope, payload["signature"])
         return {"id": new_id("msg"), "verified": verified}
 
+    # --- Phase 1 trust platform (local approximations) ------------------------
+    # Local mode has no policy store or registry: everything is allowed, trust
+    # stays at 100, and signatures verify against locally-registered keys.
+
+    def register_agent(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+        if not hasattr(self, "_trust_agents"):
+            self._trust_agents: Dict[str, Dict[str, Any]] = {}
+        agent_id = payload["agentId"]
+        existing = self._trust_agents.get(agent_id)
+        public_key = payload.get("publicKey") or (existing or {}).get("publicKey")
+        private_key = None
+        if not public_key and payload.get("generateKeys"):
+            from .signing import create_agent_identity, signing_available
+
+            if signing_available():
+                pair = create_agent_identity()
+                public_key = pair["publicKey"]
+                private_key = pair["privateKey"]
+        agent = {
+            "agentId": agent_id,
+            "name": payload.get("name") or agent_id,
+            "owner": payload.get("owner"),
+            "framework": payload.get("framework"),
+            "model": payload.get("model"),
+            "version": payload.get("version"),
+            "environment": payload.get("environment") or "development",
+            "publicKey": public_key,
+            "status": "active",
+            "trustScore": 100,
+            "trustLevel": "trusted",
+        }
+        self._trust_agents[agent_id] = agent
+        if public_key:
+            self._identities[agent_id] = public_key
+        result: Dict[str, Any] = {"agent": agent, "created": existing is None}
+        if private_key:
+            result["privateKey"] = private_key
+        return result
+
+    def send_trust_event(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+        from .signing import verify_event
+
+        agent_id = payload["agentId"]
+        signature_valid = None
+        if payload.get("signature"):
+            public_key = self._identities.get(agent_id)
+            signature_valid = bool(public_key) and verify_event(
+                public_key,
+                {
+                    "eventId": payload.get("eventId"),
+                    "agentId": agent_id,
+                    "eventType": payload.get("eventType"),
+                    "action": payload.get("action"),
+                    "timestamp": payload.get("timestamp"),
+                },
+                payload["signature"],
+            )
+        return {
+            "event": {
+                "eventId": payload.get("eventId") or new_id("evt"),
+                "agentId": agent_id,
+                "eventType": payload.get("eventType"),
+                "eventCategory": payload.get("eventCategory") or "system",
+                "action": payload.get("action"),
+                "policyDecision": "allow",
+                "signatureValid": signature_valid,
+                "hash": "",
+                "previousHash": "",
+            },
+            "policy": {
+                "decision": "allow",
+                "matched": [],
+                "reason": "Local mode — policies are not evaluated",
+            },
+            "trust": {"before": 100, "after": 100, "level": "trusted"},
+        }
+
+    def evaluate_policy(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+        return {
+            "decision": "allow",
+            "matched": [],
+            "reason": "Local mode — policies are not evaluated",
+        }
+
+    def get_trust_score(self, project_id: str, agent_id: str) -> Dict[str, Any]:
+        return {
+            "agentId": agent_id,
+            "trustScore": 100,
+            "trustLevel": "trusted",
+            "status": "active",
+        }
+
     def _persist(self, event: Dict[str, Any]) -> None:
         try:
             if not self._dir_ready:

{proofledger-0.2.0 → proofledger-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "proofledger"
-version = "0.2.0"
+version = "0.3.0"
 description = "Framework-agnostic, tamper-evident audit layer for AI agents. Hash chains verify byte-for-byte against the ProofLedger TypeScript SDK and dashboard."
 readme = "README.md"
 requires-python = ">=3.9"