truthlocks-maip 1.0.0__tar.gz

truthlocks_maip-1.0.0/.gitignore

@@ -0,0 +1,11 @@
+bin/
+*.exe
+*.dll
+*.so
+*.dylib
+node_modules/
+dist/
+__pycache__/
+*.egg-info/
+.env
+coverage.out

truthlocks_maip-1.0.0/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: truthlocks-maip
+Version: 1.0.0
+Summary: Python SDK for the MAIP (Machine Agent Identity Protocol)
+Project-URL: Homepage, https://github.com/truthlocks/maip
+Project-URL: Repository, https://github.com/truthlocks/maip
+Project-URL: Documentation, https://github.com/truthlocks/maip/tree/main/sdk/python
+Author-email: "Truthlocks Inc." <engineering@truthlocks.com>
+License-Expression: Apache-2.0
+Keywords: agent-identity,ai-agents,delegation,maip,trust
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.25.0
+Description-Content-Type: text/markdown
+
+# truthlocks-maip
+
+Python SDK for the **MAIP (Machine Agent Identity Protocol)**.
+
+## Installation
+
+```bash
+pip install truthlocks-maip
+```
+
+## Quick Start
+
+```python
+from truthlocks_maip import (
+    MaipClient,
+    CreateAgentRequest,
+    CreateSessionRequest,
+    OfferDelegationRequest,
+    CheckGuardrailsRequest,
+    Scope,
+)
+
+client = MaipClient(api_key="your-api-key")
+# For self-hosted: MaipClient(api_key="...", base_url="https://maip.your-company.com")
+
+# Register an agent
+agent = client.register_agent(CreateAgentRequest(
+    name="my-agent",
+    scope=Scope(actions=["read", "write"], resources=["documents/*"]),
+    public_key="base64-encoded-public-key",
+))
+
+# Create a session
+session = client.create_session(CreateSessionRequest(
+    agent_id=agent["id"],
+    ttl_seconds=3600,
+))
+
+# Get trust score
+trust = client.get_trust_score(agent["id"])
+print(f"Trust level: {trust['level']}, score: {trust['score']}")
+
+# Delegate trust
+delegation = client.offer_delegation(OfferDelegationRequest(
+    from_agent_id=agent["id"],
+    to_agent_id="other-agent-id",
+    scope=Scope(actions=["read"], resources=["documents/*"]),
+    ttl_seconds=1800,
+))
+
+# Check guardrails
+result = client.check_guardrails(CheckGuardrailsRequest(
+    agent_id=agent["id"],
+    action="write",
+    resource_id="documents/report.pdf",
+))
+
+if result["allowed"]:
+    pass  # Proceed with the action
+```
+
+## Offline Bundle Verification
+
+Verify receipt bundles without network access:
+
+```python
+from truthlocks_maip import verify_bundle
+
+result = verify_bundle(bundle)
+if result.valid:
+    print(f"Verified {result.receipt_count} receipts")
+else:
+    print("Bundle verification failed")
+```
+
+## API Reference
+
+### `MaipClient`
+
+| Method | Description |
+|---|---|
+| `register_agent(request)` | Register a new agent identity |
+| `list_agents(status?, offset?, limit?)` | List agents with optional filters |
+| `get_agent(agent_id)` | Get an agent by ID |
+| `suspend_agent(agent_id)` | Suspend an active agent |
+| `revoke_agent(agent_id)` | Permanently revoke an agent |
+| `create_session(request)` | Create an authenticated session |
+| `terminate_session(session_id)` | Terminate a session |
+| `get_trust_score(agent_id)` | Get the current trust score |
+| `compute_trust_score(request)` | Compute a fresh trust score |
+| `offer_delegation(request)` | Offer trust delegation |
+| `accept_delegation(delegation_id)` | Accept a delegation |
+| `execute_orchestration(request)` | Execute multi-agent orchestration |
+| `check_guardrails(request)` | Check guardrails before an action |
+
+### Error Types
+
+| Error | HTTP Status | Description |
+|---|---|---|
+| `MaipError` | any | Base error class |
+| `UnauthorizedError` | 401 | Invalid or missing API key |
+| `NotFoundError` | 404 | Resource not found |
+| `LimitExceededError` | 429 | Rate limit or quota exceeded |
+| `VerificationError` | n/a | Bundle/receipt verification failed |
+
+## License
+
+Apache-2.0

