miso-client 0.1.0__py3-none-any.whl → 3.7.2__py3-none-any.whl

miso_client/utils/data_masker.py

@@ -5,16 +5,18 @@ Implements ISO 27001 data protection controls by masking sensitive fields
 in log entries and context data.
 """
 
-from typing import Any, Set
+from typing import Any, Optional, Set
+
+from .sensitive_fields_loader import get_sensitive_fields_array
 
 
 class DataMasker:
     """Static class for masking sensitive data."""
-    
+
     MASKED_VALUE = "***MASKED***"
-    
-    # Set of sensitive field names (normalized)
-    _sensitive_fields: Set[str] = {
+
+    # Hardcoded set of sensitive field names (normalized) - fallback if JSON cannot be loaded
+    _hardcoded_sensitive_fields: Set[str] = {
         "password",
         "passwd",
         "pwd",
@@ -37,58 +39,128 @@ class DataMasker:
         "privatekey",
         "secretkey",
     }
-    
+
+    # Cached merged sensitive fields (loaded on first use)
+    _sensitive_fields: Optional[Set[str]] = None
+    _config_loaded: bool = False
+
+    @classmethod
+    def _load_config(cls, config_path: Optional[str] = None) -> None:
+        """
+        Load sensitive fields configuration from JSON and merge with hardcoded defaults.
+
+        This method is called automatically on first use. It loads JSON configuration
+        and merges it with hardcoded defaults, ensuring backward compatibility.
+
+        Args:
+            config_path: Optional custom path to JSON config file
+        """
+        if cls._config_loaded:
+            return
+
+        # Start with hardcoded fields as base
+        merged_fields = set(cls._hardcoded_sensitive_fields)
+
+        try:
+            # Try to load fields from JSON configuration
+            json_fields = get_sensitive_fields_array(config_path)
+            if json_fields:
+                # Normalize and add JSON fields (same normalization as hardcoded fields)
+                for field in json_fields:
+                    if isinstance(field, str):
+                        # Normalize: lowercase and remove underscores/hyphens
+                        normalized = field.lower().replace("_", "").replace("-", "")
+                        merged_fields.add(normalized)
+        except Exception:
+            # If JSON loading fails, fall back to hardcoded fields only
+            pass
+
+        cls._sensitive_fields = merged_fields
+        cls._config_loaded = True
+
+    @classmethod
+    def _get_sensitive_fields(cls) -> Set[str]:
+        """
+        Get the set of sensitive fields (loads config on first call).
+
+        Returns:
+            Set of normalized sensitive field names
+        """
+        if not cls._config_loaded:
+            cls._load_config()
+        assert cls._sensitive_fields is not None
+        return cls._sensitive_fields
+
+    @classmethod
+    def set_config_path(cls, config_path: str) -> None:
+        """
+        Set custom path for sensitive fields configuration.
+
+        Must be called before first use of DataMasker methods if custom path is needed.
+        Otherwise, default path or environment variable will be used.
+
+        Args:
+            config_path: Path to JSON configuration file
+        """
+        # Reset cache to force reload with new path
+        cls._config_loaded = False
+        cls._sensitive_fields = None
+        cls._load_config(config_path)
+
     @classmethod
     def is_sensitive_field(cls, key: str) -> bool:
         """
         Check if a field name indicates sensitive data.
-        
+
         Args:
             key: Field name to check
-            
+
         Returns:
             True if field is sensitive, False otherwise
         """
         # Normalize key: lowercase and remove underscores/hyphens
         normalized_key = key.lower().replace("_", "").replace("-", "")
-        
+
+        # Get sensitive fields (loads config on first use)
+        sensitive_fields = cls._get_sensitive_fields()
+
         # Check exact match
-        if normalized_key in cls._sensitive_fields:
+        if normalized_key in sensitive_fields:
             return True
-        
+
         # Check if field contains sensitive keywords
-        for sensitive_field in cls._sensitive_fields:
+        for sensitive_field in sensitive_fields:
             if sensitive_field in normalized_key:
                 return True
-        
+
         return False
-    
+
     @classmethod
     def mask_sensitive_data(cls, data: Any) -> Any:
         """
         Mask sensitive data in objects, arrays, or primitives.
