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

miso_client/utils/request_context.py

@@ -0,0 +1,285 @@
+"""Request context extraction utilities for HTTP requests."""
+
+from typing import Any, Dict, Optional, Protocol, Tuple, runtime_checkable
+
+from ..utils.jwt_tools import decode_token
+
+
+@runtime_checkable
+class RequestHeaders(Protocol):
+    """Protocol for request headers access."""
+
+    def get(self, key: str, default: Optional[str] = None) -> Optional[str]:
+        """Get header value by key."""
+        ...
+
+
+@runtime_checkable
+class RequestClient(Protocol):
+    """Protocol for request client info."""
+
+    host: Optional[str]
+
+
+@runtime_checkable
+class RequestURL(Protocol):
+    """Protocol for request URL."""
+
+    path: str
+
+
+@runtime_checkable
+class HttpRequest(Protocol):
+    """
+    Protocol for HTTP request objects.
+
+    Supports:
+    - FastAPI/Starlette Request
+    - Flask Request
+    - Generic dict-like request objects
+    """
+
+    method: str
+    headers: RequestHeaders
+    client: Optional[RequestClient]
+    url: Optional[RequestURL]
+
+
+class RequestContext:
+    """Container for extracted request context."""
+
+    def __init__(
+        self,
+        ip_address: Optional[str] = None,
+        method: Optional[str] = None,
+        path: Optional[str] = None,
+        user_agent: Optional[str] = None,
+        correlation_id: Optional[str] = None,
+        referer: Optional[str] = None,
+        user_id: Optional[str] = None,
+        session_id: Optional[str] = None,
+        request_id: Optional[str] = None,
+        request_size: Optional[int] = None,
+    ):
+        """Initialize request context."""
+        self.ip_address = ip_address
+        self.method = method
+        self.path = path
+        self.user_agent = user_agent
+        self.correlation_id = correlation_id
+        self.referer = referer
+        self.user_id = user_id
+        self.session_id = session_id
+        self.request_id = request_id
+        self.request_size = request_size
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary, excluding None values."""
+        return {k: v for k, v in self.__dict__.items() if v is not None}
+
+
+def extract_request_context(request: Any) -> RequestContext:
+    """
+    Extract logging context from HTTP request object.
+
+    Supports multiple Python web frameworks:
+    - FastAPI/Starlette Request
+    - Flask Request
+    - Generic dict-like request objects
+
+    Args:
+        request: HTTP request object
+
+    Returns:
+        RequestContext with extracted fields
+
+    Example:
+        >>> from fastapi import Request
+        >>> ctx = extract_request_context(request)
+        >>> await logger.with_request(request).info("Processing")
+    """
+    # Extract IP address (handle proxies)
+    ip_address = _extract_ip_address(request)
+
+    # Extract correlation ID from common headers
+    correlation_id = _extract_correlation_id(request)
+
+    # Extract user from JWT if available
+    user_id, session_id = _extract_user_from_auth_header(request)
+
+    # Extract method
+    method = _extract_method(request)
+
+    # Extract path
+    path = _extract_path(request)
+
+    # Extract other headers
+    headers = _get_headers(request)
+    user_agent = headers.get("user-agent")
+    referer = headers.get("referer")
+    request_id = headers.get("x-request-id")
+
+    # Extract request size
+    content_length = headers.get("content-length")
+    request_size = int(content_length) if content_length else None
+
+    return RequestContext(
+        ip_address=ip_address,
+        method=method,
+        path=path,
+        user_agent=user_agent,
+        correlation_id=correlation_id,
+        referer=referer,
+        user_id=user_id,
+        session_id=session_id,
+        request_id=request_id,
+        request_size=request_size,
+    )
+
+
+def _get_headers(request: Any) -> Dict[str, Optional[str]]:
+    """Get headers from request object."""
+    # FastAPI/Starlette
+    if hasattr(request, "headers"):
+        headers = request.headers
+        if hasattr(headers, "get"):
+            # Type cast to satisfy type checker - headers.get() returns Optional[str]
+            return headers  # type: ignore[no-any-return]
+        # Convert to dict if needed
+        if hasattr(headers, "items"):
+            return dict(headers.items())
+    return {}
+
+
+def _extract_ip_address(request: Any) -> Optional[str]:
+    """Extract client IP address, handling proxies."""
+    headers = _get_headers(request)
+
+    # Check x-forwarded-for first (proxy/load balancer)
+    forwarded_for = headers.get("x-forwarded-for")
+    if forwarded_for:
+        # Take first IP in chain
+        return forwarded_for.split(",")[0].strip()
+
+    # Check x-real-ip
+    real_ip = headers.get("x-real-ip")
+    if real_ip:
+        return real_ip
+
+    # FastAPI/Starlette: request.client.host
+    # Check if client exists and has host attribute with actual value
+    if hasattr(request, "client") and request.client:
+        try:
+            host = getattr(request.client, "host", None)
+            # Check if host is a real value (string) and not a MagicMock
+            if isinstance(host, str):
+                return host
+        except Exception:
+            pass
+
+    # Flask: request.remote_addr
+    if hasattr(request, "remote_addr"):
+        try:
+            remote_addr = getattr(request, "remote_addr", None)
+            # Check if remote_addr is a real value (string) and not a MagicMock
+            if isinstance(remote_addr, str):
+                return remote_addr
+        except Exception:
+            pass
+
+    return None
+
+
+def _extract_correlation_id(request: Any) -> Optional[str]:
+    """Extract correlation ID from common headers."""
+    headers = _get_headers(request)
+
+    return (
+        headers.get("x-correlation-id")
+        or headers.get("x-request-id")
+        or headers.get("request-id")
+        or headers.get("traceparent")  # W3C Trace Context
+    )
+
+
+def _extract_method(request: Any) -> Optional[str]:
+    """Extract HTTP method from request."""
+    if hasattr(request, "method"):
+        try:
+            method = getattr(request, "method", None)
+            # Check if method is a real value (string) and not a MagicMock
+            if isinstance(method, str):
+                return method
+        except Exception:
+            pass
+    return None
+
+
+def _extract_path(request: Any) -> Optional[str]:
+    """Extract request path from request."""
+    # FastAPI/Starlette: request.url.path
+    if hasattr(request, "url") and request.url:
+        try:
+            url_path = getattr(request.url, "path", None)
+            # Check if path is a real value (string) and not a MagicMock
+            if isinstance(url_path, str):
+                return url_path
+        except Exception:
+            pass
+
+    # Flask: request.path
+    if hasattr(request, "path"):
+        try:
+            path = getattr(request, "path", None)
+            # Check if path is a real value (string) and not a MagicMock
+            if isinstance(path, str):
+                return path
+        except Exception:
+            pass
+
+    # Try original_url (some frameworks)
+    if hasattr(request, "original_url"):
+        try:
+            original_url = getattr(request, "original_url", None)
+            # Check if original_url is a real value (string) and not a MagicMock
+            if isinstance(original_url, str):
+                return original_url
+        except Exception:
+            pass
+
+    return None
+
+
+def _extract_user_from_auth_header(request: Any) -> Tuple[Optional[str], Optional[str]]:
+    """
+    Extract user ID and session ID from Authorization header JWT.
+
+    Args:
+        request: HTTP request object
+
+    Returns:
+        Tuple of (user_id, session_id)
+    """
+    headers = _get_headers(request)
+    auth_header = headers.get("authorization")
+
+    if not auth_header or not auth_header.startswith("Bearer "):
+        return None, None
+
+    try:
+        token = auth_header[7:]  # Remove "Bearer " prefix
+        decoded = decode_token(token)
+        if not decoded:
+            return None, None
+
+        user_id = (
+            decoded.get("sub")
+            or decoded.get("userId")
+            or decoded.get("user_id")
+            or decoded.get("id")
+        )
+        session_id = decoded.get("sessionId") or decoded.get("sid")
+
+        return user_id, session_id
+    except Exception:
+        return None, None

miso_client/utils/sensitive_fields_loader.py

@@ -0,0 +1,116 @@
+"""
+Sensitive fields configuration loader for ISO 27001 compliance.
+
+This module provides utilities to load and merge sensitive fields configuration
+from JSON files, supporting custom configuration paths and environment variables.
+"""
+
+import json
+import os
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+# Default path to sensitive fields config relative to this file
+_DEFAULT_CONFIG_PATH = Path(__file__).parent / "sensitive_fields_config.json"
+
+
+def load_sensitive_fields_config(
+    config_path: Optional[str] = None,
+) -> Dict[str, Any]:
+    """
+    Load sensitive fields configuration from JSON file.
+
+    Supports custom path via:
+    1. config_path parameter
+    2. MISO_SENSITIVE_FIELDS_CONFIG environment variable
+    3. Default path: miso_client/utils/sensitive_fields_config.json
+
+    Args:
+        config_path: Optional custom path to JSON config file
+
+    Returns:
+        Dictionary with 'fields' and 'fieldPatterns' keys
+        Returns empty dict if file cannot be loaded
+
+    Example:
+        >>> config = load_sensitive_fields_config()
+        >>> fields = config.get('fields', {})
+    """
+    # Priority: parameter > environment variable > default
+    if config_path:
+        file_path = Path(config_path)
+    elif os.environ.get("MISO_SENSITIVE_FIELDS_CONFIG"):
+        file_path = Path(os.environ["MISO_SENSITIVE_FIELDS_CONFIG"])
+    else:
+        file_path = _DEFAULT_CONFIG_PATH
+
+    try:
+        with open(file_path, "r", encoding="utf-8") as f:
+            config = json.load(f)
+            # Validate structure
+            if isinstance(config, dict):
+                return config
+            return {}
+    except (FileNotFoundError, json.JSONDecodeError, IOError, OSError):
+        # File not found, invalid JSON, or permission error
+        # Return empty dict - fallback to hardcoded defaults
+        return {}
+
+
+def get_sensitive_fields_array(
+    config_path: Optional[str] = None,
+) -> List[str]:
+    """
+    Get flattened array of all sensitive field names from configuration.
+
+    Args:
+        config_path: Optional custom path to JSON config file
+
+    Returns:
+        Flattened list of all sensitive field names from all categories
+        Returns empty list if config cannot be loaded
+
+    Example:
+        >>> fields = get_sensitive_fields_array()
+        >>> assert 'password' in fields
+        >>> assert 'token' in fields
+    """
+    config = load_sensitive_fields_config(config_path)
+    fields_dict = config.get("fields", {})
+
+    # Flatten all categories into single list
+    all_fields: List[str] = []
+    if isinstance(fields_dict, dict):
+        for category_fields in fields_dict.values():
+            if isinstance(category_fields, list):
+                all_fields.extend(category_fields)
+
+    # Remove duplicates while preserving order
+    seen = set()
+    unique_fields = []
+    for field in all_fields:
+        if field.lower() not in seen:
+            seen.add(field.lower())
+            unique_fields.append(field)
+
+    return unique_fields
+
+
+def get_field_patterns(config_path: Optional[str] = None) -> List[str]:
+    """
+    Get field pattern matching rules from configuration.
+
+    Args:
+        config_path: Optional custom path to JSON config file
+
+    Returns:
+        List of field pattern matching rules
+        Returns empty list if config cannot be loaded or no patterns defined
+
+    Example:
+        >>> patterns = get_field_patterns()
+        >>> # Patterns can be regex patterns or simple matching rules
+    """
+    config = load_sensitive_fields_config(config_path)
+    patterns = config.get("fieldPatterns", [])
+    return patterns if isinstance(patterns, list) else []

miso_client/utils/sort.py

@@ -0,0 +1,116 @@
+"""
+Sort utilities for MisoClient SDK.
+
+This module provides reusable sort utilities for parsing sort parameters
+and building sort query strings.
+"""
+
+from typing import List, cast
+from urllib.parse import quote
+
+from ..models.sort import SortOption, SortOrder
+
+
+def parse_sort_params(params: dict) -> List[SortOption]:
+    """
+    Parse sort query parameters into SortOption list.
+
+    Parses `?sort=-field` format into SortOption objects.
+    Supports multiple sort parameters (array of sort strings).
+    Prefix with '-' for descending order, otherwise ascending.
+
+    Args:
+        params: Dictionary with query parameters (e.g., {'sort': '-updated_at'} or {'sort': ['-updated_at', 'created_at']})
+
+    Returns:
+        List of SortOption objects
+
+    Examples:
+        >>> parse_sort_params({'sort': '-updated_at'})
+        [SortOption(field='updated_at', order='desc')]
+        >>> parse_sort_params({'sort': ['-updated_at', 'created_at']})
+        [SortOption(field='updated_at', order='desc'), SortOption(field='created_at', order='asc')]
+    """
+    sort_options: List[SortOption] = []
+
+    # Get sort parameter (can be string or list)
+    sort_param = params.get("sort")
+    if not sort_param:
+        return sort_options
+
+    # Normalize to list
+    if isinstance(sort_param, str):
+        sort_strings = [sort_param]
+    elif isinstance(sort_param, list):
+        sort_strings = sort_param
+    else:
+        return sort_options
+
+    # Parse each sort string
+    for sort_str in sort_strings:
+        if not isinstance(sort_str, str):
+            continue
+
+        sort_str = sort_str.strip()
+        if not sort_str:
+            continue
+
+        # Check for descending order (prefix with '-')
+        if sort_str.startswith("-"):
+            field = sort_str[1:].strip()
+            order: SortOrder = "desc"
+        else:
+            field = sort_str.strip()
+            order = "asc"
+
+        if field:
+            sort_options.append(SortOption(field=field, order=cast(SortOrder, order)))
+
+    return sort_options
+
+
+def build_sort_string(sort_options: List[SortOption]) -> str:
+    """
+    Convert SortOption list to query string format.
+
+    Converts SortOption objects to sort query string format.
+    Descending order fields are prefixed with '-'.
+
+    Args:
+        sort_options: List of SortOption objects
+
+    Returns:
+        Sort query string (e.g., '-updated_at,created_at' or single value '-updated_at')
+
+    Examples:
+        >>> from miso_client.models.sort import SortOption
+        >>> sort_options = [SortOption(field='updated_at', order='desc')]
+        >>> build_sort_string(sort_options)
+        '-updated_at'
+        >>> sort_options = [
+        ...     SortOption(field='updated_at', order='desc'),
+        ...     SortOption(field='created_at', order='asc')
+        ... ]
+        >>> build_sort_string(sort_options)
+        '-updated_at,created_at'
+    """
+    if not sort_options:
+        return ""
+
+    sort_strings: List[str] = []
+    for sort_option in sort_options:
+        field = sort_option.field
+        order = sort_option.order
+
+        # URL encode field name
+        field_encoded = quote(field)
+
+        # Add '-' prefix for descending order
+        if order == "desc":
+            sort_strings.append(f"-{field_encoded}")
+        else:
+            sort_strings.append(field_encoded)
+
+    # Join multiple sorts with comma (if needed for single sort param)
+    # Or return as comma-separated string
+    return ",".join(sort_strings)

miso_client/utils/token_utils.py

@@ -0,0 +1,114 @@
+"""
+Client token utilities for extracting information from JWT tokens.
+
+This module provides utilities for decoding client tokens and extracting
+application/environment information without verification.
+"""
+
+from typing import Dict, Optional
+
+from .jwt_tools import decode_token
+
+
+def extract_client_token_info(client_token: str) -> Dict[str, Optional[str]]:
+    """
+    Extract application and environment information from client token.
+
+    Decodes JWT token without verification (no secret available) and extracts
+    fields with fallback support for multiple field name variations.
+
+    Args:
+        client_token: JWT client token string
+
+    Returns:
+        Dictionary with optional fields:
+            - application: Optional[str] - Application name
+            - environment: Optional[str] - Environment name
+            - applicationId: Optional[str] - Application ID
+            - clientId: Optional[str] - Client ID
+
+    Example:
+        >>> token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+        >>> info = extract_client_token_info(token)
+        >>> info.get("application")
+        'my-app'
+    """
+    if not client_token or not isinstance(client_token, str):
+        return {
+            "application": None,
+            "environment": None,
+            "applicationId": None,
+            "clientId": None,
+        }
+
+    try:
+        decoded = decode_token(client_token)
+        if not decoded or not isinstance(decoded, dict):
+            return {
+                "application": None,
+                "environment": None,
+                "applicationId": None,
+                "clientId": None,
+            }
+
+        # Extract fields with fallback support
+        application = (
+            decoded.get("application")
+            or decoded.get("app")
+            or decoded.get("Application")
+            or decoded.get("App")
+        )
+        if isinstance(application, str):
+            application = application.strip() if application.strip() else None
+        else:
+            application = None
+
+        environment = (
+            decoded.get("environment")
+            or decoded.get("env")
+            or decoded.get("Environment")
+            or decoded.get("Env")
+        )
+        if isinstance(environment, str):
+            environment = environment.strip() if environment.strip() else None
+        else:
+            environment = None
+
+        application_id = (
+            decoded.get("applicationId")
+            or decoded.get("app_id")
+            or decoded.get("application_id")
+            or decoded.get("ApplicationId")
+            or decoded.get("AppId")
+        )
+        if isinstance(application_id, str):
+            application_id = application_id.strip() if application_id.strip() else None
+        else:
+            application_id = None
+
+        client_id = (
+            decoded.get("clientId")
+            or decoded.get("client_id")
+            or decoded.get("ClientId")
+            or decoded.get("Client_Id")
+        )
+        if isinstance(client_id, str):
+            client_id = client_id.strip() if client_id.strip() else None
+        else:
+            client_id = None
+
+        return {
+            "application": application,
+            "environment": environment,
+            "applicationId": application_id,
+            "clientId": client_id,
+        }
+
+    except Exception:
+        # Decode failed, return empty dict
+        return {
+            "application": None,
+            "environment": None,
+            "applicationId": None,
+            "clientId": None,
+        }

miso_client/utils/url_validator.py

@@ -0,0 +1,66 @@
+"""
+URL validation utility for controller URLs.
+
+This module provides utilities for validating HTTP/HTTPS URLs with comprehensive
+checks to prevent dangerous protocols and ensure valid URL structure.
+"""
+
+from urllib.parse import urlparse
+
+
+def validate_url(url: str) -> bool:
+    """
+    Validate HTTP/HTTPS URL with comprehensive checks.
+
+    Validates that the URL:
+    - Starts with http:// or https://
+    - Has a valid hostname
+    - Does not use dangerous protocols (javascript:, data:, etc.)
+
+    Args:
+        url: URL string to validate
+
+    Returns:
+        True if URL is valid, False otherwise
+
+    Example:
+        >>> validate_url("https://controller.example.com")
+        True
+        >>> validate_url("javascript:alert('xss')")
+        False
+        >>> validate_url("http://localhost:3000")
+        True
+    """
+    if not url or not isinstance(url, str):
+        return False
+
+    url = url.strip()
+    if not url:
+        return False
+
+    # Check for dangerous protocols
+    dangerous_protocols = ["javascript:", "data:", "vbscript:", "file:", "about:"]
+    url_lower = url.lower()
+    for protocol in dangerous_protocols:
+        if url_lower.startswith(protocol):
+            return False
+
+    # Must start with http:// or https://
+    if not url_lower.startswith(("http://", "https://")):
+        return False
+
+    try:
+        parsed = urlparse(url)
+        # Must have a valid hostname (netloc)
+        if not parsed.netloc:
+            return False
+
+        # Hostname must not be empty
+        hostname = parsed.netloc.split(":")[0]  # Remove port if present
+        if not hostname:
+            return False
+
+        return True
+    except Exception:
+        # URL parsing failed
+        return False