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

embed_client/auth_examples.py

@@ -0,0 +1,248 @@
+"""
+Authentication examples for embed-client.
+
+This module provides examples of how to use the authentication system
+with different authentication methods and configurations.
+
+Author: Vasiliy Zdanovskiy
+email: vasilyvz@gmail.com
+"""
+
+from typing import Dict, Any
+from embed_client.auth import ClientAuthManager, create_auth_manager, create_auth_headers
+
+
+def get_api_key_auth_example() -> Dict[str, Any]:
+    """
+    Get example configuration for API key authentication.
+    
+    Returns:
+        Configuration dictionary for API key authentication
+    """
+    return {
+        "auth": {
+            "method": "api_key",
+            "api_keys": {
+                "admin": "admin_key_123",
+                "user": "user_key_456",
+                "readonly": "readonly_key_789"
+            }
+        }
+    }
+
+
+def get_jwt_auth_example() -> Dict[str, Any]:
+    """
+    Get example configuration for JWT authentication.
+    
+    Returns:
+        Configuration dictionary for JWT authentication
+    """
+    return {
+        "auth": {
+            "method": "jwt",
+            "jwt": {
+                "username": "testuser",
+                "password": "testpass",
+                "secret": "jwt_secret_key_123",
+                "expiry_hours": 24
+            }
+        }
+    }
+
+
+def get_basic_auth_example() -> Dict[str, Any]:
+    """
+    Get example configuration for basic authentication.
+    
+    Returns:
+        Configuration dictionary for basic authentication
+    """
+    return {
+        "auth": {
+            "method": "basic",
+            "basic": {
+                "username": "testuser",
+                "password": "testpass"
+            }
+        }
+    }
+
+
+def get_certificate_auth_example() -> Dict[str, Any]:
+    """
+    Get example configuration for certificate authentication.
+    
+    Returns:
+        Configuration dictionary for certificate authentication
+    """
+    return {
+        "auth": {
+            "method": "certificate",
+            "certificate": {
+                "enabled": True,
+                "cert_file": "certs/client.crt",
+                "key_file": "keys/client.key",
+                "ca_cert_file": "certs/ca.crt"
+            }
+        }
+    }
+
+
+def demo_api_key_authentication():
+    """Demonstrate API key authentication."""
+    print("=== API Key Authentication Demo ===")
+    
+    config = get_api_key_auth_example()
+    auth_manager = create_auth_manager(config)
+    
+    # Test authentication
+    result = auth_manager.authenticate_api_key("admin_key_123")
+    print(f"Authentication result: {result.success}")
+    print(f"User ID: {result.user_id}")
+    
+    # Get headers for request
+    headers = auth_manager.get_auth_headers("api_key", api_key="admin_key_123")
+    print(f"Request headers: {headers}")
+    
+    # Validate configuration
+    errors = auth_manager.validate_auth_config()
+    print(f"Configuration errors: {errors}")
+
+
+def demo_jwt_authentication():
+    """Demonstrate JWT authentication."""
+    print("\n=== JWT Authentication Demo ===")
+    
+    config = get_jwt_auth_example()
+    auth_manager = create_auth_manager(config)
+    
+    try:
+        # Create JWT token
+        token = auth_manager.create_jwt_token("testuser", ["admin", "user"])
+        print(f"Created JWT token: {token[:50]}...")
+        
+        # Validate token
+        result = auth_manager.authenticate_jwt(token)
+        print(f"Token validation: {result.success}")
+        print(f"User ID: {result.user_id}")
+        print(f"Roles: {result.roles}")
+        
+        # Get headers for request
+        headers = auth_manager.get_auth_headers("jwt", token=token)
+        print(f"Request headers: {headers}")
+        
+    except Exception as e:
+        print(f"JWT authentication failed: {e}")
+
+
+def demo_basic_authentication():
+    """Demonstrate basic authentication."""
+    print("\n=== Basic Authentication Demo ===")
+    
+    config = get_basic_auth_example()
+    auth_manager = create_auth_manager(config)
+    
+    # Test authentication
+    result = auth_manager.authenticate_basic("testuser", "testpass")
+    print(f"Authentication result: {result.success}")
+    print(f"User ID: {result.user_id}")
+    
+    # Get headers for request
+    headers = auth_manager.get_auth_headers("basic", username="testuser", password="testpass")
+    print(f"Request headers: {headers}")
+
+
+def demo_certificate_authentication():
+    """Demonstrate certificate authentication."""
+    print("\n=== Certificate Authentication Demo ===")
+    
+    config = get_certificate_auth_example()
+    auth_manager = create_auth_manager(config)
+    
+    # Test authentication (will fail without real certificates)
+    result = auth_manager.authenticate_certificate("certs/client.crt", "keys/client.key")
+    print(f"Authentication result: {result.success}")
+    print(f"User ID: {result.user_id}")
+    print(f"Error: {result.error}")
+    
+    # Get headers for request (should be empty for certificate auth)
+    headers = auth_manager.get_auth_headers("certificate")
+    print(f"Request headers: {headers}")
+
+
+def demo_auth_headers_creation():
+    """Demonstrate creating authentication headers."""
+    print("\n=== Authentication Headers Demo ===")
+    
+    # API Key headers
+    headers = create_auth_headers("api_key", api_key="test_key")
+    print(f"API Key headers: {headers}")
+    
+    # JWT headers
+    headers = create_auth_headers("jwt", token="test_token")
+    print(f"JWT headers: {headers}")
+    
+    # Basic auth headers
+    headers = create_auth_headers("basic", username="user", password="pass")
+    print(f"Basic auth headers: {headers}")
+    
+    # Certificate headers (should be empty)
+    headers = create_auth_headers("certificate")
+    print(f"Certificate headers: {headers}")
+
+
+def demo_configuration_validation():
+    """Demonstrate configuration validation."""
+    print("\n=== Configuration Validation Demo ===")
+    
+    # Valid configuration
+    valid_config = get_api_key_auth_example()
+    auth_manager = create_auth_manager(valid_config)
+    errors = auth_manager.validate_auth_config()
+    print(f"Valid config errors: {errors}")
+    
+    # Invalid configuration
+    invalid_config = {
+        "auth": {
+            "method": "api_key",
+            "api_keys": {}  # Empty API keys
+        }
+    }
+    auth_manager = create_auth_manager(invalid_config)
+    errors = auth_manager.validate_auth_config()
+    print(f"Invalid config errors: {errors}")
+
+
+def demo_supported_methods():
+    """Demonstrate getting supported authentication methods."""
+    print("\n=== Supported Methods Demo ===")
+    
+    config = {"auth": {"method": "api_key"}}
+    auth_manager = create_auth_manager(config)
+    
+    methods = auth_manager.get_supported_methods()
+    print(f"Supported authentication methods: {methods}")
+    
+    print(f"Authentication enabled: {auth_manager.is_auth_enabled()}")
+    print(f"Current auth method: {auth_manager.get_auth_method()}")
+
+
+def run_all_demos():
+    """Run all authentication demos."""
+    print("🚀 Authentication System Examples")
+    print("=" * 50)
+    
+    demo_api_key_authentication()
+    demo_jwt_authentication()
+    demo_basic_authentication()
+    demo_certificate_authentication()
+    demo_auth_headers_creation()
+    demo_configuration_validation()
+    demo_supported_methods()
+    
+    print("\n✅ All authentication demos completed!")
+
+
+if __name__ == "__main__":
+    run_all_demos()

