embed-client 1.0.1.1__py3-none-any.whl → 3.1.0.0__py3-none-any.whl

embed_client/ssl_manager.py

@@ -0,0 +1,466 @@
+"""
+SSL/TLS Manager for embed-client.
+
+This module provides SSL/TLS management for the embed-client, supporting
+all security modes including HTTP, HTTPS, and mTLS. It integrates with
+mcp_security_framework when available and provides fallback implementations.
+
+Author: Vasiliy Zdanovskiy
+email: vasilyvz@gmail.com
+"""
+
+import logging
+import ssl
+import os
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Union
+
+# Try to import mcp_security_framework components
+try:
+    from mcp_security_framework.core.ssl_manager import SSLManager as FrameworkSSLManager
+    from mcp_security_framework.core.cert_manager import CertificateManager
+    from mcp_security_framework.schemas.config import SSLConfig
+    from mcp_security_framework.schemas.models import CertificateInfo
+    from mcp_security_framework.utils.cert_utils import (
+        extract_certificate_info,
+        get_certificate_expiry,
+        is_certificate_self_signed,
+        parse_certificate,
+        validate_certificate_chain
+    )
+    SECURITY_FRAMEWORK_AVAILABLE = True
+except ImportError:
+    SECURITY_FRAMEWORK_AVAILABLE = False
+    print("Warning: mcp_security_framework not available. Using fallback SSL/TLS management.")
+
+# Fallback certificate handling
+try:
+    from cryptography import x509
+    from cryptography.hazmat.primitives import serialization
+    CRYPTOGRAPHY_AVAILABLE = True
+except ImportError:
+    CRYPTOGRAPHY_AVAILABLE = False
+    print("Warning: cryptography not available. Limited SSL/TLS functionality.")
+
+
+class SSLManagerError(Exception):
+    """Raised when SSL/TLS operations fail."""
+    
+    def __init__(self, message: str, error_code: int = -32002):
+        self.message = message
+        self.error_code = error_code
+        super().__init__(self.message)
+
+
+class ClientSSLManager:
+    """
+    Client SSL/TLS Manager.
+    
+    This class provides SSL/TLS management for the embed-client,
+    supporting all security modes with integration to
+    mcp_security_framework when available.
+    """
+    
+    def __init__(self, config: Dict[str, Any]):
+        """
+        Initialize SSL/TLS manager.
+        
+        Args:
+            config: SSL/TLS configuration dictionary
+        """
+        self.config = config
+        self.logger = logging.getLogger(__name__)
+        
+        # Initialize security framework components if available
+        self.ssl_manager = None
+        self.cert_manager = None
+        
+        if SECURITY_FRAMEWORK_AVAILABLE:
+            self._initialize_security_framework()
+        else:
+            self.logger.warning("mcp_security_framework not available, using fallback SSL/TLS management")
+    
+    def _initialize_security_framework(self) -> None:
+        """Initialize mcp_security_framework components."""
+        try:
+            # Create SSL config
+            ssl_config = SSLConfig(
+                enabled=self.config.get("ssl", {}).get("enabled", False),
+                cert_file=self.config.get("ssl", {}).get("cert_file"),
+                key_file=self.config.get("ssl", {}).get("key_file"),
+                ca_cert_file=self.config.get("ssl", {}).get("ca_cert_file"),
+                verify_mode=self.config.get("ssl", {}).get("verify_mode", "CERT_REQUIRED"),
+                check_hostname=self.config.get("ssl", {}).get("check_hostname", True),
+                check_expiry=self.config.get("ssl", {}).get("check_expiry", True)
+            )
+            
+            # Initialize managers
+            self.ssl_manager = FrameworkSSLManager(ssl_config)
+            
+            self.logger.info("Security framework SSL/TLS components initialized successfully")
+            
+        except Exception as e:
+            self.logger.warning(f"Failed to initialize security framework SSL/TLS: {e}")
+            self.ssl_manager = None
+            self.cert_manager = None
+    
+    def create_client_ssl_context(self) -> Optional[ssl.SSLContext]:
+        """
+        Create SSL context for client connections.
+        
+        Returns:
+            SSL context for client connections or None if SSL is disabled
+        """
+        # Check if SSL is enabled first
+        if not self.is_ssl_enabled():
+            return None
+            
+        try:
+            # Force fallback implementation for CERT_NONE mode
+            ssl_config = self.config.get("ssl", {})
+            if ssl_config.get("verify_mode") == "CERT_NONE":
+                return self._create_client_ssl_context_fallback()
+            elif self.ssl_manager:
+                # Use security framework
+                return self.ssl_manager.create_client_context()
+            else:
+                # Fallback implementation
+                return self._create_client_ssl_context_fallback()
+                
+        except Exception as e:
+            self.logger.error(f"Failed to create client SSL context: {e}")
+            raise SSLManagerError(f"Failed to create client SSL context: {e}")
+    
+    def _create_client_ssl_context_fallback(self) -> Optional[ssl.SSLContext]:
+        """Fallback SSL context creation."""
+        ssl_config = self.config.get("ssl", {})
+        
+        if not ssl_config.get("enabled", False):
+            return None
+        
+        try:
+            # Configure verification
+            verify_mode = ssl_config.get("verify_mode", "CERT_REQUIRED")
+            check_hostname = ssl_config.get("check_hostname", True)
+            
+            # Force check_hostname=False for CERT_NONE mode
+            if verify_mode == "CERT_NONE":
+                check_hostname = False
+            
+            # Create SSL context based on verification mode
+            if verify_mode == "CERT_NONE":
+                context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+                context.check_hostname = False
+                context.verify_mode = ssl.CERT_NONE
+            else:
+                context = ssl.create_default_context()
+                context.check_hostname = check_hostname
+                if verify_mode == "CERT_OPTIONAL":
+                    context.verify_mode = ssl.CERT_OPTIONAL
+                else:  # CERT_REQUIRED
+                    context.verify_mode = ssl.CERT_REQUIRED
+            
+            # Load CA certificate if provided
+            ca_cert_file = ssl_config.get("ca_cert_file")
+            if ca_cert_file and os.path.exists(ca_cert_file):
+                context.load_verify_locations(ca_cert_file)
+            
+            # Load client certificate if provided (for mTLS)
+            cert_file = ssl_config.get("cert_file")
+            key_file = ssl_config.get("key_file")
+            if cert_file and key_file and os.path.exists(cert_file) and os.path.exists(key_file):
+                context.load_cert_chain(cert_file, key_file)
+            
+            return context
+            
+        except Exception as e:
+            raise SSLManagerError(f"Failed to create SSL context: {e}")
+    
+    def create_connector(self) -> Optional[Any]:
+        """
+        Create aiohttp connector with SSL context.
+        
+        Returns:
+            aiohttp connector with SSL context or None if SSL is disabled
+        """
+        try:
+            import aiohttp
+            
+            ssl_context = self.create_client_ssl_context()
+            if ssl_context is None:
+                return None
+            
+            return aiohttp.TCPConnector(ssl=ssl_context)
+            
+        except ImportError:
+            self.logger.error("aiohttp not available for connector creation")
+            return None
+        except Exception as e:
+            self.logger.error(f"Failed to create connector: {e}")
+            return None
+    
+    def validate_certificate(self, cert_file: str) -> Dict[str, Any]:
+        """
+        Validate certificate file.
+        
+        Args:
+            cert_file: Path to certificate file
+            
+        Returns:
+            Dictionary with validation results
+        """
+        try:
+            if self.ssl_manager and CRYPTOGRAPHY_AVAILABLE:
+                # Use security framework
+                cert_info = extract_certificate_info(cert_file)
+                return {
+                    "valid": True,
+                    "subject": str(cert_info.subject),
+                    "issuer": str(cert_info.issuer),
+                    "not_valid_before": cert_info.not_valid_before.isoformat(),
+                    "not_valid_after": cert_info.not_valid_after.isoformat(),
+                    "serial_number": str(cert_info.serial_number),
+                    "is_self_signed": is_certificate_self_signed(cert_file)
+                }
+            else:
+                # Fallback implementation
+                return self._validate_certificate_fallback(cert_file)
+                
+        except Exception as e:
+            self.logger.error(f"Certificate validation failed: {e}")
+            return {
+                "valid": False,
+                "error": str(e)
+            }
+    
+    def _validate_certificate_fallback(self, cert_file: str) -> Dict[str, Any]:
+        """Fallback certificate validation."""
+        if not CRYPTOGRAPHY_AVAILABLE:
+            return {
+                "valid": False,
+                "error": "cryptography not available for certificate validation"
+            }
+        
+        try:
+            if not os.path.exists(cert_file):
+                return {
+                    "valid": False,
+                    "error": "Certificate file not found"
+                }
+            
+            # Basic file existence and readability check
+            with open(cert_file, 'rb') as f:
+                cert_data = f.read()
+            
+            # Try to parse certificate
+            cert = x509.load_pem_x509_certificate(cert_data)
+            
+            return {
+                "valid": True,
+                "subject": str(cert.subject),
+                "issuer": str(cert.issuer),
+                "not_valid_before": cert.not_valid_before.isoformat(),
+                "not_valid_after": cert.not_valid_after.isoformat(),
+                "serial_number": str(cert.serial_number)
+            }
+            
+        except Exception as e:
+            return {
+                "valid": False,
+                "error": f"Certificate validation failed: {e}"
+            }
+    
+    def get_ssl_config(self) -> Dict[str, Any]:
+        """
+        Get current SSL configuration.
+        
+        Returns:
+            Dictionary with SSL configuration
+        """
+        return self.config.get("ssl", {})
+    
+    def is_ssl_enabled(self) -> bool:
+        """
+        Check if SSL/TLS is enabled.
+        
+        Returns:
+            True if SSL/TLS is enabled, False otherwise
+        """
+        return self.config.get("ssl", {}).get("enabled", False)
+    
+    def is_mtls_enabled(self) -> bool:
+        """
+        Check if mTLS (mutual TLS) is enabled.
+        
+        Returns:
+            True if mTLS is enabled, False otherwise
+        """
+        ssl_config = self.config.get("ssl", {})
+        return (ssl_config.get("enabled", False) and 
+                bool(ssl_config.get("cert_file")) and 
+                bool(ssl_config.get("key_file")))
+    
+    def get_certificate_info(self, cert_file: str) -> Optional[Dict[str, Any]]:
+        """
+        Get certificate information.
+        
+        Args:
+            cert_file: Path to certificate file
+            
+        Returns:
+            Dictionary with certificate information or None if not available
+        """
+        try:
+            if self.ssl_manager and CRYPTOGRAPHY_AVAILABLE:
+                # Use security framework
+                cert_info = extract_certificate_info(cert_file)
+                return {
+                    "subject": str(cert_info.subject),
+                    "issuer": str(cert_info.issuer),
+                    "not_valid_before": cert_info.not_valid_before.isoformat(),
+                    "not_valid_after": cert_info.not_valid_after.isoformat(),
+                    "serial_number": str(cert_info.serial_number),
+                    "version": cert_info.version,
+                    "signature_algorithm": str(cert_info.signature_algorithm_oid),
+                    "is_self_signed": is_certificate_self_signed(cert_file)
+                }
+            else:
+                # Fallback implementation
+                return self._get_certificate_info_fallback(cert_file)
+                
+        except Exception as e:
+            self.logger.error(f"Failed to get certificate info: {e}")
+            return None
+    
+    def _get_certificate_info_fallback(self, cert_file: str) -> Optional[Dict[str, Any]]:
+        """Fallback certificate info extraction."""
+        if not CRYPTOGRAPHY_AVAILABLE:
+            return None
+        
+        try:
+            if not os.path.exists(cert_file):
+                return None
+            
+            with open(cert_file, 'rb') as f:
+                cert_data = f.read()
+            
+            cert = x509.load_pem_x509_certificate(cert_data)
+            
+            return {
+                "subject": str(cert.subject),
+                "issuer": str(cert.issuer),
+                "not_valid_before": cert.not_valid_before.isoformat(),
+                "not_valid_after": cert.not_valid_after.isoformat(),
+                "serial_number": str(cert.serial_number),
+                "version": cert.version.name,
+                "signature_algorithm": str(cert.signature_algorithm_oid)
+            }
+            
+        except Exception as e:
+            self.logger.error(f"Failed to extract certificate info: {e}")
+            return None
+    
+    def validate_ssl_config(self) -> List[str]:
+        """
+        Validate SSL configuration.
+        
+        Returns:
+            List of validation errors
+        """
+        errors = []
+        ssl_config = self.config.get("ssl", {})
+        
+        if not ssl_config.get("enabled", False):
+            return errors  # SSL disabled, no validation needed
+        
+        # Check certificate files if mTLS is configured
+        cert_file = ssl_config.get("cert_file")
+        key_file = ssl_config.get("key_file")
+        
+        if cert_file and not os.path.exists(cert_file):
+            errors.append(f"Certificate file not found: {cert_file}")
+        
+        if key_file and not os.path.exists(key_file):
+            errors.append(f"Key file not found: {key_file}")
+        
+        # Check CA certificate if provided
+        ca_cert_file = ssl_config.get("ca_cert_file")
+        if ca_cert_file and not os.path.exists(ca_cert_file):
+            errors.append(f"CA certificate file not found: {ca_cert_file}")
+        
+        # Validate certificate if provided
+        if cert_file and os.path.exists(cert_file):
+            validation_result = self.validate_certificate(cert_file)
+            if not validation_result.get("valid", False):
+                errors.append(f"Certificate validation failed: {validation_result.get('error', 'Unknown error')}")
+        
+        return errors
+    
+    def get_supported_protocols(self) -> List[str]:
+        """
+        Get list of supported SSL/TLS protocols.
+        
+        Returns:
+            List of supported protocol names
+        """
+        protocols = []
+        
+        try:
+            # Check available protocols
+            if hasattr(ssl, 'PROTOCOL_TLSv1_2'):
+                protocols.append("TLSv1.2")
+            if hasattr(ssl, 'PROTOCOL_TLSv1_3'):
+                protocols.append("TLSv1.3")
+            if hasattr(ssl, 'PROTOCOL_TLS'):
+                protocols.append("TLS")
+            
+            # Fallback to basic protocols
+            if not protocols:
+                protocols = ["SSLv23", "TLS"]
+                
+        except Exception as e:
+            self.logger.warning(f"Failed to detect supported protocols: {e}")
+            protocols = ["TLS"]  # Basic fallback
+        
+        return protocols
+
+
+def create_ssl_manager(config: Dict[str, Any]) -> ClientSSLManager:
+    """
+    Create SSL/TLS manager from configuration.
+    
+    Args:
+        config: Configuration dictionary
+        
+    Returns:
+        ClientSSLManager instance
+    """
+    return ClientSSLManager(config)
+
+
+def create_ssl_context(config: Dict[str, Any]) -> Optional[ssl.SSLContext]:
+    """
+    Create SSL context from configuration.
+    
+    Args:
+        config: Configuration dictionary
+        
+    Returns:
+        SSL context or None if SSL is disabled
+    """
+    ssl_manager = ClientSSLManager(config)
+    return ssl_manager.create_client_ssl_context()
+
+
+def create_connector(config: Dict[str, Any]) -> Optional[Any]:
+    """
+    Create aiohttp connector from configuration.
+    
+    Args:
+        config: Configuration dictionary
+        
+    Returns:
+        aiohttp connector or None if SSL is disabled
+    """
+    ssl_manager = ClientSSLManager(config)
+    return ssl_manager.create_connector()

