lockstock-integrations 1.1.0__py3-none-any.whl → 1.1.1__py3-none-any.whl

lockstock_core/__init__.py

@@ -0,0 +1,10 @@
+"""
+LockStock Core Client
+---------------------
+Shared client for all SDK integrations.
+"""
+
+from .client import LockStockClient
+from .types import VerifyResult, AuditEntry, AgentCard
+
+__all__ = ["LockStockClient", "VerifyResult", "AuditEntry", "AgentCard"]

lockstock_core/client.py

@@ -0,0 +1,281 @@
+"""
+LockStock Core Client
+---------------------
+HTTP client for LockStock API interactions.
+"""
+
+import hashlib
+import hmac
+import time
+from typing import Optional, Dict, Any, List
+import httpx
+
+from .types import VerifyResult, VerifyStatus, AuditEntry, AgentCard, map_tool_to_capability, Matrix, get_generator, normalize_task_for_signature
+
+
+class LockStockClient:
+    """
+    Client for interacting with the LockStock API.
+
+    Provides capability verification, audit logging, and identity management.
+    """
+
+    DEFAULT_ENDPOINT = "https://lockstock-api-i9kp.onrender.com"
+
+    def __init__(
+        self,
+        agent_id: str,
+        secret: Optional[str] = None,
+        api_key: Optional[str] = None,
+        endpoint: str = DEFAULT_ENDPOINT,
+        timeout: float = 30.0
+    ):
+        """
+        Initialize LockStock client.
+
+        Args:
+            agent_id: The agent's unique identifier
+            secret: The agent's HMAC secret (for signing requests)
+            api_key: Admin API key (for provisioning/management)
+            endpoint: LockStock API endpoint
+            timeout: Request timeout in seconds
+        """
+        self.agent_id = agent_id
+        self.secret = secret
+        self.api_key = api_key
+        self.endpoint = endpoint.rstrip("/")
+        self.timeout = timeout
+
+        # State tracking
+        self._current_hash = "0" * 64  # Genesis hash
+        self._sequence = 0
+        self._state_matrix = Matrix.identity()
+
+        # HTTP client
+        self._client = httpx.AsyncClient(timeout=timeout)
+
+    async def verify(
+        self,
+        task: str,
+        tool_name: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None
+    ) -> VerifyResult:
+        """
+        Verify that the agent is authorized to perform a task.
+
+        Args:
+            task: The capability/task to verify (e.g., "DEPLOY", "RESTART")
+            tool_name: Optional tool name (will be mapped to capability)
+            metadata: Optional metadata to include in audit
+
+        Returns:
+            VerifyResult with authorization status
+        """
+        # Map tool name to capability if provided
+        if tool_name and task == "UNKNOWN":
+            task = map_tool_to_capability(tool_name)
+
+        # Prepare request
+        self._sequence += 1
+        timestamp = int(time.time())
+
+        # Apply generator matrix for this task (topological state transition)
+        generator = get_generator(task)
+        new_matrix = self._state_matrix.multiply(generator)
+
+        # Create signature with the NEW matrix (uses timestamp, not sequence)
+        signature = self._sign_request(task, self._current_hash, timestamp, new_matrix)
+
+        payload = {
+            "client_id": self.agent_id,
+            "task": task.lower(),
+            "parent_hash": self._current_hash,
+            "state_matrix": new_matrix.to_dict(),
+            "signature": signature,
+            "timestamp": timestamp,
+            "sequence": self._sequence
+        }
+
+        try:
+            response = await self._client.post(
+                f"{self.endpoint}/verify",
+                json=payload,
+                headers=self._headers()
+            )
+
+            data = response.json()
+
+            status = VerifyStatus(data.get("status", "rejected"))
+
+            if status == VerifyStatus.ACCEPTED:
+                # Update state from server response
+                self._current_hash = data.get("state_hash", self._current_hash)
+                if "state_matrix" in data:
+                    self._state_matrix = Matrix.from_dict(data["state_matrix"])
+
+            return VerifyResult(
+                status=status,
+                reason=data.get("reason"),
+                state_hash=data.get("state_hash"),
+                server_timestamp=data.get("server_timestamp")
+            )
+
+        except httpx.HTTPError as e:
+            return VerifyResult(
+                status=VerifyStatus.REJECTED,
+                reason=f"HTTP error: {str(e)}"
+            )
+        except Exception as e:
+            return VerifyResult(
+                status=VerifyStatus.REJECTED,
+                reason=f"Client error: {str(e)}"
+            )
+
+    async def verify_tool(self, tool_name: str, tool_input: Optional[Dict] = None) -> VerifyResult:
+        """
+        Verify authorization for a specific tool call.
+
+        Args:
+            tool_name: Name of the tool being called
+            tool_input: The tool's input parameters
+
+        Returns:
+            VerifyResult with authorization status
+        """
+        capability = map_tool_to_capability(tool_name)
+        return await self.verify(task=capability, tool_name=tool_name)
+
+    async def bootstrap(self) -> Dict[str, Any]:
+        """
+        Initialize the agent's identity with the server.
+
+        Returns:
+            Bootstrap response with root hash and matrix
+        """
+        try:
+            response = await self._client.post(
+                f"{self.endpoint}/bootstrap",
+                json={"client_id": self.agent_id},
+                headers=self._headers()
+            )
+
+            data = response.json()
+
+            if "root_hash" in data:
+                self._current_hash = data["root_hash"]
+                if "root_matrix" in data:
+                    self._state_matrix = Matrix.from_dict(data["root_matrix"])
+                self._sequence = 0
+
+            return data
+
+        except Exception as e:
+            return {"error": str(e)}
+
+    async def get_agent_card(self) -> Optional[AgentCard]:
+        """
+        Retrieve the agent's card from the server.
+
+        Returns:
+            AgentCard if found, None otherwise
+        """
+        try:
+            response = await self._client.get(
+                f"{self.endpoint}/api/guard/agents/{self.agent_id}",
+                headers=self._headers()
+            )
+
+            if response.status_code == 200:
+                data = response.json()
+                return AgentCard(
+                    agent_id=data.get("agent_id", self.agent_id),
+                    display_name=data.get("display_name", ""),
+                    capabilities=data.get("capabilities", []),
+                    status=data.get("status", "unknown"),
+                    fingerprint=data.get("fingerprint"),
+                    owner_id=data.get("owner_id"),
+                    created_at=data.get("created_at")
+                )
+            return None
+
+        except Exception:
+            return None
+
+    async def log_audit(
+        self,
+        action: str,
+        status: str,
+        metadata: Optional[Dict[str, Any]] = None
+    ) -> bool:
+        """
+        Log an action to the audit trail.
+
+        Args:
+            action: The action that was performed
+            status: Status of the action (e.g., "APPROVED", "DENIED")
+            metadata: Additional metadata to log
+
+        Returns:
+            True if logged successfully
+        """
+        # Audit is automatically logged via verify() calls
+        # This method is for explicit logging of non-verified actions
+        entry = AuditEntry(
+            sequence=self._sequence,
+            action=action,
+            timestamp=int(time.time()),
+            state_hash=self._current_hash,
+            signature=self._sign_request(action, self._current_hash, self._sequence),
+            metadata=metadata or {}
+        )
+
+        # In production, this would POST to an audit endpoint
+        # For now, we just track locally
+        return True
+
+    def _sign_request(self, task: str, parent_hash: str, timestamp: int, matrix: Matrix = None) -> str:
+        """Create HMAC signature for a request.
+
+        The signature format matches the Rust server:
+        {client_id}|{Task}|{parent_hash}|{a11},{a12},{a21},{a22}|{timestamp}
+
+        IMPORTANT: The task name must match Rust's Debug format (e.g., "Heartbeat", "FileRead")
+        because the server uses {:?} formatting for the Task enum in signature generation.
+        """
+        if not self.secret:
+            return "unsigned"
+
+        # Use provided matrix or current state
+        m = matrix if matrix else self._state_matrix
+        matrix_str = f"{m.a11},{m.a12},{m.a21},{m.a22}"
+
+        # Normalize task to Rust Debug format (e.g., "HEARTBEAT" -> "Heartbeat")
+        rust_task = normalize_task_for_signature(task)
+
+        # Build message in server's expected format
+        message = f"{self.agent_id}|{rust_task}|{parent_hash}|{matrix_str}|{timestamp}"
+
+        signature = hmac.new(
+            self.secret.encode(),
+            message.encode(),
+            hashlib.sha256
+        ).hexdigest()
+
+        return signature
+
+    def _headers(self) -> Dict[str, str]:
+        """Build request headers."""
+        headers = {"Content-Type": "application/json"}
+        if self.api_key:
+            headers["x-admin-key"] = self.api_key
+        return headers
+
+    async def close(self):
+        """Close the HTTP client."""
+        await self._client.aclose()
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        await self.close()