truthlocks_maip-1.0.0/README.md

@@ -0,0 +1,108 @@
+# truthlocks-maip
+
+Python SDK for the **MAIP (Machine Agent Identity Protocol)**.
+
+## Installation
+
+```bash
+pip install truthlocks-maip
+```
+
+## Quick Start
+
+```python
+from truthlocks_maip import (
+    MaipClient,
+    CreateAgentRequest,
+    CreateSessionRequest,
+    OfferDelegationRequest,
+    CheckGuardrailsRequest,
+    Scope,
+)
+
+client = MaipClient(api_key="your-api-key")
+# For self-hosted: MaipClient(api_key="...", base_url="https://maip.your-company.com")
+
+# Register an agent
+agent = client.register_agent(CreateAgentRequest(
+    name="my-agent",
+    scope=Scope(actions=["read", "write"], resources=["documents/*"]),
+    public_key="base64-encoded-public-key",
+))
+
+# Create a session
+session = client.create_session(CreateSessionRequest(
+    agent_id=agent["id"],
+    ttl_seconds=3600,
+))
+
+# Get trust score
+trust = client.get_trust_score(agent["id"])
+print(f"Trust level: {trust['level']}, score: {trust['score']}")
+
+# Delegate trust
+delegation = client.offer_delegation(OfferDelegationRequest(
+    from_agent_id=agent["id"],
+    to_agent_id="other-agent-id",
+    scope=Scope(actions=["read"], resources=["documents/*"]),
+    ttl_seconds=1800,
+))
+
+# Check guardrails
+result = client.check_guardrails(CheckGuardrailsRequest(
+    agent_id=agent["id"],
+    action="write",
+    resource_id="documents/report.pdf",
+))
+
+if result["allowed"]:
+    pass  # Proceed with the action
+```
+
+## Offline Bundle Verification
+
+Verify receipt bundles without network access:
+
+```python
+from truthlocks_maip import verify_bundle
+
+result = verify_bundle(bundle)
+if result.valid:
+    print(f"Verified {result.receipt_count} receipts")
+else:
+    print("Bundle verification failed")
+```
+
+## API Reference
+
+### `MaipClient`
+
+| Method | Description |
+|---|---|
+| `register_agent(request)` | Register a new agent identity |
+| `list_agents(status?, offset?, limit?)` | List agents with optional filters |
+| `get_agent(agent_id)` | Get an agent by ID |
+| `suspend_agent(agent_id)` | Suspend an active agent |
+| `revoke_agent(agent_id)` | Permanently revoke an agent |
+| `create_session(request)` | Create an authenticated session |
+| `terminate_session(session_id)` | Terminate a session |
+| `get_trust_score(agent_id)` | Get the current trust score |
+| `compute_trust_score(request)` | Compute a fresh trust score |
+| `offer_delegation(request)` | Offer trust delegation |
+| `accept_delegation(delegation_id)` | Accept a delegation |
+| `execute_orchestration(request)` | Execute multi-agent orchestration |
+| `check_guardrails(request)` | Check guardrails before an action |
+
+### Error Types
+
+| Error | HTTP Status | Description |
+|---|---|---|
+| `MaipError` | any | Base error class |
+| `UnauthorizedError` | 401 | Invalid or missing API key |
+| `NotFoundError` | 404 | Resource not found |
+| `LimitExceededError` | 429 | Rate limit or quota exceeded |
+| `VerificationError` | n/a | Bundle/receipt verification failed |
+
+## License
+
+Apache-2.0

