miso-client 0.1.0__py3-none-any.whl

miso_client/models/config.py

@@ -0,0 +1,174 @@
+"""
+Configuration types for MisoClient SDK.
+
+This module contains Pydantic models that define the configuration structure
+and data types used throughout the MisoClient SDK.
+"""
+
+from typing import Optional, Dict, Any, List, Literal
+from pydantic import BaseModel, Field
+
+
+class RedisConfig(BaseModel):
+    """Redis connection configuration."""
+    
+    host: str = Field(..., description="Redis host")
+    port: int = Field(default=6379, description="Redis port")
+    password: Optional[str] = Field(default=None, description="Redis password")
+    db: int = Field(default=0, description="Redis database number")
+    key_prefix: str = Field(default="miso:", description="Key prefix for Redis keys")
+
+
+class MisoClientConfig(BaseModel):
+    """Main MisoClient configuration.
+    
+    Required fields:
+    - controller_url: Miso Controller base URL
+    - client_id: Client identifier for authentication
+    - client_secret: Client secret for authentication
+    
+    Optional fields:
+    - redis: Redis configuration for caching
+    - log_level: Logging level (debug, info, warn, error)
+    - cache: Cache TTL settings for roles and permissions
+    """
+    
+    controller_url: str = Field(..., description="Miso Controller base URL")
+    client_id: str = Field(..., description="Client identifier for authentication")
+    client_secret: str = Field(..., description="Client secret for authentication")
+    redis: Optional[RedisConfig] = Field(default=None, description="Optional Redis configuration")
+    log_level: Literal["debug", "info", "warn", "error"] = Field(
+        default="info", 
+        description="Log level"
+    )
+    cache: Optional[Dict[str, int]] = Field(
+        default=None,
+        description="Cache TTL settings: permission_ttl, role_ttl (default: 900 seconds)"
+    )
+    
+    @property
+    def role_ttl(self) -> int:
+        """Get role cache TTL in seconds."""
+        if self.cache and "role_ttl" in self.cache:
+            return self.cache["role_ttl"]
+        return self.cache.get("roleTTL", 900) if self.cache else 900  # 15 minutes default
+    
+    @property
+    def permission_ttl(self) -> int:
+        """Get permission cache TTL in seconds."""
+        if self.cache and "permission_ttl" in self.cache:
+            return self.cache["permission_ttl"]
+        return self.cache.get("permissionTTL", 900) if self.cache else 900  # 15 minutes default
+
+
+class UserInfo(BaseModel):
+    """User information from token validation."""
+    
+    id: str = Field(..., description="User ID")
+    username: str = Field(..., description="Username")
+    email: Optional[str] = Field(default=None, description="User email")
+    firstName: Optional[str] = Field(default=None, alias="first_name", description="First name")
+    lastName: Optional[str] = Field(default=None, alias="last_name", description="Last name")
+    roles: Optional[List[str]] = Field(default=None, description="User roles")
+    
+    class Config:
+        populate_by_name = True  # Allow both snake_case and camelCase
+
+
+class AuthResult(BaseModel):
+    """Authentication result."""
+    
+    authenticated: bool = Field(..., description="Whether authentication was successful")
+    user: Optional[UserInfo] = Field(default=None, description="User information if authenticated")
+    error: Optional[str] = Field(default=None, description="Error message if authentication failed")
+
+
+class LogEntry(BaseModel):
+    """Log entry structure."""
+    
+    timestamp: str = Field(..., description="ISO timestamp")
+    level: Literal["error", "audit", "info", "debug"] = Field(..., description="Log level")
+    environment: str = Field(..., description="Environment name (extracted by backend)")
+    application: str = Field(..., description="Application identifier (clientId)")
+    applicationId: Optional[str] = Field(default=None, alias="application_id", description="Application ID")
+    userId: Optional[str] = Field(default=None, alias="user_id", description="User ID if available")
+    message: str = Field(..., description="Log message")
+    context: Optional[Dict[str, Any]] = Field(default=None, description="Additional context")
+    correlationId: Optional[str] = Field(default=None, alias="correlation_id", description="Correlation ID for tracing")
+    requestId: Optional[str] = Field(default=None, alias="request_id", description="Request ID")
+    sessionId: Optional[str] = Field(default=None, alias="session_id", description="Session ID")
+    stackTrace: Optional[str] = Field(default=None, alias="stack_trace", description="Stack trace for errors")
+    ipAddress: Optional[str] = Field(default=None, alias="ip_address", description="IP address")
+    userAgent: Optional[str] = Field(default=None, alias="user_agent", description="User agent")
+    hostname: Optional[str] = Field(default=None, description="Hostname")
+    
+    class Config:
+        populate_by_name = True
+
+
+class RoleResult(BaseModel):
+    """Role query result."""
+    
+    userId: str = Field(..., alias="user_id", description="User ID")
+    roles: List[str] = Field(..., description="List of user roles")
+    environment: str = Field(..., description="Environment name")
+    application: str = Field(..., description="Application name")
+    
+    class Config:
+        populate_by_name = True
+
+
+class PermissionResult(BaseModel):
+    """Permission query result."""
+    
+    userId: str = Field(..., alias="user_id", description="User ID")
+    permissions: List[str] = Field(..., description="List of user permissions")
+    environment: str = Field(..., description="Environment name")
+    application: str = Field(..., description="Application name")
+    
+    class Config:
+        populate_by_name = True
+
+
+class ClientTokenResponse(BaseModel):
+    """Client token response."""
+    
+    success: bool = Field(..., description="Whether token request was successful")
+    token: str = Field(..., description="Client token")
+    expiresIn: int = Field(..., alias="expires_in", description="Token expiration in seconds")
+    expiresAt: str = Field(..., alias="expires_at", description="Token expiration ISO timestamp")
+    
+    class Config:
+        populate_by_name = True
+
+
+class PerformanceMetrics(BaseModel):
+    """Performance metrics for logging."""
+    
+    startTime: int = Field(..., alias="start_time", description="Start time in milliseconds")
+    endTime: Optional[int] = Field(default=None, alias="end_time", description="End time in milliseconds")
+    duration: Optional[int] = Field(default=None, description="Duration in milliseconds")
+    memoryUsage: Optional[Dict[str, int]] = Field(
+        default=None, 
+        alias="memory_usage",
+        description="Memory usage metrics (rss, heapTotal, heapUsed, external, arrayBuffers)"
+    )
+    
+    class Config:
+        populate_by_name = True
+
+
+class ClientLoggingOptions(BaseModel):
+    """Options for client logging."""
+    
+    applicationId: Optional[str] = Field(default=None, alias="application_id", description="Application ID")
+    userId: Optional[str] = Field(default=None, alias="user_id", description="User ID")
+    correlationId: Optional[str] = Field(default=None, alias="correlation_id", description="Correlation ID")
+    requestId: Optional[str] = Field(default=None, alias="request_id", description="Request ID")
+    sessionId: Optional[str] = Field(default=None, alias="session_id", description="Session ID")
+    token: Optional[str] = Field(default=None, description="JWT token for context extraction")
+    maskSensitiveData: Optional[bool] = Field(default=None, alias="mask_sensitive_data", description="Enable data masking")
+    performanceMetrics: Optional[bool] = Field(default=None, alias="performance_metrics", description="Include performance metrics")
+    
+    class Config:
+        populate_by_name = True