-        
+
         Returns a masked copy without modifying the original.
         Recursively processes nested objects and arrays.
-        
+
         Args:
             data: Data to mask (dict, list, or primitive)
-            
+
         Returns:
             Masked copy of the data
         """
         # Handle null and undefined
         if data is None:
             return data
-        
+
         # Handle primitives (string, number, boolean)
         if not isinstance(data, (dict, list)):
             return data
-        
+
         # Handle arrays
         if isinstance(data, list):
             return [cls.mask_sensitive_data(item) for item in data]
-        
+
         # Handle objects/dicts
         masked: dict[str, Any] = {}
         for key, value in data.items():
@@ -101,49 +173,49 @@ class DataMasker:
             else:
                 # Keep non-sensitive value as-is
                 masked[key] = value
-        
+
         return masked
-    
+
     @classmethod
     def mask_value(cls, value: str, show_first: int = 0, show_last: int = 0) -> str:
         """
         Mask specific value (useful for masking individual strings).
-        
+
         Args:
             value: String value to mask
             show_first: Number of characters to show at the start
             show_last: Number of characters to show at the end
-            
+
         Returns:
             Masked string value
         """
         if not value or len(value) <= show_first + show_last:
             return cls.MASKED_VALUE
-        
+
         first = value[:show_first] if show_first > 0 else ""
         last = value[-show_last:] if show_last > 0 else ""
         masked_length = max(8, len(value) - show_first - show_last)
         masked = "*" * masked_length
-        
+
         return f"{first}{masked}{last}"
-    
+
     @classmethod
     def contains_sensitive_data(cls, data: Any) -> bool:
         """
         Check if data contains sensitive information.
-        
+
         Args:
             data: Data to check