lockstock_core/types.py

@@ -0,0 +1,264 @@
+"""
+LockStock Core Types
+--------------------
+Shared types for all SDK integrations.
+"""
+
+from dataclasses import dataclass, field
+from typing import List, Optional, Dict, Any
+from enum import Enum
+
+
+class VerifyStatus(str, Enum):
+    ACCEPTED = "accepted"
+    REJECTED = "rejected"
+    BUFFERED = "buffered"
+
+
+@dataclass
+class VerifyResult:
+    """Result of a capability verification request."""
+    status: VerifyStatus
+    reason: Optional[str] = None
+    state_hash: Optional[str] = None
+    server_timestamp: Optional[int] = None
+
+    @property
+    def authorized(self) -> bool:
+        return self.status == VerifyStatus.ACCEPTED
+
+
+@dataclass
+class AuditEntry:
+    """An entry in the agent's audit trail."""
+    sequence: int
+    action: str
+    timestamp: int
+    state_hash: str
+    signature: str
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class AgentCard:
+    """Agent identity and capabilities."""
+    agent_id: str
+    display_name: str
+    capabilities: List[str]
+    status: str = "active"
+    fingerprint: Optional[str] = None
+    owner_id: Optional[str] = None
+    created_at: Optional[str] = None
+
+    def has_capability(self, capability: str) -> bool:
+        """Check if agent has a specific capability."""
+        return capability.upper() in [c.upper() for c in self.capabilities]
+
+
+# Mapping from common tool names to LockStock capabilities
+# These map to the Task enum variants in Rust (case-insensitive)
+TOOL_CAPABILITY_MAP = {
+    # File operations -> FileRead, FileWrite
+    "read": "FILEREAD",
+    "read_file": "FILEREAD",
+    "Read": "FILEREAD",
+    "Glob": "FILEREAD",
+    "glob": "FILEREAD",
+    "Grep": "FILEREAD",
+    "grep": "FILEREAD",
+    "write": "FILEWRITE",
+    "write_file": "FILEWRITE",
+    "Write": "FILEWRITE",
+    "edit": "FILEWRITE",
+    "Edit": "FILEWRITE",
+    "NotebookEdit": "FILEWRITE",
+
+    # Shell/execution -> Shell (alias for Deploy)
+    "bash": "SHELL",
+    "Bash": "SHELL",
+    "shell": "SHELL",
+    "execute": "SHELL",
+    "run_command": "SHELL",
+    "KillShell": "SHELL",
+
+    # Network operations -> Network
+    "web_fetch": "NETWORK",
+    "WebFetch": "NETWORK",
+    "web_search": "NETWORK",
+    "WebSearch": "NETWORK",
+    "http_request": "NETWORK",
+    "fetch": "NETWORK",
+
+    # Database operations -> Database
+    "sql": "DATABASE",
+    "query": "DATABASE",
+    "db_read": "DATABASE",
+    "db_write": "DATABASE",
+    "LSP": "DATABASE",  # Language Server Protocol reads code
+
+    # Agent operations -> Teleport, Handoff
+    "task": "TELEPORT",
+    "Task": "TELEPORT",
+    "spawn_agent": "TELEPORT",
+    "TaskOutput": "TELEPORT",
+    "handoff": "HANDOFF",
+    "delegate": "DELEGATE",
+
+    # State operations -> Checkpoint, Teleport
+    "checkpoint": "CHECKPOINT",
+    "save_state": "CHECKPOINT",
+    "export_passport": "TELEPORT",
+    "import_passport": "TELEPORT",
+
+    # Monitoring -> Heartbeat
+    "heartbeat": "HEARTBEAT",
+    "health_check": "HEARTBEAT",
+
+    # Operations -> Deploy, Restart, Backup, Rollback
+    "deploy": "DEPLOY",
+    "restart": "RESTART",
+    "backup": "BACKUP",
+    "rollback": "ROLLBACK",
+
+    # Task management tools
+    "TaskCreate": "FILEWRITE",
+    "TaskUpdate": "FILEWRITE",
+    "TaskList": "FILEREAD",
+    "TaskGet": "FILEREAD",
+
+    # Skills
+    "Skill": "SHELL",
+    "AskUserQuestion": "HEARTBEAT",  # Interactive, low privilege
+    "EnterPlanMode": "HEARTBEAT",
+    "ExitPlanMode": "HEARTBEAT",
+}
+
+
+def map_tool_to_capability(tool_name: str) -> str:
+    """Map a tool name to a LockStock capability."""
+    return TOOL_CAPABILITY_MAP.get(tool_name, "UNKNOWN")
+
+
+# Mapping from any case to Rust Debug format (used in HMAC signatures)
+# The Rust server uses {:?} format which produces these exact strings
+TASK_RUST_DEBUG_FORMAT = {
+    # Operations
+    "deploy": "Deploy",
+    "restart": "Restart",
+    "backup": "Backup",
+    "rollback": "Rollback",
+    # Agent lifecycle
+    "heartbeat": "Heartbeat",
+    "checkpoint": "Checkpoint",
+    "teleport": "Teleport",
+    # MCP tool categories
+    "fileread": "FileRead",
+    "file_read": "FileRead",
+    "read": "FileRead",
+    "query": "FileRead",
+    "filewrite": "FileWrite",
+    "file_write": "FileWrite",
+    "write": "FileWrite",
+    "edit": "FileWrite",
+    "network": "Network",
+    "http": "Network",
+    "fetch": "Network",
+    "shell": "Shell",
+    "bash": "Shell",
+    "exec": "Shell",
+    "execute": "Shell",
+    "database": "Database",
+    "db": "Database",
+    "sql": "Database",
+    # A2A protocol
+    "handoff": "Handoff",
+    "hand_off": "Handoff",
+    "delegate": "Delegate",
+    # Wildcard
+    "all": "All",
+    "admin": "All",
+}
+
+
+def normalize_task_for_signature(task: str) -> str:
+    """
+    Convert a task name to the Rust Debug format used in HMAC signatures.
+
+    The Rust server uses {:?} format for Task enum in signatures, which produces
+    PascalCase variants like 'Heartbeat', 'FileRead', etc.
+
+    Args:
+        task: Task name in any case (e.g., "HEARTBEAT", "heartbeat", "Heartbeat")
+
+    Returns:
+        Task name in Rust Debug format (e.g., "Heartbeat")
+    """
+    normalized = TASK_RUST_DEBUG_FORMAT.get(task.lower())
+    if normalized:
+        return normalized
+
+    # Fallback: try to capitalize properly for unknown tasks
+    # This handles cases like "deploy" -> "Deploy"
+    return task.capitalize()
+
+
+# Prime field modulus (F_65537)
+MODULUS = 65537
+
+
+class Matrix:
+    """2x2 matrix over F_65537 for topological state transitions."""
+
+    def __init__(self, a11: int, a12: int, a21: int, a22: int):
+        self.a11 = a11 % MODULUS
+        self.a12 = a12 % MODULUS
+        self.a21 = a21 % MODULUS
+        self.a22 = a22 % MODULUS
+
+    def multiply(self, other: "Matrix") -> "Matrix":
+        """Matrix multiplication in F_65537."""
+        return Matrix(
+            (self.a11 * other.a11 + self.a12 * other.a21) % MODULUS,
+            (self.a11 * other.a12 + self.a12 * other.a22) % MODULUS,
+            (self.a21 * other.a11 + self.a22 * other.a21) % MODULUS,
+            (self.a21 * other.a12 + self.a22 * other.a22) % MODULUS,
+        )
+
+    def to_dict(self) -> Dict[str, int]:
+        """Convert to dictionary for JSON serialization."""
+        return {"a11": self.a11, "a12": self.a12, "a21": self.a21, "a22": self.a22}
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, int]) -> "Matrix":
+        """Create from dictionary."""
+        return cls(d.get("a11", 1), d.get("a12", 0), d.get("a21", 0), d.get("a22", 1))
+
+    @classmethod
+    def identity(cls) -> "Matrix":
+        """Return identity matrix."""
+        return cls(1, 0, 0, 1)
+
+
+# Generator matrices for each task (matching Rust server)
+GENERATOR_MATRICES = {
+    "DEPLOY": Matrix(1, 1, 0, 1),
+    "RESTART": Matrix(1, 0, 1, 1),
+    "BACKUP": Matrix(2, 1, 1, 1),
+    "ROLLBACK": Matrix(1, 1, 1, 2),
+    "HEARTBEAT": Matrix(0, 65536, 1, 0),  # 90-degree rotation
+    "CHECKPOINT": Matrix(2, 1, 1, 2),
+    "TELEPORT": Matrix(3, 1, 1, 1),
+    "FILEREAD": Matrix(1, 2, 0, 1),
+    "FILEWRITE": Matrix(1, 3, 0, 1),
+    "NETWORK": Matrix(1, 0, 2, 1),
+    "SHELL": Matrix(1, 4, 0, 1),  # Upper triangular (distinct from Deploy, v1.0.8+)
+    "DATABASE": Matrix(1, 0, 3, 1),
+    "HANDOFF": Matrix(3, 2, 1, 1),
+    "DELEGATE": Matrix(1, 1, 2, 3),
+    "ALL": Matrix(1, 0, 0, 1),  # Identity
+}
+
+
+def get_generator(task: str) -> Matrix:
+    """Get the generator matrix for a task."""
+    return GENERATOR_MATRICES.get(task.upper(), Matrix.identity())