truthlocks_maip-1.0.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "truthlocks-maip"
+version = "1.0.0"
+description = "Python SDK for the MAIP (Machine Agent Identity Protocol)"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.9"
+authors = [
+    { name = "Truthlocks Inc.", email = "engineering@truthlocks.com" },
+]
+keywords = ["maip", "agent-identity", "trust", "delegation", "ai-agents"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.25.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/truthlocks/maip"
+Repository = "https://github.com/truthlocks/maip"
+Documentation = "https://github.com/truthlocks/maip/tree/main/sdk/python"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/truthlocks_maip"]

truthlocks_maip-1.0.0/src/truthlocks_maip/__init__.py

@@ -0,0 +1,75 @@
+# Copyright 2026 Truthlocks Inc.
+# Licensed under the Apache License, Version 2.0
+
+"""Python SDK for the MAIP (Machine Agent Identity Protocol)."""
+
+from truthlocks_maip.client import MaipClient
+from truthlocks_maip.errors import (
+    LimitExceededError,
+    MaipError,
+    NotFoundError,
+    UnauthorizedError,
+    VerificationError,
+)
+from truthlocks_maip.types import (
+    Agent,
+    AgentStatus,
+    Bundle,
+    CheckGuardrailsRequest,
+    ComputeTrustScoreRequest,
+    CreateAgentRequest,
+    CreateSessionRequest,
+    Delegation,
+    DelegationStatus,
+    ExecuteOrchestrationRequest,
+    GuardrailResult,
+    GuardrailViolation,
+    ListResponse,
+    OfferDelegationRequest,
+    Orchestration,
+    OrchestrationStatus,
+    Receipt,
+    Scope,
+    Session,
+    SessionStatus,
+    TrustFactor,
+    TrustLevel,
+    TrustScore,
+)
+from truthlocks_maip.verify import verify_bundle, verify_receipt_hash
+
+__all__ = [
+    "MaipClient",
+    "MaipError",
+    "LimitExceededError",
+    "UnauthorizedError",
+    "NotFoundError",
+    "VerificationError",
+    "Agent",
+    "AgentStatus",
+    "Bundle",
+    "CheckGuardrailsRequest",
+    "ComputeTrustScoreRequest",
+    "CreateAgentRequest",
+    "CreateSessionRequest",
+    "Delegation",
+    "DelegationStatus",
+    "ExecuteOrchestrationRequest",
+    "GuardrailResult",
+    "GuardrailViolation",
+    "ListResponse",
+    "OfferDelegationRequest",
+    "Orchestration",
+    "OrchestrationStatus",
+    "Receipt",
+    "Scope",
+    "Session",
+    "SessionStatus",
+    "TrustFactor",
+    "TrustLevel",
+    "TrustScore",
+    "verify_bundle",
+    "verify_receipt_hash",
+]
+
+__version__ = "0.1.0"

truthlocks_maip-1.0.0/src/truthlocks_maip/client.py

@@ -0,0 +1,269 @@
+# Copyright 2026 Truthlocks Inc.
+# Licensed under the Apache License, Version 2.0
+
+"""MAIP SDK client for interacting with the Machine Agent Identity Protocol API."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict
+from typing import Any, Optional
+from urllib.parse import quote
+
+import httpx
+
+from truthlocks_maip.errors import (
+    LimitExceededError,
+    MaipError,
+    NotFoundError,
+    UnauthorizedError,
+)
+from truthlocks_maip.types import (
+    Agent,
+    AgentStatus,
+    CheckGuardrailsRequest,
+    ComputeTrustScoreRequest,
+    CreateAgentRequest,
+    CreateSessionRequest,
+    Delegation,
+    ExecuteOrchestrationRequest,
+    GuardrailResult,
+    ListResponse,
+    OfferDelegationRequest,
+    Orchestration,
+    Session,
+    TrustScore,
+)
+
+DEFAULT_BASE_URL = "https://api.truthlocks.com"
+DEFAULT_TIMEOUT = 30.0
+
+
+class MaipClient:
+    """MAIP SDK client.
+
+    Supports both the hosted Truthlocks API and self-hosted deployments
+    by configuring the ``base_url`` parameter.
+
+    Example::
+
+        from truthlocks_maip import MaipClient
+
+        client = MaipClient(api_key="your-api-key")
+
+        agent = client.register_agent(CreateAgentRequest(
+            name="my-agent",
+            scope=Scope(actions=["read"], resources=["*"]),
+            public_key="base64-encoded-public-key",
+        ))
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        if not api_key:
+            raise MaipError("api_key is required")
+
+        self._base_url = base_url.rstrip("/")
+        self._client = httpx.Client(
+            base_url=self._base_url,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+                "User-Agent": "truthlocks-maip-python/0.1.0",
+            },
+            timeout=timeout,
+        )
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self._client.close()
+
+    def __enter__(self) -> MaipClient:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    # -------------------------------------------------------------------------
+    # Agent Management
+    # -------------------------------------------------------------------------
+
+    def register_agent(self, request: CreateAgentRequest) -> dict[str, Any]:
+        """Register a new agent identity."""
+        return self._post("/v1/agents", self._to_api_dict(request))
+
+    def list_agents(
+        self,
+        status: Optional[AgentStatus] = None,
+        offset: Optional[int] = None,
+        limit: Optional[int] = None,
+    ) -> dict[str, Any]:
+        """List agents with optional filters."""
+        params: dict[str, Any] = {}
+        if status is not None:
+            params["status"] = status.value
+        if offset is not None:
+            params["offset"] = offset
+        if limit is not None:
+            params["limit"] = limit
+        return self._get("/v1/agents", params=params)
+
+    def get_agent(self, agent_id: str) -> dict[str, Any]:
+        """Retrieve a single agent by ID."""
+        return self._get(f"/v1/agents/{quote(agent_id, safe='')}")
+
+    def suspend_agent(self, agent_id: str) -> dict[str, Any]:
+        """Suspend an active agent."""
+        return self._post(
+            f"/v1/agents/{quote(agent_id, safe='')}/suspend", {}
+        )
+
+    def revoke_agent(self, agent_id: str) -> dict[str, Any]:
+        """Permanently revoke an agent identity."""
+        return self._post(
+            f"/v1/agents/{quote(agent_id, safe='')}/revoke", {}
+        )
+
+    # -------------------------------------------------------------------------
+    # Session Management
+    # -------------------------------------------------------------------------
+
+    def create_session(self, request: CreateSessionRequest) -> dict[str, Any]:
+        """Create a new authenticated session for an agent."""
+        return self._post("/v1/sessions", self._to_api_dict(request))
+
+    def terminate_session(self, session_id: str) -> dict[str, Any]:
+        """Terminate an active session."""
+        return self._post(
+            f"/v1/sessions/{quote(session_id, safe='')}/terminate", {}
+        )
+
+    # -------------------------------------------------------------------------
+    # Trust
+    # -------------------------------------------------------------------------
+
+    def get_trust_score(self, agent_id: str) -> dict[str, Any]:
+        """Get the current trust score for an agent."""
+        return self._get(
+            f"/v1/agents/{quote(agent_id, safe='')}/trust-score"
+        )
+
+    def compute_trust_score(
+        self, request: ComputeTrustScoreRequest
+    ) -> dict[str, Any]:
+        """Compute a fresh trust score for an agent."""
+        agent_id = request.agent_id
+        return self._post(
+            f"/v1/agents/{quote(agent_id, safe='')}/trust-score/compute",
+            self._to_api_dict(request),
+        )
+
+    # -------------------------------------------------------------------------
+    # Delegation
+    # -------------------------------------------------------------------------
+
+    def offer_delegation(
+        self, request: OfferDelegationRequest
+    ) -> dict[str, Any]:
+        """Offer a trust delegation from one agent to another."""
+        return self._post("/v1/delegations", self._to_api_dict(request))
+
+    def accept_delegation(self, delegation_id: str) -> dict[str, Any]:
+        """Accept an offered delegation."""
+        return self._post(
+            f"/v1/delegations/{quote(delegation_id, safe='')}/accept", {}
+        )
+
+    # -------------------------------------------------------------------------
+    # Orchestration
+    # -------------------------------------------------------------------------
+
+    def execute_orchestration(
+        self, request: ExecuteOrchestrationRequest
+    ) -> dict[str, Any]:
+        """Execute a multi-agent orchestration."""
+        return self._post("/v1/orchestrations", self._to_api_dict(request))
+
+    # -------------------------------------------------------------------------
+    # Guardrails
+    # -------------------------------------------------------------------------
+
+    def check_guardrails(
+        self, request: CheckGuardrailsRequest
+    ) -> dict[str, Any]:
+        """Check guardrails before performing an action."""
+        return self._post("/v1/guardrails/check", self._to_api_dict(request))
+
+    # -------------------------------------------------------------------------
+    # Internal helpers
+    # -------------------------------------------------------------------------
+
+    @staticmethod
+    def _to_api_dict(obj: Any) -> dict[str, Any]:
+        """Convert a dataclass to a dict with camelCase keys for the API."""
+        raw = asdict(obj)
+        return MaipClient._snake_to_camel_dict(raw)
+
+    @staticmethod
+    def _snake_to_camel(name: str) -> str:
+        parts = name.split("_")
+        return parts[0] + "".join(p.capitalize() for p in parts[1:])
+
+    @staticmethod
+    def _snake_to_camel_dict(d: dict[str, Any]) -> dict[str, Any]:
+        result: dict[str, Any] = {}
+        for key, value in d.items():
+            camel_key = MaipClient._snake_to_camel(key)
+            if isinstance(value, dict):
+                result[camel_key] = MaipClient._snake_to_camel_dict(value)
+            elif value is not None:
+                result[camel_key] = value
+        return result
+
+    def _get(
+        self, path: str, params: Optional[dict[str, Any]] = None
+    ) -> dict[str, Any]:
+        try:
+            response = self._client.get(path, params=params)
+            self._raise_for_status(response)
+            return response.json()  # type: ignore[no-any-return]
+        except httpx.HTTPError as exc:
+            raise MaipError(f"Request failed: {exc}") from exc
+
+    def _post(self, path: str, body: dict[str, Any]) -> dict[str, Any]:
+        try:
+            response = self._client.post(path, json=body)
+            self._raise_for_status(response)
+            return response.json()  # type: ignore[no-any-return]
+        except httpx.HTTPError as exc:
+            raise MaipError(f"Request failed: {exc}") from exc
+
+    @staticmethod
+    def _raise_for_status(response: httpx.Response) -> None:
+        if response.is_success:
+            return
+
+        try:
+            error_body = response.json()
+            message = error_body.get("message", f"HTTP {response.status_code}")
+        except Exception:
+            message = f"HTTP {response.status_code}"
+
+        status = response.status_code
+        if status == 401:
+            raise UnauthorizedError(message)
+        elif status == 404:
+            raise NotFoundError("Resource", message)
+        elif status == 429:
+            retry_after = response.headers.get("Retry-After")
+            raise LimitExceededError(
+                message,
+                retry_after_seconds=int(retry_after) if retry_after else None,
+            )
+        else:
+            raise MaipError(message, status_code=status)