-            
+
         Returns:
             True if data contains sensitive fields, False otherwise
         """
         if data is None or not isinstance(data, (dict, list)):
             return False
-        
+
         if isinstance(data, list):
             return any(cls.contains_sensitive_data(item) for item in data)
-        
+
         # Check object keys
         for key, value in data.items():
             if cls.is_sensitive_field(key):
@@ -151,6 +223,5 @@ class DataMasker:
             if isinstance(value, (dict, list)):
                 if cls.contains_sensitive_data(value):
                     return True
-        
-        return False
 
+        return False

miso_client/utils/environment_token.py

@@ -0,0 +1,126 @@
+"""
+Server-side environment token wrapper with origin validation and audit logging.
+
+This module provides a secure server-side wrapper for fetching environment tokens
+with origin validation and ISO 27001 compliant audit logging.
+"""
+
+from typing import Any
+
+from ..errors import AuthenticationError
+from ..services.logger import LoggerService
+from .data_masker import DataMasker
+from .origin_validator import validate_origin
+
+
+async def get_environment_token(miso_client: Any, headers: Any) -> str:
+    """
+    Get environment token with origin validation and audit logging.
+
+    This is a server-side wrapper that validates request origin before calling
+    the controller, and logs audit events with ISO 27001 compliant data masking.
+
+    Args:
+        miso_client: MisoClient instance
+        headers: Request headers dict or object with headers attribute
+
+    Returns:
+        Client token string
+
+    Raises:
+        AuthenticationError: If origin validation fails or token fetch fails
+
+    Example:
+        >>> from miso_client import MisoClient, MisoClientConfig
+        >>> config = MisoClientConfig(...)
+        >>> client = MisoClient(config)
+        >>> headers = {"origin": "http://localhost:3000"}
+        >>> token = await get_environment_token(client, headers)
+    """
+    config = miso_client.config
+    logger: LoggerService = miso_client.logger
+
+    # Validate origin if allowedOrigins is configured
+    if config.allowedOrigins:
+        validation_result = validate_origin(headers, config.allowedOrigins)
+        if not validation_result["valid"]:
+            error_message = validation_result.get("error", "Origin validation failed")
+
+            # Log error and audit event before raising exception
+            masked_config = {
+                "clientId": config.client_id,
+                "clientSecret": DataMasker.mask_sensitive_data(config.client_secret),
+            }
+
+            await logger.error(
+                "Origin validation failed for environment token request",
+                context={
+                    "error": error_message,
+                    "allowedOrigins": config.allowedOrigins,
+                    "clientId": config.client_id,
+                },
+            )
+
+            await logger.audit(
+                "auth.environment_token.origin_validation_failed",
+                resource="/api/v1/auth/token",
+                context={
+                    "error": error_message,
+                    "allowedOrigins": config.allowedOrigins,
+                    **masked_config,
+                },
+            )
+
+            raise AuthenticationError(f"Origin validation failed: {error_message}")
+
+    # Log audit event before calling controller (with masked credentials)
+    masked_config = {
+        "clientId": config.client_id,
+        "clientSecret": DataMasker.mask_sensitive_data(config.client_secret),
+    }
+
+    await logger.audit(
+        "auth.environment_token.request",
+        resource=config.clientTokenUri or "/api/v1/auth/token",
+        context=masked_config,
+    )
+
+    try:
+        # Call auth service to get environment token
+        token: str = await miso_client.auth.get_environment_token()
+
+        # Log successful token fetch
+        await logger.audit(
+            "auth.environment_token.success",
+            resource=config.clientTokenUri or "/api/v1/auth/token",
+            context={
+                "clientId": config.client_id,
+                "tokenLength": len(token) if token else 0,
+            },
+        )
+
+        return token
+
+    except Exception as error:
+        # Log error and audit event
+        await logger.error(
+            "Failed to get environment token",
+            context={
+                "error": str(error),
+                "clientId": config.client_id,
+            },
+        )
+
+        await logger.audit(
+            "auth.environment_token.failure",
+            resource=config.clientTokenUri or "/api/v1/auth/token",
+            context={
+                "error": str(error),
+                **masked_config,
+            },
+        )
+
+        # Re-raise as AuthenticationError
+        if isinstance(error, AuthenticationError):
+            raise
+        raise AuthenticationError(f"Failed to get environment token: {str(error)}") from error

miso_client/utils/error_utils.py

@@ -0,0 +1,216 @@
+"""
+Error utilities for MisoClient SDK.
+
+This module provides error transformation utilities for handling
+camelCase error responses from the API.
+"""
+
+from typing import Optional
+
+from ..errors import MisoClientError
+from ..models.error_response import ErrorResponse
+
+
+class ApiErrorException(Exception):
+    """
+    Exception class for camelCase error responses.
+
+    Used with camelCase ErrorResponse format matching TypeScript SDK.
+    """
+
+    def __init__(self, error: ErrorResponse):
+        """
+        Initialize ApiErrorException.
+
+        Args:
+            error: ErrorResponse object with camelCase properties
+        """
+        super().__init__(error.title or "API Error")
+        self.name = "ApiErrorException"
+        self.statusCode = error.statusCode
+        self.correlationId = error.correlationId
+        self.type = error.type
+        self.instance = error.instance
+        self.errors = error.errors
+
+
+def transformError(error_data: dict) -> ErrorResponse:
+    """
+    Transform arbitrary error into standardized camelCase ErrorResponse.
+
+    Converts error data dictionary to ErrorResponse object with camelCase field names.
+
+    Args:
+        error_data: Dictionary with error data (must be camelCase)
+
+    Returns:
+        ErrorResponse object with standardized format
+
+    Examples:
+        >>> error_data = {
+        ...     'errors': ['Error message'],
+        ...     'type': '/Errors/Bad Input',
+        ...     'title': 'Bad Request',
+        ...     'statusCode': 400,
+        ...     'instance': '/api/endpoint'
+        ... }
+        >>> error_response = transformError(error_data)
+        >>> error_response.statusCode
+        400
+    """
+    return ErrorResponse(**error_data)
+
+
+# Alias for backward compatibility
+transform_error_to_snake_case = transformError
+
+
+def handleApiError(
+    response_data: dict, status_code: int, instance: Optional[str] = None
+) -> ApiErrorException:
+    """
+    Handle API error and raise camelCase ApiErrorException.
+
+    Creates ApiErrorException from camelCase API response.
+
+    Args:
+        response_data: Error response data from API (must be camelCase)
+        status_code: HTTP status code (overrides statusCode in response_data)
+        instance: Optional request instance URI (overrides instance in response_data)
+
+    Returns:
+        ApiErrorException with camelCase error format
+
+    Raises:
+        ApiErrorException: Always raises this exception
+
+    Examples:
+        >>> response_data = {
+        ...     'errors': ['Validation failed'],
+        ...     'type': '/Errors/Validation',
+        ...     'title': 'Validation Error',
+        ...     'statusCode': 422
+        ... }
+        >>> try:
+        ...     handleApiError(response_data, 422, '/api/endpoint')
+        ... except ApiErrorException as e:
+        ...     e.statusCode
+        422
+    """
+    # Create a copy to avoid mutating the original
+    data = response_data.copy()
+
+    # Override instance if provided
+    if instance:
+        data["instance"] = instance
+
+    # Override statusCode if provided
+    data["statusCode"] = status_code
+
+    # Ensure title has a default if missing
+    if "title" not in data:
+        data["title"] = None
+
+    # Transform to ErrorResponse
+    error_response = transformError(data)
+
+    # Raise ApiErrorException
+    raise ApiErrorException(error_response)
+
+
+def handle_api_error_snake_case(
+    response_data: dict, status_code: int, instance: Optional[str] = None
+) -> MisoClientError:
+    """
+    Handle errors with camelCase response format (legacy function).
+
+    Creates MisoClientError with ErrorResponse from camelCase API response.
+    This is kept for backward compatibility. New code should use handleApiError().
+
+    Args:
+        response_data: Error response data from API (must be camelCase)
+        status_code: HTTP status code (overrides statusCode in response_data)
+        instance: Optional request instance URI (overrides instance in response_data)
+
+    Returns:
+        MisoClientError with structured ErrorResponse
+
+    Examples:
+        >>> response_data = {
+        ...     'errors': ['Validation failed'],
+        ...     'type': '/Errors/Validation',
+        ...     'title': 'Validation Error',
+        ...     'statusCode': 422
+        ... }
+        >>> error = handle_api_error_snake_case(response_data, 422, '/api/endpoint')
+        >>> error.error_response.statusCode
+        422
+    """
+    # Create a copy to avoid mutating the original
+    data = response_data.copy()
+
+    # Override instance if provided
+    if instance:
+        data["instance"] = instance
+
+    # Override statusCode if provided
+    data["statusCode"] = status_code
+
+    # Ensure title has a default if missing
+    if "title" not in data:
+        data["title"] = None
+
+    # Transform to ErrorResponse
+    error_response = transformError(data)
+
+    # Create error message from errors list
+    if error_response.errors:
+        if len(error_response.errors) == 1:
+            message = error_response.errors[0]
+        else:
+            title_prefix = f"{error_response.title}: " if error_response.title else ""
+            message = f"{title_prefix}{'; '.join(error_response.errors)}"
+    else:
+        message = error_response.title or "API Error"
+
+    # Create MisoClientError with ErrorResponse
+    return MisoClientError(
+        message=message,
+        status_code=status_code,
+        error_response=error_response,
+    )
+
+
+def extract_correlation_id_from_error(error: Exception) -> Optional[str]:
+    """
+    Extract correlation ID from exception if available.
+
+    Checks MisoClientError.error_response.correlationId and ApiErrorException.correlationId.
+
+    Args:
+        error: Exception object
+
+    Returns:
+        Correlation ID string if found, None otherwise
+
+    Examples:
+        >>> error = MisoClientError("Error", error_response=ErrorResponse(
+        ...     errors=["Error"], type="/Errors/Test", statusCode=400,
+        ...     correlationId="req-123"
+        ... ))
+        >>> extract_correlation_id_from_error(error)
+        'req-123'
+    """
+    # Check MisoClientError with error_response
+    if isinstance(error, MisoClientError) and error.error_response:
+        correlation_id = error.error_response.correlationId
+        if correlation_id is not None:
+            return str(correlation_id)
+
+    # Check ApiErrorException with correlationId property
+    if isinstance(error, ApiErrorException):
+        correlation_id = error.correlationId
+        if correlation_id is not None:
+            return str(correlation_id)
+
+    return None