xache 5.0.0__py3-none-any.whl

xache/crypto/signing.py

@@ -0,0 +1,244 @@
+"""
+Request signing utilities per LLD §2.1
+Signature format: METHOD\nPATH\nSHA256(body)\nX-Ts\nX-Agent-DID
+"""
+
+import hashlib
+import re
+import time
+from typing import Dict
+
+from eth_account import Account
+from eth_account.messages import encode_defunct
+from solders.keypair import Keypair  # type: ignore
+from solders.pubkey import Pubkey  # type: ignore
+
+
+def sign_request(
+    method: str,
+    path: str,
+    body: str,
+    timestamp: int,
+    did: str,
+    private_key: str,
+) -> str:
+    """
+    Sign a request per LLD §2.1
+
+    Args:
+        method: HTTP method (GET, POST, etc.)
+        path: URL path (e.g., /v1/memory/store)
+        body: Request body (empty string for GET)
+        timestamp: Unix timestamp in milliseconds
+        did: Agent DID
+        private_key: Private key (hex string without 0x prefix)
+
+    Returns:
+        Signature (hex string)
+    """
+    # Create signature message per LLD §2.1
+    message = create_signature_message(method, path, body, timestamp, did)
+
+    # Sign message with private key
+    signature = sign_message(message, private_key, did)
+
+    return signature
+
+
+def create_signature_message(
+    method: str,
+    path: str,
+    body: str,
+    timestamp: int,
+    did: str,
+) -> str:
+    """
+    Create signature message per LLD §2.1
+    Format: METHOD\nPATH\nSHA256(body)\nX-Ts\nX-Agent-DID
+    """
+    # Calculate SHA256 of body
+    body_hash = hashlib.sha256(body.encode('utf-8')).hexdigest()
+
+    # Build message per LLD §2.1
+    message = f"{method}\n{path}\n{body_hash}\n{timestamp}\n{did}"
+
+    return message
+
+
+def sign_message(message: str, private_key: str, did: str) -> str:
+    """
+    Sign a message with private key
+    Supports both EVM (secp256k1) and Solana (ed25519) signing
+
+    Args:
+        message: Message to sign
+        private_key: Private key (hex string without 0x prefix)
+        did: Agent DID (used to determine signing algorithm)
+
+    Returns:
+        Signature (hex string without 0x prefix)
+    """
+    # Remove 0x prefix if present
+    clean_key = private_key[2:] if private_key.startswith('0x') else private_key
+
+    # Determine signing method based on DID
+    if ':evm:' in did:
+        # EVM signing using eth_account (secp256k1)
+        return sign_message_evm(message, clean_key)
+    elif ':sol:' in did:
+        # Solana signing using ed25519
+        return sign_message_solana(message, clean_key)
+    else:
+        raise ValueError(f"Unsupported DID type in: {did}")
+
+
+def sign_message_evm(message: str, private_key: str) -> str:
+    """
+    Sign message using EVM secp256k1 (eth_account)
+    """
+    try:
+        # Create account from private key
+        account = Account.from_key(f"0x{private_key}")
+
+        # Encode message for Ethereum signing
+        message_hash = encode_defunct(text=message)
+
+        # Sign the message
+        signed = account.sign_message(message_hash)
+
+        # Return signature as hex without 0x prefix
+        return signed.signature.hex()[2:]
+    except Exception as e:
+        raise ValueError(f"EVM signing failed: {str(e)}")
+
+
+def sign_message_solana(message: str, private_key: str) -> str:
+    """
+    Sign message using Solana ed25519
+    """
+    try:
+        # Convert hex private key to bytes
+        private_key_bytes = bytes.fromhex(private_key)
+
+        # Create keypair from secret key
+        # Solana keypairs are 64 bytes (32-byte secret + 32-byte public)
+        if len(private_key_bytes) == 32:
+            # If only 32 bytes, treat as seed
+            keypair = Keypair.from_seed(private_key_bytes)
+        elif len(private_key_bytes) == 64:
+            # Full keypair
+            keypair = Keypair.from_bytes(private_key_bytes)
+        else:
+            raise ValueError(f"Invalid Solana private key length: {len(private_key_bytes)} bytes")
+
+        # Sign the message
+        message_bytes = message.encode('utf-8')
+        signature = keypair.sign_message(message_bytes)
+
+        # Return signature as hex
+        return bytes(signature).hex()
+    except Exception as e:
+        raise ValueError(f"Solana signing failed: {str(e)}")
+
+
+def validate_did(did: str) -> bool:
+    """
+    Validate DID format per LLD §2.1
+    Format: did:agent:<evm|sol>:<address>
+    - EVM: did:agent:evm:0x[40 hex chars]
+    - Solana: did:agent:sol:[32-44 base58 chars]
+    """
+    # Check basic structure
+    if not did.startswith('did:agent:'):
+        return False
+
+    parts = did.split(':')
+    if len(parts) != 4:
+        return False
+
+    _, _, chain, address = parts
+
+    if chain == 'evm':
+        # EVM addresses: 0x followed by 40 hex characters
+        return bool(re.match(r'^0x[a-fA-F0-9]{40}$', address))
+    elif chain == 'sol':
+        # Solana addresses: base58 string (32-44 characters typical)
+        return bool(re.match(r'^[1-9A-HJ-NP-Za-km-z]{32,44}$', address))
+
+    return False
+
+
+def validate_timestamp(timestamp: int) -> bool:
+    """
+    Validate timestamp is within acceptable window (±300s per LLD §2.1)
+    """
+    now = int(time.time() * 1000)
+    diff = abs(now - timestamp)
+    return diff <= 300000  # 5 minutes = 300 seconds = 300,000ms
+
+
+def generate_auth_headers(
+    method: str,
+    path: str,
+    body: str,
+    did: str,
+    private_key: str,
+) -> Dict[str, str]:
+    """
+    Generate authentication headers per LLD §2.1
+
+    Args:
+        method: HTTP method
+        path: URL path
+        body: Request body (empty string for GET)
+        did: Agent DID
+        private_key: Private key (hex string)
+
+    Returns:
+        Authentication headers
+    """
+    # Validate DID format
+    if not validate_did(did):
+        raise ValueError(f"Invalid DID format: {did}")
+
+    # Generate timestamp
+    timestamp = int(time.time() * 1000)
+
+    # Validate timestamp
+    if not validate_timestamp(timestamp):
+        raise ValueError("Generated timestamp is outside acceptable window")
+
+    # Sign request
+    signature = sign_request(method, path, body, timestamp, did, private_key)
+
+    # Return headers per LLD §2.1
+    return {
+        "X-Agent-DID": did,
+        "X-Sig": signature,
+        "X-Ts": str(timestamp),
+    }
+
+
+def derive_evm_address(private_key: str) -> str:
+    """
+    Derive Ethereum address from private key
+    """
+    clean_key = private_key[2:] if private_key.startswith('0x') else private_key
+    account = Account.from_key(f"0x{clean_key}")
+    return account.address
+
+
+def derive_solana_address(private_key: str) -> str:
+    """
+    Derive Solana address from private key
+    """
+    private_key_bytes = bytes.fromhex(private_key)
+
+    if len(private_key_bytes) == 32:
+        keypair = Keypair.from_seed(private_key_bytes)
+    elif len(private_key_bytes) == 64:
+        keypair = Keypair.from_bytes(private_key_bytes)
+    else:
+        raise ValueError(f"Invalid Solana private key length: {len(private_key_bytes)} bytes")
+
+    return str(keypair.pubkey())