truthlocks_maip-1.0.0/src/truthlocks_maip/errors.py

@@ -0,0 +1,64 @@
+# Copyright 2026 Truthlocks Inc.
+# Licensed under the Apache License, Version 2.0
+
+"""Error types for the MAIP SDK."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+class MaipError(Exception):
+    """Base error class for all MAIP SDK errors."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: Optional[int] = None,
+        code: Optional[str] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.code = code
+
+
+class LimitExceededError(MaipError):
+    """Raised when the caller exceeds a rate limit or quota."""
+
+    def __init__(
+        self,
+        message: str = "Rate limit exceeded",
+        retry_after_seconds: Optional[int] = None,
+    ) -> None:
+        super().__init__(message, status_code=429, code="LIMIT_EXCEEDED")
+        self.retry_after_seconds = retry_after_seconds
+
+
+class UnauthorizedError(MaipError):
+    """Raised when the API key is missing, invalid, or lacks permission."""
+
+    def __init__(
+        self, message: str = "Unauthorized: invalid or missing API key"
+    ) -> None:
+        super().__init__(message, status_code=401, code="UNAUTHORIZED")
+
+
+class NotFoundError(MaipError):
+    """Raised when a requested resource is not found."""
+
+    def __init__(self, resource: str, identifier: str) -> None:
+        super().__init__(
+            f"{resource} not found: {identifier}",
+            status_code=404,
+            code="NOT_FOUND",
+        )
+        self.resource = resource
+        self.identifier = identifier
+
+
+class VerificationError(MaipError):
+    """Raised when bundle or receipt verification fails."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message, code="VERIFICATION_FAILED")

truthlocks_maip-1.0.0/src/truthlocks_maip/types.py

@@ -0,0 +1,230 @@
+# Copyright 2026 Truthlocks Inc.
+# Licensed under the Apache License, Version 2.0
+
+"""Data types for the MAIP SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Generic, Optional, TypeVar
+
+T = TypeVar("T")
+
+
+class AgentStatus(str, Enum):
+    ACTIVE = "active"
+    SUSPENDED = "suspended"
+    REVOKED = "revoked"
+
+
+class SessionStatus(str, Enum):
+    ACTIVE = "active"
+    TERMINATED = "terminated"
+    EXPIRED = "expired"
+
+
+class TrustLevel(str, Enum):
+    CRITICAL = "critical"
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+    VERIFIED = "verified"
+
+
+class DelegationStatus(str, Enum):
+    OFFERED = "offered"
+    ACCEPTED = "accepted"
+    REJECTED = "rejected"
+    REVOKED = "revoked"
+    EXPIRED = "expired"
+
+
+class OrchestrationStatus(str, Enum):
+    PENDING = "pending"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+class ViolationSeverity(str, Enum):
+    INFO = "info"
+    WARNING = "warning"
+    ERROR = "error"
+    CRITICAL = "critical"
+
+
+@dataclass(frozen=True)
+class Scope:
+    """Permissions and boundaries for an agent."""
+    actions: list[str]
+    resources: list[str]
+    constraints: dict[str, str] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class Agent:
+    """A registered machine agent identity."""
+    id: str
+    name: str
+    status: AgentStatus
+    scope: Scope
+    public_key: str
+    metadata: dict[str, str]
+    created_at: str
+    updated_at: str
+
+
+@dataclass(frozen=True)
+class Session:
+    """An authenticated agent session."""
+    id: str
+    agent_id: str
+    status: SessionStatus
+    scope: Scope
+    expires_at: str
+    created_at: str
+
+
+@dataclass(frozen=True)
+class TrustFactor:
+    """A single factor contributing to a trust score."""
+    name: str
+    weight: float
+    value: float
+    description: str
+
+
+@dataclass(frozen=True)
+class TrustScore:
+    """Computed trust level for an agent."""
+    agent_id: str
+    score: float
+    level: TrustLevel
+    factors: list[TrustFactor]
+    computed_at: str
+
+
+@dataclass(frozen=True)
+class Delegation:
+    """Trust delegation from one agent to another."""
+    id: str
+    from_agent_id: str
+    to_agent_id: str
+    scope: Scope
+    status: DelegationStatus
+    expires_at: str
+    created_at: str
+
+
+@dataclass(frozen=True)
+class Orchestration:
+    """A multi-agent orchestration session."""
+    id: str
+    coordinator_agent_id: str
+    participant_agent_ids: list[str]
+    status: OrchestrationStatus
+    scope: Scope
+    created_at: str
+    result: Optional[dict[str, Any]] = None
+    completed_at: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class Receipt:
+    """Cryptographic proof of an action taken by an agent."""
+    id: str
+    agent_id: str
+    session_id: str
+    action: str
+    resource_id: str
+    timestamp: str
+    signature: str
+    metadata: dict[str, str]
+
+
+@dataclass(frozen=True)
+class Bundle:
+    """Collection of receipts that can be verified offline."""
+    id: str
+    receipts: list[Receipt]
+    root_hash: str
+    signature: str
+    created_at: str
+
+
+@dataclass(frozen=True)
+class GuardrailViolation:
+    """A guardrail rule violation."""
+    rule: str
+    severity: ViolationSeverity
+    message: str
+
+
+@dataclass(frozen=True)
+class GuardrailResult:
+    """Outcome of a guardrails check."""
+    allowed: bool
+    violations: list[GuardrailViolation]
+    checked_at: str
+
+
+@dataclass(frozen=True)
+class ListResponse(Generic[T]):
+    """Paginated list response."""
+    items: list[T]
+    total: int
+    offset: int
+    limit: int
+
+
+@dataclass(frozen=True)
+class CreateAgentRequest:
+    """Options for creating an agent."""
+    name: str
+    scope: Scope
+    public_key: str
+    metadata: dict[str, str] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class CreateSessionRequest:
+    """Options for creating a session."""
+    agent_id: str
+    scope: Optional[Scope] = None
+    ttl_seconds: Optional[int] = None
+
+
+@dataclass(frozen=True)
+class ComputeTrustScoreRequest:
+    """Options for computing a trust score."""
+    agent_id: str
+    factors: Optional[list[dict[str, Any]]] = None
+
+
+@dataclass(frozen=True)
+class OfferDelegationRequest:
+    """Options for offering a delegation."""
+    from_agent_id: str
+    to_agent_id: str
+    scope: Scope
+    ttl_seconds: Optional[int] = None
+
+
+@dataclass(frozen=True)
+class ExecuteOrchestrationRequest:
+    """Options for executing an orchestration."""
+    coordinator_agent_id: str
+    participant_agent_ids: list[str]
+    scope: Scope
+    parameters: Optional[dict[str, Any]] = None
+
+
+@dataclass(frozen=True)
+class CheckGuardrailsRequest:
+    """Options for checking guardrails."""
+    agent_id: str
+    action: str
+    resource_id: str
+    context: Optional[dict[str, Any]] = None