embed_client/client_factory.py

@@ -0,0 +1,396 @@
+"""
+Client Factory for Embedding Service
+
+Author: Vasiliy Zdanovskiy
+email: vasilyvz@gmail.com
+
+This module provides a factory for creating EmbeddingServiceAsyncClient instances
+with automatic security mode detection and configuration.
+"""
+
+import os
+import ssl
+from typing import Optional, Dict, Any, Union, Tuple
+from urllib.parse import urlparse
+
+from .async_client import EmbeddingServiceAsyncClient
+from .config import ClientConfig
+from .auth import create_auth_manager
+from .ssl_manager import create_ssl_manager
+
+
+class SecurityMode:
+    """Security mode constants."""
+    HTTP = "http"
+    HTTP_TOKEN = "http_token"
+    HTTPS = "https"
+    HTTPS_TOKEN = "https_token"
+    MTLS = "mtls"
+    MTLS_ROLES = "mtls_roles"
+
+
+class ClientFactory:
+    """
+    Factory for creating EmbeddingServiceAsyncClient instances with automatic
+    security mode detection and configuration.
+    
+    Supports all 6 security modes:
+    1. HTTP - plain HTTP without authentication
+    2. HTTP + Token - HTTP with API Key, JWT, or Basic authentication
+    3. HTTPS - HTTPS with server certificate verification
+    4. HTTPS + Token - HTTPS with server certificates + authentication
+    5. mTLS - mutual TLS with client and server certificates
+    6. mTLS + Roles - mTLS with role-based access control
+    """
+    
+    @staticmethod
+    def detect_security_mode(
+        base_url: str,
+        auth_method: Optional[str] = None,
+        ssl_enabled: Optional[bool] = None,
+        cert_file: Optional[str] = None,
+        key_file: Optional[str] = None,
+        **kwargs
+    ) -> str:
+        """
+        Automatically detect security mode based on provided parameters.
+        
+        Args:
+            base_url: Server base URL
+            auth_method: Authentication method (none, api_key, jwt, basic, certificate)
+            ssl_enabled: Whether SSL is enabled
+            cert_file: Client certificate file path
+            key_file: Client private key file path
+            **kwargs: Additional parameters
+            
+        Returns:
+            Detected security mode string
+        """
+        # Parse URL to determine protocol
+        parsed_url = urlparse(base_url)
+        is_https = parsed_url.scheme.lower() == 'https'
+        
+        # Determine SSL status
+        if ssl_enabled is None:
+            ssl_enabled = is_https
+        else:
+            ssl_enabled = bool(ssl_enabled)
+        
+        # Check for mTLS (client certificates)
+        has_client_cert = bool(cert_file and key_file)
+        
+        # Check for authentication
+        has_auth = auth_method and auth_method != 'none'
+        
+        # Determine security mode
+        if ssl_enabled and has_client_cert:
+            # Check for role-based access (additional certificate attributes)
+            if kwargs.get('roles') or kwargs.get('role_attributes'):
+                return SecurityMode.MTLS_ROLES
+            else:
+                return SecurityMode.MTLS
+        elif ssl_enabled and has_auth:
+            return SecurityMode.HTTPS_TOKEN
+        elif ssl_enabled:
+            return SecurityMode.HTTPS
+        elif has_auth:
+            return SecurityMode.HTTP_TOKEN
+        else:
+            return SecurityMode.HTTP
+    
+    @staticmethod
+    def create_client(
+        base_url: str,
+        port: int = 8001,
+        auth_method: Optional[str] = None,
+        ssl_enabled: Optional[bool] = None,
+        **kwargs
+    ) -> EmbeddingServiceAsyncClient:
+        """
+        Create a client with automatic security mode detection.
+        
+        Args:
+            base_url: Server base URL
+            port: Server port
+            auth_method: Authentication method
+            ssl_enabled: Whether SSL is enabled
+            **kwargs: Additional configuration parameters
+            
+        Returns:
+            Configured EmbeddingServiceAsyncClient instance
+        """
+        # Detect security mode
+        security_mode = ClientFactory.detect_security_mode(
+            base_url, auth_method, ssl_enabled, **kwargs
+        )
+        
+        # Create configuration based on detected mode
+        config_dict = ClientFactory._create_config_for_mode(
+            security_mode, base_url, port, auth_method, ssl_enabled, **kwargs
+        )
+        
+        # Create and return client
+        return EmbeddingServiceAsyncClient(config_dict=config_dict)
+    
+    @staticmethod
+    def _create_config_for_mode(
+        security_mode: str,
+        base_url: str,
+        port: int,
+        auth_method: Optional[str],
+        ssl_enabled: Optional[bool],
+        **kwargs
+    ) -> Dict[str, Any]:
+        """
+        Create configuration dictionary for specific security mode.
+        
+        Args:
+            security_mode: Detected security mode
+            base_url: Server base URL
+            port: Server port
+            auth_method: Authentication method
+            ssl_enabled: Whether SSL is enabled
+            **kwargs: Additional parameters
+            
+        Returns:
+            Configuration dictionary
+        """
+        config_dict = {
+            "server": {
+                "host": base_url,
+                "port": port
+            },
+            "client": {
+                "timeout": kwargs.get("timeout", 30.0)
+            }
+        }
+        
+        # Configure authentication
+        if security_mode in [SecurityMode.HTTP_TOKEN, SecurityMode.HTTPS_TOKEN]:
+            config_dict["auth"] = ClientFactory._create_auth_config(auth_method, **kwargs)
+        elif security_mode in [SecurityMode.MTLS, SecurityMode.MTLS_ROLES] and auth_method and auth_method != "none":
+            config_dict["auth"] = ClientFactory._create_auth_config(auth_method, **kwargs)
+        
+        # Configure SSL/TLS
+        if security_mode in [SecurityMode.HTTPS, SecurityMode.HTTPS_TOKEN, SecurityMode.MTLS, SecurityMode.MTLS_ROLES]:
+            config_dict["ssl"] = ClientFactory._create_ssl_config(security_mode, ssl_enabled, **kwargs)
+        
+        return config_dict
+    
+    @staticmethod
+    def _create_auth_config(auth_method: str, **kwargs) -> Dict[str, Any]:
+        """Create authentication configuration."""
+        auth_config = {"method": auth_method}
+        
+        if auth_method == "api_key":
+            api_key = kwargs.get("api_key") or os.environ.get("EMBED_CLIENT_API_KEY")
+            if api_key:
+                auth_config["api_keys"] = {"user": api_key}
+                if kwargs.get("api_key_header"):
+                    auth_config["api_key_header"] = kwargs["api_key_header"]
+        
+        elif auth_method == "jwt":
+            jwt_secret = kwargs.get("jwt_secret") or os.environ.get("EMBED_CLIENT_JWT_SECRET")
+            jwt_username = kwargs.get("jwt_username") or os.environ.get("EMBED_CLIENT_JWT_USERNAME")
+            jwt_password = kwargs.get("jwt_password") or os.environ.get("EMBED_CLIENT_JWT_PASSWORD")
+            
+            if jwt_secret and jwt_username and jwt_password:
+                auth_config["jwt"] = {
+                    "secret": jwt_secret,
+                    "username": jwt_username,
+                    "password": jwt_password
+                }
+                if kwargs.get("jwt_expiry"):
+                    auth_config["jwt"]["expiry"] = kwargs["jwt_expiry"]
+        
+        elif auth_method == "basic":
+            username = kwargs.get("username") or os.environ.get("EMBED_CLIENT_USERNAME")
+            password = kwargs.get("password") or os.environ.get("EMBED_CLIENT_PASSWORD")
+            
+            if username and password:
+                auth_config["basic"] = {
+                    "username": username,
+                    "password": password
+                }
+        
+        elif auth_method == "certificate":
+            cert_file = kwargs.get("cert_file") or os.environ.get("EMBED_CLIENT_CERT_FILE")
+            key_file = kwargs.get("key_file") or os.environ.get("EMBED_CLIENT_KEY_FILE")
+            
+            if cert_file and key_file:
+                auth_config["certificate"] = {
+                    "cert_file": cert_file,
+                    "key_file": key_file
+                }
+        
+        return auth_config
+    
+    @staticmethod
+    def _create_ssl_config(security_mode: str, ssl_enabled: bool, **kwargs) -> Dict[str, Any]:
+        """Create SSL/TLS configuration."""
+        ssl_config = {
+            "enabled": ssl_enabled,
+            "verify_mode": kwargs.get("verify_mode", "CERT_REQUIRED"),
+            "check_hostname": kwargs.get("check_hostname", True),
+            "check_expiry": kwargs.get("check_expiry", True)
+        }
+        
+        # Add CA certificate if provided
+        ca_cert_file = kwargs.get("ca_cert_file") or os.environ.get("EMBED_CLIENT_CA_CERT_FILE")
+        if ca_cert_file:
+            ssl_config["ca_cert_file"] = ca_cert_file
+        
+        # Add client certificates for mTLS
+        if security_mode in [SecurityMode.MTLS, SecurityMode.MTLS_ROLES]:
+            cert_file = kwargs.get("cert_file") or os.environ.get("EMBED_CLIENT_CERT_FILE")
+            key_file = kwargs.get("key_file") or os.environ.get("EMBED_CLIENT_KEY_FILE")
+            
+            if cert_file:
+                ssl_config["cert_file"] = cert_file
+            if key_file:
+                ssl_config["key_file"] = key_file
+        
+        return ssl_config
+    
+    @staticmethod
+    def create_http_client(base_url: str, port: int = 8001, **kwargs) -> EmbeddingServiceAsyncClient:
+        """Create HTTP client (no authentication, no SSL)."""
+        return ClientFactory.create_client(
+            base_url, port, auth_method="none", ssl_enabled=False, **kwargs
+        )
+    
+    @staticmethod
+    def create_http_token_client(
+        base_url: str,
+        port: int = 8001,
+        auth_method: str = "api_key",
+        **kwargs
+    ) -> EmbeddingServiceAsyncClient:
+        """Create HTTP client with authentication."""
+        return ClientFactory.create_client(
+            base_url, port, auth_method=auth_method, ssl_enabled=False, **kwargs
+        )
+    
+    @staticmethod
+    def create_https_client(
+        base_url: str,
+        port: int = 8001,
+        **kwargs
+    ) -> EmbeddingServiceAsyncClient:
+        """Create HTTPS client (no authentication, with SSL)."""
+        return ClientFactory.create_client(
+            base_url, port, auth_method="none", ssl_enabled=True, **kwargs
+        )
+    
+    @staticmethod
+    def create_https_token_client(
+        base_url: str,
+        port: int = 8001,
+        auth_method: str = "api_key",
+        **kwargs
+    ) -> EmbeddingServiceAsyncClient:
+        """Create HTTPS client with authentication."""
+        return ClientFactory.create_client(
+            base_url, port, auth_method=auth_method, ssl_enabled=True, **kwargs
+        )
+    
+    @staticmethod
+    def create_mtls_client(
+        base_url: str,
+        cert_file: str,
+        key_file: str,
+        port: int = 8001,
+        auth_method: Optional[str] = None,
+        **kwargs
+    ) -> EmbeddingServiceAsyncClient:
+        """Create mTLS client with client certificates."""
+        return ClientFactory.create_client(
+            base_url, port, auth_method=auth_method, ssl_enabled=True,
+            cert_file=cert_file, key_file=key_file, **kwargs
+        )
+    
+    @staticmethod
+    def create_mtls_roles_client(
+        base_url: str,
+        cert_file: str,
+        key_file: str,
+        port: int = 8001,
+        roles: Optional[list] = None,
+        role_attributes: Optional[dict] = None,
+        auth_method: Optional[str] = None,
+        **kwargs
+    ) -> EmbeddingServiceAsyncClient:
+        """Create mTLS client with role-based access control."""
+        return ClientFactory.create_client(
+            base_url, port, auth_method=auth_method, ssl_enabled=True,
+            cert_file=cert_file, key_file=key_file,
+            roles=roles, role_attributes=role_attributes, **kwargs
+        )
+    
+    @staticmethod
+    def from_config_file(config_path: str) -> EmbeddingServiceAsyncClient:
+        """Create client from configuration file."""
+        config = ClientConfig()
+        config.load_config_file(config_path)
+        return EmbeddingServiceAsyncClient.from_config(config)
+    
+    @staticmethod
+    def from_environment() -> EmbeddingServiceAsyncClient:
+        """Create client from environment variables."""
+        base_url = os.environ.get("EMBED_CLIENT_BASE_URL", "http://localhost")
+        port = int(os.environ.get("EMBED_CLIENT_PORT", "8001"))
+        auth_method = os.environ.get("EMBED_CLIENT_AUTH_METHOD", "none")
+        
+        # Check if SSL should be enabled
+        ssl_enabled = os.environ.get("EMBED_CLIENT_SSL_ENABLED", "").lower() in ["true", "1", "yes"]
+        if not ssl_enabled and base_url.startswith("https://"):
+            ssl_enabled = True
+        
+        return ClientFactory.create_client(
+            base_url, port, auth_method=auth_method, ssl_enabled=ssl_enabled
+        )
+
+
+# Convenience functions for common use cases
+def create_client(
+    base_url: str,
+    port: int = 8001,
+    auth_method: Optional[str] = None,
+    ssl_enabled: Optional[bool] = None,
+    **kwargs
+) -> EmbeddingServiceAsyncClient:
+    """
+    Create a client with automatic security mode detection.
+    
+    This is a convenience function that delegates to ClientFactory.create_client().
+    """
+    return ClientFactory.create_client(base_url, port, auth_method, ssl_enabled, **kwargs)
+
+
+def create_client_from_config(config_path: str) -> EmbeddingServiceAsyncClient:
+    """Create client from configuration file."""
+    return ClientFactory.from_config_file(config_path)
+
+
+def create_client_from_env() -> EmbeddingServiceAsyncClient:
+    """Create client from environment variables."""
+    return ClientFactory.from_environment()
+
+
+# Security mode detection function
+def detect_security_mode(
+    base_url: str,
+    auth_method: Optional[str] = None,
+    ssl_enabled: Optional[bool] = None,
+    cert_file: Optional[str] = None,
+    key_file: Optional[str] = None,
+    **kwargs
+) -> str:
+    """
+    Detect security mode based on provided parameters.
+    
+    This is a convenience function that delegates to ClientFactory.detect_security_mode().
+    """
+    return ClientFactory.detect_security_mode(
+        base_url, auth_method, ssl_enabled, cert_file, key_file, **kwargs
+    )