miso_client/services/__init__.py

@@ -0,0 +1,20 @@
+"""Service implementations for MisoClient SDK."""
+
+from .auth import AuthService
+from .role import RoleService
+from .permission import PermissionService
+from .logger import LoggerService, LoggerChain
+from .redis import RedisService
+from .encryption import EncryptionService
+from .cache import CacheService
+
+__all__ = [
+    "AuthService",
+    "RoleService",
+    "PermissionService",
+    "LoggerService",
+    "LoggerChain",
+    "RedisService",
+    "EncryptionService",
+    "CacheService",
+]

miso_client/services/auth.py

@@ -0,0 +1,160 @@
+"""
+Authentication service for token validation and user management.
+
+This module handles authentication operations including client token management,
+token validation, user information retrieval, and logout functionality.
+"""
+
+from typing import Optional
+from ..models.config import UserInfo, AuthResult
+from ..services.redis import RedisService
+from ..utils.http_client import HttpClient
+
+
+class AuthService:
+    """Authentication service for token validation and user management."""
+    
+    def __init__(self, http_client: HttpClient, redis: RedisService):
+        """
+        Initialize authentication service.
+        
+        Args:
+            http_client: HTTP client instance
+            redis: Redis service instance
+        """
+        self.config = http_client.config
+        self.http_client = http_client
+        self.redis = redis
+    
+    async def get_environment_token(self) -> str:
+        """
+        Get environment token using client credentials.
+        
+        This is called automatically by HttpClient, but can be called manually if needed.
+        
+        Returns:
+            Client token string
+            
+        Raises:
+            AuthenticationError: If token fetch fails
+        """
+        return await self.http_client.get_environment_token()
+    
+    def login(self, redirect_uri: str) -> str:
+        """
+        Initiate login flow by redirecting to controller.
+        
+        Returns the login URL for browser redirect or manual navigation.
+        Backend will extract environment and application from client token.
+        
+        Args:
+            redirect_uri: URI to redirect to after successful login
+            
+        Returns:
+            Login URL string
+        """
+        return f"{self.config.controller_url}/api/auth/login?redirect={redirect_uri}"
+    
+    async def validate_token(self, token: str) -> bool:
+        """
+        Validate token with controller.
+        
+        Args:
+            token: JWT token to validate
+            
+        Returns:
+            True if token is valid, False otherwise
+        """
+        try:
+            result = await self.http_client.authenticated_request(
+                "POST",
+                "/api/auth/validate",  # Backend knows app/env from client token
+                token
+            )
+            
+            auth_result = AuthResult(**result)
+            return auth_result.authenticated
+            
+        except Exception:
+            # Token validation failed, return false
+            return False
+    
+    async def get_user(self, token: str) -> Optional[UserInfo]:
+        """
+        Get user information from token.
+        
+        Args:
+            token: JWT token
+            
+        Returns:
+            UserInfo if token is valid, None otherwise
+        """
+        try:
+            result = await self.http_client.authenticated_request(
+                "POST",
+                "/api/auth/validate",
+                token
+            )
+            
+            auth_result = AuthResult(**result)
+            
+            if auth_result.authenticated and auth_result.user:
+                return auth_result.user
+            
+            return None
+            
+        except Exception:
+            # Failed to get user info, return null
+            return None
+    
+    async def get_user_info(self, token: str) -> Optional[UserInfo]:
+        """
+        Get user information from GET /api/auth/user endpoint.
+        
+        Args:
+            token: JWT token
+            
+        Returns:
+            UserInfo if token is valid, None otherwise
+        """
+        try:
+            user_data = await self.http_client.authenticated_request(
+                "GET",
+                "/api/auth/user",
+                token
+            )
+            
+            return UserInfo(**user_data)
+            
+        except Exception:
+            # Failed to get user info, return None
+            return None
+    
+    async def logout(self) -> None:
+        """
+        Logout user.
+        
+        Backend extracts app/env from client token (no body needed).
+        
+        Raises:
+            MisoClientError: If logout fails
+        """
+        try:
+            # Backend extracts app/env from client token
+            await self.http_client.request("POST", "/api/auth/logout")
+        except Exception as e:
+            # Logout failed, re-raise error for application to handle
+            from ..errors import MisoClientError
+            raise MisoClientError(f"Logout failed: {str(e)}")
+    
+    async def is_authenticated(self, token: str) -> bool:
+        """
+        Check if user is authenticated (has valid token).
+        
+        Args:
+            token: JWT token
+            
+        Returns:
+            True if user is authenticated, False otherwise
+        """
+        return await self.validate_token(token)