embed_client-3.1.0.0.dist-info/METADATA

@@ -0,0 +1,229 @@
+Metadata-Version: 2.4
+Name: embed-client
+Version: 3.1.0.0
+Summary: Async client for Embedding Service API with comprehensive authentication, SSL/TLS, and mTLS support
+Author-email: Vasiliy Zdanovskiy <vasilyvz@gmail.com>
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: aiohttp
+Requires-Dist: PyJWT>=2.0.0
+Requires-Dist: cryptography>=3.0.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-asyncio; extra == "test"
+
+# embed-client
+
+Асинхронный клиент для Embedding Service API с поддержкой всех режимов безопасности.
+
+## Возможности
+
+- ✅ **Асинхронный API** - полная поддержка async/await
+- ✅ **Все режимы безопасности** - HTTP, HTTPS, mTLS
+- ✅ **Аутентификация** - API Key, JWT, Basic Auth, Certificate
+- ✅ **SSL/TLS поддержка** - полная интеграция с mcp_security_framework
+- ✅ **Конфигурация** - файлы конфигурации, переменные окружения, аргументы
+- ✅ **Обратная совместимость** - API формат не изменился, добавлена только безопасность
+- ✅ **Типизация** - 100% type-annotated код
+- ✅ **Тестирование** - 84+ тестов с полным покрытием
+
+## Quick Start: Примеры запуска
+
+### Базовое использование
+
+**Вариант 1: через аргументы командной строки**
+
+```sh
+# HTTP без аутентификации
+python embed_client/example_async_usage.py --base-url http://localhost --port 8001
+
+# HTTP с API ключом
+python embed_client/example_async_usage.py --base-url http://localhost --port 8001 \
+  --auth-method api_key --api-key admin_key_123
+
+# HTTPS с SSL
+python embed_client/example_async_usage.py --base-url https://localhost --port 9443 \
+  --ssl-verify-mode CERT_REQUIRED
+
+# mTLS с сертификатами
+python embed_client/example_async_usage.py --base-url https://localhost --port 9443 \
+  --cert-file certs/client.crt --key-file keys/client.key --ca-cert-file certs/ca.crt
+```
+
+**Вариант 2: через переменные окружения**
+
+```sh
+export EMBED_CLIENT_BASE_URL=http://localhost
+export EMBED_CLIENT_PORT=8001
+export EMBED_CLIENT_AUTH_METHOD=api_key
+export EMBED_CLIENT_API_KEY=admin_key_123
+python embed_client/example_async_usage.py
+```
+
+**Вариант 3: через файл конфигурации**
+
+```sh
+python embed_client/example_async_usage.py --config configs/https_token.json
+```
+
+### Режимы безопасности
+
+#### 1. HTTP (без аутентификации)
+```python
+from embed_client.async_client import EmbeddingServiceAsyncClient
+
+client = EmbeddingServiceAsyncClient(
+    base_url="http://localhost",
+    port=8001
+)
+```
+
+#### 2. HTTP + Token
+```python
+from embed_client.config import ClientConfig
+
+# API Key
+config = ClientConfig.create_http_token_config(
+    "http://localhost", 8001, {"user": "api_key_123"}
+)
+
+# JWT
+config = ClientConfig.create_http_jwt_config(
+    "http://localhost", 8001, "secret", "username", "password"
+)
+
+# Basic Auth
+config = ClientConfig.create_http_basic_config(
+    "http://localhost", 8001, "username", "password"
+)
+```
+
+#### 3. HTTPS
+```python
+config = ClientConfig.create_https_config(
+    "https://localhost", 9443,
+    ca_cert_file="certs/ca.crt"
+)
+```
+
+#### 4. mTLS (взаимная аутентификация)
+```python
+config = ClientConfig.create_mtls_config(
+    "https://localhost", 9443,
+    cert_file="certs/client.crt",
+    key_file="keys/client.key",
+    ca_cert_file="certs/ca.crt"
+)
+```
+
+### Программное использование
+
+```python
+import asyncio
+from embed_client.async_client import EmbeddingServiceAsyncClient
+from embed_client.config import ClientConfig
+
+async def main():
+    # Создание конфигурации
+    config = ClientConfig.create_http_token_config(
+        "http://localhost", 8001, {"user": "api_key_123"}
+    )
+    
+    # Использование клиента
+    async with EmbeddingServiceAsyncClient.from_config(config) as client:
+        # Проверка статуса
+        print(f"Аутентификация: {client.get_auth_method()}")
+        print(f"SSL включен: {client.is_ssl_enabled()}")
+        print(f"mTLS включен: {client.is_mtls_enabled()}")
+        
+        # Выполнение запроса
+        result = await client.cmd("embed", params={"texts": ["hello world"]})
+        
+        # Извлечение данных
+        embeddings = client.extract_embeddings(result)
+        texts = client.extract_texts(result)
+        tokens = client.extract_tokens(result)
+        bm25_tokens = client.extract_bm25_tokens(result)
+        
+        print(f"Эмбеддинги: {embeddings}")
+        print(f"Тексты: {texts}")
+        print(f"Токены: {tokens}")
+        print(f"BM25 токены: {bm25_tokens}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Установка
+
+```bash
+# Установка из PyPI
+pip install embed-client
+
+# Установка в режиме разработки
+git clone <repository>
+cd embed-client
+pip install -e .
+```
+
+## Зависимости
+
+- `aiohttp` - асинхронные HTTP запросы
+- `PyJWT>=2.0.0` - JWT токены
+- `cryptography>=3.0.0` - криптография и сертификаты
+- `pydantic>=2.0.0` - валидация конфигурации
+
+## Тестирование
+
+```bash
+# Запуск всех тестов
+pytest tests/
+
+# Запуск тестов с покрытием
+pytest tests/ --cov=embed_client
+
+# Запуск конкретных тестов
+pytest tests/test_async_client.py -v
+pytest tests/test_config.py -v
+pytest tests/test_auth.py -v
+pytest tests/test_ssl_manager.py -v
+```
+
+## Документация
+
+- [Формат API и режимы безопасности](docs/api_format.md)
+- [Примеры использования](embed_client/example_async_usage.py)
+- [Примеры на русском](embed_client/example_async_usage_ru.py)
+
+## Безопасность
+
+### Рекомендации
+
+1. **Используйте HTTPS** для продакшена
+2. **Включите проверку сертификатов** (CERT_REQUIRED)
+3. **Используйте mTLS** для критически важных систем
+4. **Регулярно обновляйте сертификаты**
+5. **Храните приватные ключи в безопасном месте**
+
+### Поддерживаемые протоколы
+
+- TLS 1.2
+- TLS 1.3
+- SSL 3.0 (устаревший, не рекомендуется)
+
+## Лицензия
+
+MIT License
+
+## Автор
+
+**Vasiliy Zdanovskiy**  
+Email: vasilyvz@gmail.com
+
+---
+
+**Важно:**
+- Используйте `--base-url` (через дефис), а не `--base_url` (через подчеркивание).
+- Значение base_url должно содержать `http://` или `https://`.
+- Аргументы должны быть отдельными (через пробел), а не через `=`.