xache 5.0.0__py3-none-any.whl

xache/services/memory.py

@@ -0,0 +1,401 @@
+"""Memory Service - Store, retrieve, delete encrypted memories per LLD §2.4"""
+
+import json
+import hashlib
+from typing import Dict, Any, Optional, List
+
+import nacl.secret
+import nacl.utils
+import nacl.hash
+
+from ..types import (
+    StoreMemoryRequest,
+    StoreMemoryResponse,
+    RetrieveMemoryResponse,
+    BatchStoreMemoryRequest,
+    BatchStoreMemoryResponse,
+    BatchStoreMemoryResult,
+    BatchRetrieveMemoryRequest,
+    BatchRetrieveMemoryResponse,
+    BatchRetrieveMemoryResult,
+)
+
+
+class MemoryService:
+    """Memory service for encrypted data storage"""
+
+    def __init__(self, client):
+        self.client = client
+        self._encryption_key: Optional[bytes] = None
+
+    async def store(
+        self,
+        data: Dict[str, Any],
+        storage_tier: str,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> StoreMemoryResponse:
+        """
+        Store encrypted memory per LLD §2.4
+        Cost: $0.01 (automatic 402 payment)
+
+        Example:
+            ```python
+            memory = await client.memory.store(
+                data={"key": "value", "nested": {"data": 123}},
+                storage_tier="hot",
+                metadata={"tags": ["important"]},
+            )
+            print(f"Memory ID: {memory.memory_id}")
+            ```
+        """
+        # Validate request
+        self._validate_store_request(data, storage_tier)
+
+        # Get encryption key
+        key = await self._get_encryption_key()
+
+        # Encrypt data client-side using PyNaCl
+        encrypted_data = self._encrypt_data(data, key)
+
+        # Make API request with automatic 402 payment
+        response = await self.client.request_with_payment(
+            "POST",
+            "/v1/memory/store",
+            {
+                "encryptedData": encrypted_data,
+                "storageTier": storage_tier,
+                "metadata": metadata,
+            },
+        )
+
+        if not response.success or not response.data:
+            raise Exception("Memory store failed")
+
+        resp_data = response.data
+        return StoreMemoryResponse(
+            memory_id=resp_data["memoryId"],
+            storage_tier=resp_data["storageTier"],
+            size=resp_data["size"],
+            receipt_id=resp_data["receiptId"],
+        )
+
+    async def retrieve(self, memory_id: str) -> RetrieveMemoryResponse:
+        """
+        Retrieve encrypted memory per LLD §2.4
+        Cost: $0.005 (automatic 402 payment)
+        """
+        if not memory_id:
+            raise ValueError("memory_id is required")
+
+        # Make API request with automatic 402 payment
+        response = await self.client.request_with_payment(
+            "POST",
+            "/v1/memory/retrieve",
+            {"memoryId": memory_id},
+        )
+
+        if not response.success or not response.data:
+            raise Exception("Memory retrieve failed")
+
+        resp_data = response.data
+
+        # Get encryption key
+        key = await self._get_encryption_key()
+
+        # Decrypt data client-side
+        decrypted_data = self._decrypt_data(resp_data["encryptedData"], key)
+
+        return RetrieveMemoryResponse(
+            memory_id=resp_data["memoryId"],
+            data=decrypted_data,
+            storage_tier=resp_data["storageTier"],
+            metadata=resp_data.get("metadata"),
+            receipt_id=resp_data["receiptId"],
+        )
+
+    async def delete(self, memory_id: str) -> Dict[str, Any]:
+        """Delete memory per LLD §2.4 (free)"""
+        if not memory_id:
+            raise ValueError("memory_id is required")
+
+        response = await self.client.request(
+            "DELETE",
+            f"/v1/memory/{memory_id}",
+        )
+
+        if not response.success or not response.data:
+            raise Exception("Memory delete failed")
+
+        return response.data
+
+    async def store_batch(
+        self,
+        items: List[Dict[str, Any]],
+    ) -> BatchStoreMemoryResponse:
+        """
+        Batch store encrypted memories per PRD FR-010, LLD §2.3
+        Max 100 items per batch
+        Cost: Single 402 payment for entire batch
+
+        Example:
+            ```python
+            result = await client.memory.store_batch([
+                {"data": {"key": "value1"}, "storage_tier": "hot"},
+                {"data": {"key": "value2"}, "storage_tier": "warm"},
+                {"data": {"key": "value3"}, "storage_tier": "cold"},
+            ])
+
+            print(f"Success: {result.success_count}, Failed: {result.failure_count}")
+            for r in result.results:
+                if r.memory_id:
+                    print(f"Stored: {r.memory_id}")
+                else:
+                    print(f"Failed: {r.error}")
+            ```
+        """
+        # Validate batch request
+        if not isinstance(items, list):
+            raise ValueError("items must be a list")
+
+        if len(items) == 0:
+            raise ValueError("items list cannot be empty")
+
+        if len(items) > 100:
+            raise ValueError("batch size exceeds maximum of 100 items")
+
+        # Validate each item
+        for idx, item in enumerate(items):
+            try:
+                self._validate_store_request(item.get("data"), item.get("storage_tier"))
+            except Exception as e:
+                raise ValueError(f"Invalid item at index {idx}: {str(e)}")
+
+        # Get encryption key
+        key = await self._get_encryption_key()
+
+        # Encrypt all items client-side
+        encrypted_items = []
+        for item in items:
+            encrypted_data = self._encrypt_data(item["data"], key)
+            encrypted_items.append({
+                "encryptedData": encrypted_data,
+                "storageTier": item["storage_tier"],
+                "metadata": item.get("metadata"),
+            })
+
+        # Make API request with automatic 402 payment
+        response = await self.client.request_with_payment(
+            "POST",
+            "/v1/memory/store/batch",
+            {"items": encrypted_items},
+        )
+
+        if not response.success or not response.data:
+            raise Exception("Batch memory store failed")
+
+        resp_data = response.data
+
+        # Convert results to dataclass instances
+        results = [
+            BatchStoreMemoryResult(
+                index=r["index"],
+                memory_id=r.get("memoryId"),
+                receipt_id=r.get("receiptId"),
+                error=r.get("error"),
+            )
+            for r in resp_data["results"]
+        ]
+
+        return BatchStoreMemoryResponse(
+            results=results,
+            success_count=resp_data["successCount"],
+            failure_count=resp_data["failureCount"],
+            batch_receipt_id=resp_data["batchReceiptId"],
+        )
+
+    async def retrieve_batch(
+        self,
+        memory_ids: List[str],
+    ) -> BatchRetrieveMemoryResponse:
+        """
+        Batch retrieve encrypted memories per PRD FR-011, LLD §2.3
+        Max 100 items per batch
+        Cost: Single 402 payment for entire batch
+
+        Example:
+            ```python
+            result = await client.memory.retrieve_batch([
+                "mem_abc123",
+                "mem_def456",
+                "mem_ghi789",
+            ])
+
+            print(f"Success: {result.success_count}, Failed: {result.failure_count}")
+            for r in result.results:
+                if r.data:
+                    print(f"Retrieved: {r.memory_id}, {r.data}")
+                else:
+                    print(f"Failed: {r.error}")
+            ```
+        """
+        # Validate batch request
+        if not isinstance(memory_ids, list):
+            raise ValueError("memory_ids must be a list")
+
+        if len(memory_ids) == 0:
+            raise ValueError("memory_ids list cannot be empty")
+
+        if len(memory_ids) > 100:
+            raise ValueError("batch size exceeds maximum of 100 items")
+
+        # Validate each memoryId
+        for idx, memory_id in enumerate(memory_ids):
+            if not memory_id or not isinstance(memory_id, str):
+                raise ValueError(f"Invalid memory_id at index {idx}")
+
+        # Make API request with automatic 402 payment
+        response = await self.client.request_with_payment(
+            "POST",
+            "/v1/memory/retrieve/batch",
+            {"memoryIds": memory_ids},
+        )
+
+        if not response.success or not response.data:
+            raise Exception("Batch memory retrieve failed")
+
+        resp_data = response.data
+
+        # Get encryption key
+        key = await self._get_encryption_key()
+
+        # Decrypt all successfully retrieved items
+        results = []
+        for result in resp_data["results"]:
+            # If retrieval failed, return error as-is
+            if result.get("error") or not result.get("encryptedData"):
+                results.append(
+                    BatchRetrieveMemoryResult(
+                        index=result["index"],
+                        memory_id=result.get("memoryId"),
+                        error=result.get("error") or "No data returned",
+                    )
+                )
+                continue
+
+            # Decrypt the data
+            try:
+                decrypted_data = self._decrypt_data(result["encryptedData"], key)
+                results.append(
+                    BatchRetrieveMemoryResult(
+                        index=result["index"],
+                        memory_id=result.get("memoryId"),
+                        data=decrypted_data,
+                        storage_tier=result.get("storageTier"),
+                        metadata=result.get("metadata"),
+                        receipt_id=result.get("receiptId"),
+                    )
+                )
+            except Exception as e:
+                results.append(
+                    BatchRetrieveMemoryResult(
+                        index=result["index"],
+                        memory_id=result.get("memoryId"),
+                        error=f"Decryption failed: {str(e)}",
+                    )
+                )
+
+        return BatchRetrieveMemoryResponse(
+            results=results,
+            success_count=resp_data["successCount"],
+            failure_count=resp_data["failureCount"],
+            batch_receipt_id=resp_data["batchReceiptId"],
+        )
+
+    def _validate_store_request(self, data: Dict[str, Any], storage_tier: str):
+        """Validate store request"""
+        if not isinstance(data, dict):
+            raise ValueError("data must be a dictionary")
+
+        if storage_tier not in ["hot", "warm", "cold"]:
+            raise ValueError('storage_tier must be "hot", "warm", or "cold"')
+
+        # Validate data size
+        json_str = json.dumps(data)
+        if len(json_str) > 400:
+            raise ValueError("data too large (max ~400 characters)")
+
+    async def _get_encryption_key(self) -> bytes:
+        """Get or derive encryption key"""
+        if self._encryption_key is None:
+            self._encryption_key = self._derive_encryption_key()
+        return self._encryption_key
+
+    def _derive_encryption_key(self) -> bytes:
+        """
+        Derive encryption key from client configuration using PyNaCl
+        Uses BLAKE2b hash function for deterministic key derivation
+        """
+        key_material = self.client.private_key + self.client.did
+        key_material_bytes = key_material.encode('utf-8')
+
+        # Use BLAKE2b for deterministic key derivation (32 bytes for SecretBox)
+        key = nacl.hash.blake2b(
+            key_material_bytes,
+            digest_size=nacl.secret.SecretBox.KEY_SIZE,
+            encoder=nacl.encoding.RawEncoder
+        )
+
+        return key
+
+    def _encrypt_data(self, data: Dict[str, Any], key: bytes) -> str:
+        """
+        Encrypt data using PyNaCl SecretBox (XSalsa20-Poly1305)
+        """
+        import base64
+
+        # Convert data to JSON bytes
+        json_str = json.dumps(data)
+        json_bytes = json_str.encode('utf-8')
+
+        # Create SecretBox with key
+        box = nacl.secret.SecretBox(key)
+
+        # Encrypt (nonce is automatically generated and prepended)
+        encrypted = box.encrypt(json_bytes)
+
+        # Return base64 encoded ciphertext (includes nonce)
+        return base64.b64encode(encrypted).decode('utf-8')
+
+    def _decrypt_data(self, encrypted_data: str, key: bytes) -> Dict[str, Any]:
+        """
+        Decrypt data using PyNaCl SecretBox
+        """
+        import base64
+
+        # Decode from base64
+        encrypted_bytes = base64.b64decode(encrypted_data)
+
+        # Create SecretBox with key
+        box = nacl.secret.SecretBox(key)
+
+        # Decrypt (nonce is automatically extracted from ciphertext)
+        decrypted_bytes = box.decrypt(encrypted_bytes)
+
+        # Convert to JSON
+        json_str = decrypted_bytes.decode('utf-8')
+        return json.loads(json_str)
+
+    def set_encryption_key(self, key: bytes):
+        """
+        Set custom encryption key
+        Useful for testing or using external key management
+        """
+        if len(key) != nacl.secret.SecretBox.KEY_SIZE:
+            raise ValueError(f"Key must be {nacl.secret.SecretBox.KEY_SIZE} bytes")
+        self._encryption_key = key
+
+    async def get_current_encryption_key(self) -> bytes:
+        """
+        Get current encryption key (for backup purposes)
+        """
+        return await self._get_encryption_key()

xache/services/owner.py

@@ -0,0 +1,293 @@
+"""
+Owner Service - Owner identity registration and management
+"""
+
+from typing import List, Optional, Dict
+from dataclasses import dataclass
+from ..types import DID
+
+
+@dataclass
+class Owner:
+    """Owner profile information"""
+    owner_did: DID
+    wallet_address: str
+    wallet_chain: str  # 'evm' | 'solana'
+    entity_type: str  # 'human' | 'organization'
+    display_name: Optional[str]
+    organization_name: Optional[str]
+    email: Optional[str]
+    email_verified: bool
+    wallet_verified: bool
+    created_at: str
+    updated_at: str
+
+
+@dataclass
+class OwnedAgent:
+    """Owned agent information"""
+    agent_did: DID
+    wallet_address: str
+    chain: str
+    claim_type: str  # 'individual' | 'workspace'
+    workspace_id: Optional[str]
+    workspace_name: Optional[str]
+    role: Optional[str]  # 'admin' | 'member'
+    added_at: str
+
+
+class OwnerService:
+    """
+    Owner service for identity registration and management
+
+    Register and manage owner identities for enterprise fleet management.
+    """
+
+    def __init__(self, client):
+        self.client = client
+
+    async def register(
+        self,
+        wallet_address: str,
+        wallet_chain: str,
+        entity_type: str,
+        display_name: Optional[str] = None,
+        organization_name: Optional[str] = None,
+        email: Optional[str] = None,
+        supabase_user_id: Optional[str] = None,
+    ) -> Owner:
+        """
+        Register a new owner (human or organization)
+
+        Args:
+            wallet_address: Wallet address
+            wallet_chain: Wallet chain ('evm' or 'solana')
+            entity_type: Entity type ('human' or 'organization')
+            display_name: Optional display name
+            organization_name: Optional organization name
+            email: Optional email address
+            supabase_user_id: Optional Supabase user ID
+
+        Returns:
+            Registered owner
+
+        Example:
+            ```python
+            owner = await client.owner.register(
+                wallet_address="0x1234...",
+                wallet_chain="evm",
+                entity_type="human",
+                display_name="John Doe",
+                email="john@example.com"
+            )
+            print(f"Registered: {owner.owner_did}")
+            ```
+        """
+        body = {
+            "walletAddress": wallet_address,
+            "walletChain": wallet_chain,
+            "entityType": entity_type,
+        }
+
+        if display_name:
+            body["displayName"] = display_name
+        if organization_name:
+            body["organizationName"] = organization_name
+        if email:
+            body["email"] = email
+        if supabase_user_id:
+            body["supabaseUserId"] = supabase_user_id
+
+        response = await self.client.request(
+            "POST", "/v1/owners/register", body, skip_auth=True
+        )
+
+        if not response.success or not response.data:
+            raise Exception(
+                response.error.get("message", "Failed to register owner")
+                if response.error
+                else "Failed to register owner"
+            )
+
+        return self._parse_owner(response.data.get("owner", response.data))
+
+    async def verify_wallet(
+        self,
+        owner_did: DID,
+        message: str,
+        signature: str,
+        timestamp: int,
+    ) -> bool:
+        """
+        Verify wallet ownership with cryptographic signature
+
+        Args:
+            owner_did: Owner DID
+            message: Message that was signed
+            signature: Signature
+            timestamp: Timestamp of signature
+
+        Returns:
+            True if verified
+
+        Example:
+            ```python
+            verified = await client.owner.verify_wallet(
+                owner_did="did:owner:evm:0x1234...",
+                message="Verify wallet ownership",
+                signature="0x...",
+                timestamp=1699900000
+            )
+            print(f"Verified: {verified}")
+            ```
+        """
+        body = {
+            "ownerDID": owner_did,
+            "message": message,
+            "signature": signature,
+            "timestamp": timestamp,
+        }
+
+        response = await self.client.request(
+            "POST", "/v1/owners/verify-wallet", body, skip_auth=True
+        )
+
+        if not response.success or response.data is None:
+            raise Exception(
+                response.error.get("message", "Failed to verify wallet")
+                if response.error
+                else "Failed to verify wallet"
+            )
+
+        return response.data.get("verified", False)
+
+    async def get_profile(self) -> Optional[Owner]:
+        """
+        Get the authenticated owner's profile
+
+        Returns:
+            Owner profile or None if not found
+
+        Example:
+            ```python
+            profile = await client.owner.get_profile()
+            if profile:
+                print(f"Display name: {profile.display_name}")
+            ```
+        """
+        response = await self.client.request("GET", "/v1/owners/me")
+
+        if not response.success:
+            raise Exception(
+                response.error.get("message", "Failed to get profile")
+                if response.error
+                else "Failed to get profile"
+            )
+
+        if not response.data or not response.data.get("owner"):
+            return None
+
+        return self._parse_owner(response.data["owner"])
+
+    async def update_profile(
+        self,
+        display_name: Optional[str] = None,
+        organization_name: Optional[str] = None,
+        email: Optional[str] = None,
+    ) -> Owner:
+        """
+        Update the authenticated owner's profile
+
+        Args:
+            display_name: Optional new display name
+            organization_name: Optional new organization name
+            email: Optional new email
+
+        Returns:
+            Updated owner profile
+
+        Example:
+            ```python
+            updated = await client.owner.update_profile(
+                display_name="Jane Doe",
+                organization_name="Acme Corp"
+            )
+            print(f"Updated: {updated.display_name}")
+            ```
+        """
+        body = {}
+        if display_name is not None:
+            body["displayName"] = display_name
+        if organization_name is not None:
+            body["organizationName"] = organization_name
+        if email is not None:
+            body["email"] = email
+
+        response = await self.client.request("PUT", "/v1/owners/me", body)
+
+        if not response.success or not response.data:
+            raise Exception(
+                response.error.get("message", "Failed to update profile")
+                if response.error
+                else "Failed to update profile"
+            )
+
+        return self._parse_owner(response.data.get("owner", response.data))
+
+    async def get_owned_agents(self) -> Dict:
+        """
+        Get all agents owned by the authenticated owner
+
+        Returns:
+            Dictionary with agents and count
+
+        Example:
+            ```python
+            result = await client.owner.get_owned_agents()
+            print(f"Total owned agents: {result['count']}")
+
+            for agent in result['agents']:
+                print(f"{agent.agent_did} - {agent.claim_type}")
+            ```
+        """
+        response = await self.client.request("GET", "/v1/owners/me/agents")
+
+        if not response.success or not response.data:
+            raise Exception(
+                response.error.get("message", "Failed to get owned agents")
+                if response.error
+                else "Failed to get owned agents"
+            )
+
+        return {
+            "agents": [
+                OwnedAgent(
+                    agent_did=a["agentDID"],
+                    wallet_address=a["walletAddress"],
+                    chain=a["chain"],
+                    claim_type=a["claimType"],
+                    workspace_id=a.get("workspaceId"),
+                    workspace_name=a.get("workspaceName"),
+                    role=a.get("role"),
+                    added_at=a["addedAt"],
+                )
+                for a in response.data.get("agents", [])
+            ],
+            "count": response.data.get("count", 0),
+        }
+
+    def _parse_owner(self, data: dict) -> Owner:
+        """Parse owner data into Owner object"""
+        return Owner(
+            owner_did=data["ownerDID"],
+            wallet_address=data["walletAddress"],
+            wallet_chain=data["walletChain"],
+            entity_type=data["entityType"],
+            display_name=data.get("displayName"),
+            organization_name=data.get("organizationName"),
+            email=data.get("email"),
+            email_verified=data.get("emailVerified", False),
+            wallet_verified=data.get("walletVerified", False),
+            created_at=data["createdAt"],
+            updated_at=data["updatedAt"],
+        )