miso_client/services/cache.py

@@ -0,0 +1,204 @@
+"""
+Cache service with Redis support and in-memory TTL fallback.
+
+This module provides a generic caching service that can be used anywhere.
+It supports Redis-backed caching when available, with automatic fallback to
+in-memory TTL-based caching when Redis is unavailable.
+"""
+
+import json
+import time
+from typing import Any, Optional, Dict, Tuple
+from ..services.redis import RedisService
+
+
+class CacheService:
+    """Cache service with Redis and in-memory TTL fallback."""
+    
+    def __init__(self, redis: Optional[RedisService] = None):
+        """
+        Initialize cache service.
+        
+        Args:
+            redis: Optional RedisService instance. If provided, Redis will be used
+                  as primary cache with in-memory as fallback. If None, only
+                  in-memory caching is used.
+        """
+        self.redis = redis
+        # In-memory cache: {key: (value, expiration_timestamp)}
+        self._memory_cache: Dict[str, Tuple[Any, float]] = {}
+        # Cleanup threshold: clean expired entries if cache exceeds this size
+        self._cleanup_threshold = 1000
+    
+    def _is_expired(self, expiration: float) -> bool:
+        """Check if entry has expired."""
+        return time.time() > expiration
+    
+    def _cleanup_expired(self) -> None:
+        """Remove expired entries from memory cache."""
+        if len(self._memory_cache) <= self._cleanup_threshold:
+            return
+        
+        expired_keys = [
+            key for key, (_, expiration) in self._memory_cache.items()
+            if self._is_expired(expiration)
+        ]
+        
+        for key in expired_keys:
+            del self._memory_cache[key]
+    
+    def _serialize_value(self, value: Any) -> str:
+        """
+        Serialize value to JSON string.
+        
+        Args:
+            value: Value to serialize (can be any JSON-serializable type)
+            
+        Returns:
+            JSON string representation
+        """
+        # For primitive types (str, int, float, bool, None), return as-is or simple string
+        if isinstance(value, (str, int, float, bool)) or value is None:
+            if isinstance(value, str):
+                return value
+            return json.dumps(value)
+        
+        # For complex types, use JSON serialization with a marker
+        return json.dumps({"__cached_value__": value})
+    
+    def _deserialize_value(self, value_str: str) -> Any:
+        """
+        Deserialize JSON string back to original value.
+        
+        Args:
+            value_str: JSON string to deserialize
+            
+        Returns:
+            Deserialized value
+        """
+        if not value_str:
+            return None
+        
+        try:
+            # Try to parse as JSON
+            parsed = json.loads(value_str)
+            # Check if it's our wrapped format
+            if isinstance(parsed, dict) and "__cached_value__" in parsed:
+                return parsed["__cached_value__"]
+            # Otherwise return as-is (could be a string or other JSON value)
+            return parsed
+        except (json.JSONDecodeError, TypeError):
+            # If JSON parsing fails, assume it's a plain string
+            return value_str
+    
+    async def get(self, key: str) -> Optional[Any]:
+        """
+        Get cached value.
+        
+        Checks Redis first (if available), then falls back to in-memory cache.
+        
+        Args:
+            key: Cache key
+            
+        Returns:
+            Cached value if found, None otherwise
+        """
+        # Try Redis first if available and connected
+        if self.redis and self.redis.is_connected():
+            try:
+                cached_value = await self.redis.get(key)
+                if cached_value is not None:
+                    return self._deserialize_value(cached_value)
+            except Exception:
+                # Redis operation failed, fall through to memory cache
+                pass
+        
+        # Fallback to in-memory cache
+        if key in self._memory_cache:
+            value, expiration = self._memory_cache[key]
+            if not self._is_expired(expiration):
+                return value
+            else:
+                # Entry expired, remove it
+                del self._memory_cache[key]
+        
+        return None
+    
+    async def set(self, key: str, value: Any, ttl: int) -> bool:
+        """
+        Set cached value with TTL.
+        
+        Stores in both Redis (if available) and in-memory cache.
+        
+        Args:
+            key: Cache key
+            value: Value to cache (any JSON-serializable type)
+            ttl: Time to live in seconds
+            
+        Returns:
+            True if successful, False otherwise
+        """
+        serialized_value = self._serialize_value(value)
+        success = False
+        
+        # Store in Redis if available
+        if self.redis and self.redis.is_connected():
+            try:
+                success = await self.redis.set(key, serialized_value, ttl)
+            except Exception:
+                # Redis operation failed, continue to memory cache
+                pass
+        
+        # Also store in memory cache
+        expiration = time.time() + ttl
+        self._memory_cache[key] = (value, expiration)
+        
+        # Cleanup expired entries periodically
+        self._cleanup_expired()
+        
+        return success or True  # Return True if at least memory cache succeeded
+    
+    async def delete(self, key: str) -> bool:
+        """
+        Delete cached value.
+        
+        Deletes from both Redis (if available) and in-memory cache.
+        
+        Args:
+            key: Cache key
+            
+        Returns:
+            True if deleted from at least one cache, False otherwise
+        """
+        deleted = False
+        
+        # Delete from Redis if available
+        if self.redis and self.redis.is_connected():
+            try:
+                deleted = await self.redis.delete(key)
+            except Exception:
+                pass
+        
+        # Delete from memory cache
+        if key in self._memory_cache:
+            del self._memory_cache[key]
+            deleted = True
+        
+        return deleted
+    
+    async def clear(self) -> None:
+        """
+        Clear all cached values.
+        
+        Clears both Redis (if available) and in-memory cache.
+        Note: Redis clear operation only clears keys with the configured prefix,
+        not the entire Redis database.
+        """
+        # Clear memory cache
+        self._memory_cache.clear()
+        
+        # For Redis, we would need to delete all keys with the prefix
+        # This is more complex and potentially dangerous, so we'll skip it
+        # Users should use delete() for specific keys or clear Redis manually
+        # if needed
+