xache/crypto/wallet.py

@@ -0,0 +1,240 @@
+"""
+Wallet Generation Utilities
+Production-ready BIP-39 compliant wallet generation for EVM and Solana
+"""
+
+from typing import Optional, Literal
+from dataclasses import dataclass
+from mnemonic import Mnemonic
+from eth_account import Account
+from bip_utils import (
+    Bip39MnemonicGenerator,
+    Bip39SeedGenerator,
+    Bip39WordsNum,
+    Bip44,
+    Bip44Coins,
+    Bip44Changes
+)
+import nacl.signing
+import base58
+
+KeyType = Literal['evm', 'solana']
+
+
+@dataclass
+class WalletGenerationResult:
+    """Wallet generation result"""
+    did: str  # DID format: did:agent:<evm|sol>:<address>
+    address: str  # Wallet address
+    private_key: str  # Private key (hex string with 0x prefix)
+    mnemonic: str  # BIP-39 mnemonic (24 words)
+    key_type: KeyType  # Key type (evm or solana)
+
+
+@dataclass
+class WalletGenerationOptions:
+    """Wallet generation options"""
+    label: Optional[str] = None
+    index: int = 0
+
+
+class WalletGenerator:
+    """
+    Wallet Generator class
+    Provides secure, deterministic wallet generation for AI agents
+    """
+
+    @staticmethod
+    def generate(
+        key_type: KeyType,
+        options: Optional[WalletGenerationOptions] = None
+    ) -> WalletGenerationResult:
+        """
+        Generate a new wallet with random mnemonic
+
+        Args:
+            key_type: 'evm' for Ethereum/Base or 'solana' for Solana
+            options: Optional generation options
+
+        Returns:
+            Wallet generation result with DID, keys, and mnemonic
+
+        Example:
+            >>> wallet = WalletGenerator.generate('evm')
+            >>> print(wallet.did)
+            did:agent:evm:0x1234...
+        """
+        if options is None:
+            options = WalletGenerationOptions()
+
+        # Generate 24-word mnemonic (256-bit entropy)
+        mnemonic_generator = Bip39MnemonicGenerator()
+        mnemonic = mnemonic_generator.FromWordsNumber(Bip39WordsNum.WORDS_NUM_24)
+
+        return WalletGenerator.from_mnemonic(str(mnemonic), key_type, options)
+
+    @staticmethod
+    def from_mnemonic(
+        mnemonic: str,
+        key_type: KeyType,
+        options: Optional[WalletGenerationOptions] = None
+    ) -> WalletGenerationResult:
+        """
+        Generate wallet from existing mnemonic
+
+        Args:
+            mnemonic: BIP-39 mnemonic phrase (12 or 24 words)
+            key_type: 'evm' for Ethereum/Base or 'solana' for Solana
+            options: Optional generation options
+
+        Returns:
+            Wallet generation result with DID and keys
+
+        Raises:
+            ValueError: If mnemonic is invalid
+        """
+        if options is None:
+            options = WalletGenerationOptions()
+
+        # Validate mnemonic
+        mnemo = Mnemonic("english")
+        if not mnemo.check(mnemonic):
+            raise ValueError("Invalid mnemonic phrase")
+
+        if key_type == 'evm':
+            return WalletGenerator._generate_evm_wallet(mnemonic, options)
+        elif key_type == 'solana':
+            return WalletGenerator._generate_solana_wallet(mnemonic, options)
+        else:
+            raise ValueError(f"Unsupported key type: {key_type}")
+
+    @staticmethod
+    def _generate_evm_wallet(
+        mnemonic: str,
+        options: WalletGenerationOptions
+    ) -> WalletGenerationResult:
+        """Generate EVM wallet (Ethereum, Base) using BIP-44 path"""
+        # BIP-44 path: m/44'/60'/0'/0/{index}
+        seed = Bip39SeedGenerator(mnemonic).Generate()
+        bip44_ctx = Bip44.FromSeed(seed, Bip44Coins.ETHEREUM)
+
+        # Derive account
+        bip44_acc = bip44_ctx.Purpose().Coin().Account(0)
+        bip44_chg = bip44_acc.Change(Bip44Changes.CHAIN_EXT)
+        bip44_addr = bip44_chg.AddressIndex(options.index)
+
+        # Get private key
+        private_key_bytes = bip44_addr.PrivateKey().Raw().ToBytes()
+        private_key_hex = '0x' + private_key_bytes.hex()
+
+        # Create account from private key
+        account = Account.from_key(private_key_bytes)
+        address = account.address
+
+        did = f"did:agent:evm:{address}"
+
+        return WalletGenerationResult(
+            did=did,
+            address=address,
+            private_key=private_key_hex,
+            mnemonic=mnemonic,
+            key_type='evm'
+        )
+
+    @staticmethod
+    def _generate_solana_wallet(
+        mnemonic: str,
+        options: WalletGenerationOptions
+    ) -> WalletGenerationResult:
+        """Generate Solana wallet using BIP-44 path"""
+        # BIP-44 path: m/44'/501'/{index}'/0'
+        seed = Bip39SeedGenerator(mnemonic).Generate()
+        bip44_ctx = Bip44.FromSeed(seed, Bip44Coins.SOLANA)
+
+        # Derive account
+        bip44_acc = bip44_ctx.Purpose().Coin().Account(options.index)
+        bip44_chg = bip44_acc.Change(Bip44Changes.CHAIN_EXT)
+
+        # Get private key (first 32 bytes for ed25519)
+        private_key_bytes = bip44_chg.PrivateKey().Raw().ToBytes()[:32]
+        private_key_hex = '0x' + private_key_bytes.hex()
+
+        # Create ed25519 key pair
+        signing_key = nacl.signing.SigningKey(private_key_bytes)
+        verify_key = signing_key.verify_key
+
+        # Encode public key as base58
+        address = base58.b58encode(bytes(verify_key)).decode('ascii')
+
+        did = f"did:agent:sol:{address}"
+
+        return WalletGenerationResult(
+            did=did,
+            address=address,
+            private_key=private_key_hex,
+            mnemonic=mnemonic,
+            key_type='solana'
+        )
+
+    @staticmethod
+    def validate_did(did: str) -> bool:
+        """
+        Validate DID format
+
+        Args:
+            did: DID string to validate
+
+        Returns:
+            True if DID format is valid
+        """
+        import re
+
+        evm_pattern = r'^did:agent:evm:0x[a-fA-F0-9]{40}$'
+        sol_pattern = r'^did:agent:sol:[1-9A-HJ-NP-Za-km-z]{32,44}$'
+
+        return bool(re.match(evm_pattern, did) or re.match(sol_pattern, did))
+
+    @staticmethod
+    def did_to_address(did: str) -> str:
+        """
+        Extract address from DID
+
+        Args:
+            did: DID string
+
+        Returns:
+            Address extracted from DID
+
+        Raises:
+            ValueError: If DID format is invalid
+        """
+        parts = did.split(':')
+        if len(parts) != 4 or parts[0] != 'did' or parts[1] != 'agent':
+            raise ValueError('Invalid DID format')
+        return parts[3]
+
+    @staticmethod
+    def did_to_key_type(did: str) -> KeyType:
+        """
+        Extract key type from DID
+
+        Args:
+            did: DID string
+
+        Returns:
+            Key type extracted from DID
+
+        Raises:
+            ValueError: If DID format is invalid
+        """
+        parts = did.split(':')
+        if len(parts) != 4 or parts[0] != 'did' or parts[1] != 'agent':
+            raise ValueError('Invalid DID format')
+
+        key_type = parts[2]
+        if key_type == 'evm':
+            return 'evm'
+        if key_type == 'sol':
+            return 'solana'
+
+        raise ValueError(f'Invalid key type in DID: {key_type}')