{lockstock_integrations-1.1.0.dist-info → lockstock_integrations-1.1.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lockstock-integrations
-Version: 1.1.0
+Version: 1.1.1
 Summary: LockStock compliance runtime integrations for AI Agent SDKs
 Project-URL: Homepage, https://d3cipher.ai
 Project-URL: Documentation, https://d3cipher.ai/docs

{lockstock_integrations-1.1.0.dist-info → lockstock_integrations-1.1.1.dist-info}/RECORD

@@ -5,12 +5,15 @@ lockstock_a2a/task_handler.py,sha256=hKpk9smt12nqTlJua861LpdKiiXpcRGRYhCW0SwS438
 lockstock_claude/__init__.py,sha256=yI1e13JC_KKgYrap2AIkVl5biCsHKfb9rPtgbN1QNtg,320
 lockstock_claude/hooks.py,sha256=uJ-i3s9pmwcgSIpc84TlxNAyP2a1S8Auyo6o1H3KrcU,5116
 lockstock_claude/skills.py,sha256=4f6HprTBfjmPvcDzJ40fcsMoF543EybbE0_KM_kBtpQ,4023
+lockstock_core/__init__.py,sha256=Euan9X4O6XBgQ8IYoC5hj2ruTNU0vPLvBTCIPZZNQdU,258
+lockstock_core/client.py,sha256=gNacFIoH9DA9Dw2moyfPHGj7mlexrJ7VxIo0e3iRX8M,9110
+lockstock_core/types.py,sha256=4OtO7PWcZyXxbmuFcoXXxjO3tKHV1oNGpm5yExLTCQE,7426
 lockstock_langgraph/__init__.py,sha256=7fBIYNCQygvUvG7IQOVY042sNNmu4UwkJoy0VLQn4Ik,425
 lockstock_langgraph/checkpointer.py,sha256=XJ2c_92OSBq4aNpOT112nTy3yI3stFcSCb8OTx04nos,6317
 lockstock_langgraph/middleware.py,sha256=ZSwoxdkn3cC6aIBnMgd1jYGHYKa1yQXRwnts3Ds4sfQ,9174
 lockstock_openai/__init__.py,sha256=Pc4phRUJEqrnREggyGJnc1HDKa7puVAR6-G9WZ4dtXM,402
 lockstock_openai/guardrails.py,sha256=fy84bDrhy6CVk2b4_yOl5XTxw9Lp1HT4Mw9WcaAHOsg,11920
 lockstock_openai/tracing.py,sha256=VQWzG0y6t8q5rJZFbbP-bi9tsV0KaUqqH4Kr9-vr_e8,6025
-lockstock_integrations-1.1.0.dist-info/METADATA,sha256=2oQWjepWJDR6-Q_L5tOmiaDCg4gGm6K5-JcEIRYtRSE,5629
-lockstock_integrations-1.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-lockstock_integrations-1.1.0.dist-info/RECORD,,
+lockstock_integrations-1.1.1.dist-info/METADATA,sha256=H022KMhtIDctPxNHkdc70WRfzjyO72xwK6Ed5u69Au8,5629
+lockstock_integrations-1.1.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+lockstock_integrations-1.1.1.dist-info/RECORD,,