truthlocks_maip-1.0.0/src/truthlocks_maip/verify.py

@@ -0,0 +1,126 @@
+# Copyright 2026 Truthlocks Inc.
+# Licensed under the Apache License, Version 2.0
+
+"""Offline bundle and receipt verification.
+
+All functions in this module are pure and make no network calls.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+
+from truthlocks_maip.errors import VerificationError
+from truthlocks_maip.types import Bundle, Receipt
+
+
+def _sha256_hex(data: str) -> str:
+    """Compute SHA-256 hex digest of a string."""
+    return hashlib.sha256(data.encode("utf-8")).hexdigest()
+
+
+def _hash_receipt(receipt: Receipt) -> str:
+    """Compute the canonical hash of a receipt for Merkle tree inclusion."""
+    canonical = json.dumps(
+        {
+            "action": receipt.action,
+            "agentId": receipt.agent_id,
+            "id": receipt.id,
+            "metadata": receipt.metadata,
+            "resourceId": receipt.resource_id,
+            "sessionId": receipt.session_id,
+            "signature": receipt.signature,
+            "timestamp": receipt.timestamp,
+        },
+        sort_keys=False,
+        separators=(",", ":"),
+    )
+    return _sha256_hex(canonical)
+
+
+def _compute_merkle_root(leaf_hashes: list[str]) -> str:
+    """Compute the Merkle root from an ordered list of leaf hashes."""
+    if not leaf_hashes:
+        return _sha256_hex("")
+    if len(leaf_hashes) == 1:
+        return leaf_hashes[0]
+
+    level = list(leaf_hashes)
+    while len(level) > 1:
+        next_level: list[str] = []
+        for i in range(0, len(level), 2):
+            left = level[i]
+            right = level[i + 1] if i + 1 < len(level) else left
+            next_level.append(_sha256_hex(left + right))
+        level = next_level
+    return level[0]
+
+
+@dataclass(frozen=True)
+class VerifyBundleResult:
+    """Result of a bundle verification."""
+    valid: bool
+    computed_root_hash: str
+    declared_root_hash: str
+    receipt_count: int
+    receipt_hashes: list[str]
+
+
+def verify_bundle(bundle: Bundle) -> VerifyBundleResult:
+    """Verify a receipt bundle offline.
+
+    Checks that the Merkle root hash matches the receipts in the bundle.
+    Does NOT verify cryptographic signatures against agent public keys
+    (that requires network access to retrieve keys).
+
+    Pure function: no network calls are made.
+
+    Args:
+        bundle: The bundle to verify.
+
+    Returns:
+        The verification result.
+
+    Raises:
+        VerificationError: If the bundle structure is invalid.
+    """
+    if not bundle.receipts or not isinstance(bundle.receipts, list):
+        raise VerificationError("Bundle has no receipts list")
+    if not bundle.root_hash:
+        raise VerificationError("Bundle has no root_hash")
+
+    receipt_hashes: list[str] = []
+    for receipt in bundle.receipts:
+        if not receipt.id or not receipt.agent_id or not receipt.timestamp:
+            raise VerificationError(
+                f"Receipt is missing required fields: {receipt}"
+            )
+        receipt_hashes.append(_hash_receipt(receipt))
+
+    computed_root_hash = _compute_merkle_root(receipt_hashes)
+
+    return VerifyBundleResult(
+        valid=computed_root_hash == bundle.root_hash,
+        computed_root_hash=computed_root_hash,
+        declared_root_hash=bundle.root_hash,
+        receipt_count=len(bundle.receipts),
+        receipt_hashes=receipt_hashes,
+    )
+
+
+def verify_receipt_hash(receipt: Receipt, expected_hash: str) -> bool:
+    """Verify a single receipt hash against an expected value.
+
+    Useful for spot-checking individual receipts from a bundle.
+
+    Args:
+        receipt: The receipt to hash.
+        expected_hash: The expected SHA-256 hex hash.
+
+    Returns:
+        True if the computed hash matches the expected hash.
+    """
+    computed = _hash_receipt(receipt)
+    return computed == expected_hash