xache/errors.py

@@ -0,0 +1,184 @@
+"""
+Custom exception classes for Xache SDK
+Maps to API error codes per LLD §2.1
+"""
+
+from typing import Optional, Dict, Any
+
+
+class XacheError(Exception):
+    """Base Xache error class"""
+
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        status_code: int,
+        details: Optional[Dict[str, Any]] = None,
+        request_id: Optional[str] = None,
+    ):
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.status_code = status_code
+        self.details = details or {}
+        self.request_id = request_id
+
+    def __str__(self) -> str:
+        msg = f"[{self.code}] {self.message}"
+        if self.request_id:
+            msg += f" (request_id: {self.request_id})"
+        return msg
+
+
+class UnauthenticatedError(XacheError):
+    """Authentication error (401)"""
+
+    def __init__(
+        self,
+        message: str,
+        details: Optional[Dict[str, Any]] = None,
+        request_id: Optional[str] = None,
+    ):
+        super().__init__("UNAUTHENTICATED", message, 401, details, request_id)
+
+
+class PaymentRequiredError(XacheError):
+    """Payment required error (402)"""
+
+    def __init__(
+        self,
+        message: str,
+        challenge_id: str,
+        amount: str,
+        chain_hint: str,
+        pay_to: str,
+        description: str,
+        request_id: Optional[str] = None,
+    ):
+        details = {
+            "challenge_id": challenge_id,
+            "amount": amount,
+            "chain_hint": chain_hint,
+            "pay_to": pay_to,
+            "description": description,
+        }
+        super().__init__("PAYMENT_REQUIRED", message, 402, details, request_id)
+        self.challenge_id = challenge_id
+        self.amount = amount
+        self.chain_hint = chain_hint
+        self.pay_to = pay_to
+        self.description = description
+
+
+class RateLimitedError(XacheError):
+    """Rate limited error (429)"""
+
+    def __init__(
+        self,
+        message: str,
+        reset_at: Optional[str] = None,
+        details: Optional[Dict[str, Any]] = None,
+        request_id: Optional[str] = None,
+    ):
+        error_details = details or {}
+        if reset_at:
+            error_details["reset_at"] = reset_at
+        super().__init__("RATE_LIMITED", message, 429, error_details, request_id)
+        self.reset_at = reset_at
+
+
+class BudgetExceededError(XacheError):
+    """Budget exceeded error (400)"""
+
+    def __init__(
+        self,
+        message: str,
+        details: Optional[Dict[str, Any]] = None,
+        request_id: Optional[str] = None,
+    ):
+        super().__init__("BUDGET_EXCEEDED", message, 400, details, request_id)
+
+
+class InvalidInputError(XacheError):
+    """Invalid input error (400)"""
+
+    def __init__(
+        self,
+        message: str,
+        details: Optional[Dict[str, Any]] = None,
+        request_id: Optional[str] = None,
+    ):
+        super().__init__("INVALID_INPUT", message, 400, details, request_id)
+
+
+class ConflictError(XacheError):
+    """Conflict error (409)"""
+
+    def __init__(
+        self,
+        message: str,
+        details: Optional[Dict[str, Any]] = None,
+        request_id: Optional[str] = None,
+    ):
+        super().__init__("CONFLICT", message, 409, details, request_id)
+
+
+class RetryLaterError(XacheError):
+    """Retry later error (503)"""
+
+    def __init__(
+        self,
+        message: str,
+        details: Optional[Dict[str, Any]] = None,
+        request_id: Optional[str] = None,
+    ):
+        super().__init__("RETRY_LATER", message, 503, details, request_id)
+
+
+class InternalError(XacheError):
+    """Internal server error (500)"""
+
+    def __init__(
+        self,
+        message: str,
+        details: Optional[Dict[str, Any]] = None,
+        request_id: Optional[str] = None,
+    ):
+        super().__init__("INTERNAL", message, 500, details, request_id)
+
+
+class NetworkError(Exception):
+    """Network error (not from API)"""
+
+    def __init__(self, message: str, original_error: Optional[Exception] = None):
+        super().__init__(message)
+        self.original_error = original_error
+
+
+def create_error_from_response(
+    code: str,
+    message: str,
+    status_code: int,
+    details: Optional[Dict[str, Any]] = None,
+    request_id: Optional[str] = None,
+) -> XacheError:
+    """Create appropriate error from API response"""
+    error_map = {
+        "UNAUTHENTICATED": UnauthenticatedError,
+        "RATE_LIMITED": RateLimitedError,
+        "BUDGET_EXCEEDED": BudgetExceededError,
+        "INVALID_INPUT": InvalidInputError,
+        "CONFLICT": ConflictError,
+        "RETRY_LATER": RetryLaterError,
+        "INTERNAL": InternalError,
+    }
+
+    error_class = error_map.get(code)
+    if error_class:
+        if code == "RATE_LIMITED":
+            reset_at = details.get("reset_at") if details else None
+            return error_class(message, reset_at, details, request_id)
+        return error_class(message, details, request_id)
+
+    return XacheError(code, message, status_code, details, request_id)

xache/payment/__init__.py

@@ -0,0 +1,5 @@
+"""Payment handling"""
+
+from .handler import PaymentHandler
+
+__all__ = ["PaymentHandler"]