miso_client/services/encryption.py

@@ -0,0 +1,93 @@
+"""
+Encryption service for sensitive data using Fernet symmetric encryption.
+
+This module provides encryption/decryption functionality that can be used anywhere
+in the application. It supports reading the encryption key from environment variables
+or accepting it as a constructor parameter.
+"""
+
+import os
+import base64
+from typing import Optional
+from cryptography.fernet import Fernet
+from ..errors import ConfigurationError
+
+
+class EncryptionService:
+    """Service for encrypting/decrypting sensitive data using Fernet encryption."""
+    
+    def __init__(self, encryption_key: Optional[str] = None):
+        """
+        Initialize encryption service with key from environment or parameter.
+        
+        Args:
+            encryption_key: Optional encryption key. If not provided, reads from EXTENSION_KEY env var.
+                           If provided, overrides environment variable.
+        
+        Raises:
+            ConfigurationError: If encryption key is not found or invalid
+        """
+        # Use provided key, or fall back to environment variable
+        key = encryption_key or os.environ.get("ENCRYPTION_KEY")
+        
+        if not key:
+            raise ConfigurationError(
+                "ENCRYPTION_KEY not found. Either set ENCRYPTION_KEY environment variable "
+                "or pass encryption_key parameter to EncryptionService constructor."
+            )
+        
+        try:
+            # Fernet.generate_key() returns bytes, but env vars are strings
+            # Convert string to bytes if needed
+            key_bytes = key.encode() if isinstance(key, str) else key
+            self.fernet = Fernet(key_bytes)
+        except Exception as e:
+            raise ConfigurationError(
+                f"Failed to initialize encryption service with provided key: {str(e)}"
+            ) from e
+    
+    def encrypt(self, plaintext: str) -> str:
+        """
+        Encrypt sensitive data.
+        
+        Args:
+            plaintext: Plain text string to encrypt
+            
+        Returns:
+            Base64-encoded encrypted string
+            
+        Raises:
+            ValueError: If encryption fails
+        """
+        if not plaintext:
+            return ""
+        
+        try:
+            encrypted = self.fernet.encrypt(plaintext.encode())
+            return base64.b64encode(encrypted).decode()
+        except Exception as e:
+            raise ValueError(f"Failed to encrypt data: {str(e)}") from e
+    
+    def decrypt(self, encrypted_text: str) -> str:
+        """
+        Decrypt sensitive data.
+        
+        Args:
+            encrypted_text: Base64-encoded encrypted string
+            
+        Returns:
+            Decrypted plain text string
+            
+        Raises:
+            ValueError: If decryption fails or data is invalid
+        """
+        if not encrypted_text:
+            return ""
+        
+        try:
+            decoded = base64.b64decode(encrypted_text.encode())
+            decrypted = self.fernet.decrypt(decoded)
+            return decrypted.decode()
+        except Exception as e:
+            raise ValueError(f"Failed to decrypt data: {str(e)}") from e
+