auth-gate 0.2.0__tar.gz → 0.2.3__tar.gz

{auth_gate-0.2.0/src/auth_gate.egg-info → auth_gate-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: auth-gate
-Version: 0.2.0
+Version: 0.2.3
 Summary: Enterprise-grade authentication for microservices with Kong and Keycloak integration
 Home-page: https://github.com/tradelink-org/auth-gate
 Author: Brian Mburu
@@ -290,6 +290,44 @@ app.add_middleware(
 )
 ```
 
+### Parameterized Paths with UUID Matching
+
+You can exclude or make paths optional using UUID v4 parameters:
+
+```python
+app.add_middleware(
+    AuthMiddleware,
+    excluded_paths={
+        "/api/v1/categories/{category_id:uuid}": {"GET"},  # Public read
+        "/api/v1/products/{product_id:uuid}": {"GET"},
+    },
+    excluded_prefixes={
+        "/api/{version:uuid}": {"GET"},  # Version-specific docs
+    },
+    optional_auth_paths={
+        "/api/v1/recommendations/{user_id:uuid}": {"GET"},  # Personalized if authenticated
+    }
+)
+```
+
+**Pattern Syntax:**
+- `{param:uuid}` - Matches valid UUID v4 format (case-insensitive)
+- Works with exact paths, prefixes, and optional auth paths
+- Supports method-specific exclusions
+- Exact matches take precedence over patterns
+
+**Example Behavior:**
+```python
+# Matches: /api/v1/categories/7b5bcc8f-2c99-43c0-9c7d-e27c10881bd2
+# Does not match: /api/v1/categories/invalid-id
+# Does not match: /api/v1/categories/all
+```
+
+**UUID v4 Validation:**
+- Must have version digit "4" in the correct position
+- Must have variant bits (8, 9, a, or b) in the correct position
+- Accepts uppercase, lowercase, or mixed case
+
 ### Direct Validator Usage
 
 ```python

{auth_gate-0.2.0 → auth_gate-0.2.3}/README.md

@@ -249,6 +249,44 @@ app.add_middleware(
 )
 ```
 
+### Parameterized Paths with UUID Matching
+
+You can exclude or make paths optional using UUID v4 parameters:
+
+```python
+app.add_middleware(
+    AuthMiddleware,
+    excluded_paths={
+        "/api/v1/categories/{category_id:uuid}": {"GET"},  # Public read
+        "/api/v1/products/{product_id:uuid}": {"GET"},
+    },
+    excluded_prefixes={
+        "/api/{version:uuid}": {"GET"},  # Version-specific docs
+    },
+    optional_auth_paths={
+        "/api/v1/recommendations/{user_id:uuid}": {"GET"},  # Personalized if authenticated
+    }
+)
+```
+
+**Pattern Syntax:**
+- `{param:uuid}` - Matches valid UUID v4 format (case-insensitive)
+- Works with exact paths, prefixes, and optional auth paths
+- Supports method-specific exclusions
+- Exact matches take precedence over patterns
+
+**Example Behavior:**
+```python
+# Matches: /api/v1/categories/7b5bcc8f-2c99-43c0-9c7d-e27c10881bd2
+# Does not match: /api/v1/categories/invalid-id
+# Does not match: /api/v1/categories/all
+```
+
+**UUID v4 Validation:**
+- Must have version digit "4" in the correct position
+- Must have variant bits (8, 9, a, or b) in the correct position
+- Accepts uppercase, lowercase, or mixed case
+
 ### Direct Validator Usage
 
 ```python

{auth_gate-0.2.0 → auth_gate-0.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "auth-gate"
-version = "0.2.0"
+version = "0.2.3"
 description = "Enterprise-grade authentication for microservices with Kong and Keycloak integration"
 readme = "README.md"
 requires-python = ">=3.11"

{auth_gate-0.2.0 → auth_gate-0.2.3}/setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = auth-gate
-version = 0.2.0
+version = 0.2.3
 author = Brian Mburu
 author_email = brian.mburu@students.jkuat.ac.ke
 description = Enterprise-grade authentication for microservices with Kong and Keycloak integration

{auth_gate-0.2.0 → auth_gate-0.2.3}/src/auth_gate/__init__.py

@@ -4,41 +4,67 @@ Tradelink Authentication Client
 Enterprise authentication client for microservices with Kong/Keycloak integration.
 """
 
-from .config import AuthMode, AuthSettings
+from .config import AuthMode, AuthSettings, get_settings, reset_settings
 from .fastapi_utils import (
     get_current_auth,
     get_current_service,
     get_current_user,
     get_optional_auth,
     get_optional_user,
+    is_bypass_mode,
+    is_using_keycloak,
+    is_using_kong,
     require_admin,
     require_customer,
     require_moderator,
     require_roles,
     require_scopes,
+    require_service_roles,
     require_supplier,
     require_supplier_or_admin,
     require_user_admin,
     require_user_customer,
     require_user_moderator,
+    require_user_roles,
     require_user_supplier,
     verify_hmac_signature,
 )
 from .middleware import AuthMiddleware
-from .schemas import ServiceContext, UserContext
-from .user_auth import UserValidator
+from .s2s_auth import (
+    CircuitBreaker,
+    CircuitBreakerOpenError,
+    CircuitState,
+    ServiceAuthClient,
+    ServiceToken,
+    get_service_auth_client,
+)
+from .schemas import AuthContext, BaseAuthContext, ServiceContext, UserContext
+from .user_auth import HMACVerifier, UserValidator, get_user_validator
 
-__version__ = "0.2.0"
+__version__ = "0.2.3"
 
 __all__ = [
     # Configuration
     "AuthSettings",
     "AuthMode",
-    # Schemas
+    "get_settings",
+    "reset_settings",
+    # Schemas & Type Aliases
     "UserContext",
     "ServiceContext",
+    "AuthContext",
+    "BaseAuthContext",
     # User Authentication
     "UserValidator",
+    "HMACVerifier",
+    "get_user_validator",
+    # Service-to-Service
+    "ServiceAuthClient",
+    "CircuitBreaker",
+    "CircuitBreakerOpenError",
+    "CircuitState",
+    "ServiceToken",
+    "get_service_auth_client",
     # Middleware
     "AuthMiddleware",
     # FastAPI Dependencies
@@ -48,6 +74,8 @@ __all__ = [
     "get_optional_auth",
     "get_optional_user",
     "require_roles",
+    "require_user_roles",
+    "require_service_roles",
     "require_scopes",
     "require_admin",
     "require_supplier",
@@ -59,4 +87,8 @@ __all__ = [
     "require_user_customer",
     "require_user_supplier",
     "require_user_moderator",
+    # Mode Utilities
+    "is_using_kong",
+    "is_using_keycloak",
+    "is_bypass_mode",
 ]

{auth_gate-0.2.0 → auth_gate-0.2.3}/src/auth_gate/middleware.py

@@ -3,8 +3,9 @@ FastAPI middleware for authentication (with service-to-service support)
 """
 
 import logging
+import re
 import time
-from typing import Dict, Optional, Set, Union
+from typing import Dict, List, Optional, Pattern, Set, Tuple, Union
 
 from fastapi import HTTPException, Request, status
 from fastapi.responses import JSONResponse
@@ -16,6 +17,12 @@ from .user_auth import get_user_validator
 
 logger = logging.getLogger(__name__)
 
+# UUID v4 format: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx
+# where y is 8, 9, a, or b (variant bits)
+TYPE_PATTERNS = {
+    "uuid": r"[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}",
+}
+
 
 class AuthMiddleware(BaseHTTPMiddleware):
     """
@@ -73,6 +80,16 @@ class AuthMiddleware(BaseHTTPMiddleware):
         # Paths where authentication is optional
         self.optional_auth_dict = self._normalize_paths(optional_auth_paths or set())
 
+        # Compile parameterized patterns
+        self._excluded_patterns = self._compile_patterns(self.excluded_paths_dict)
+        self._excluded_prefix_patterns = self._compile_patterns(
+            self.excluded_prefixes_dict, is_prefix=True
+        )
+        self._optional_patterns = self._compile_patterns(self.optional_auth_dict)
+
+        # Remove parameterized paths from literal dicts (they're now in pattern lists)
+        self._remove_parameterized_from_dicts()
+
         self.validator = get_user_validator()
         self.settings = get_settings()
 
@@ -94,25 +111,195 @@ class AuthMiddleware(BaseHTTPMiddleware):
             return normalized
         raise ValueError("Invalid type for paths: must be set or dict")
 
+    @staticmethod
+    def _has_parameters(path: str) -> bool:
+        """Check if path contains parameter placeholders like {param:type}"""
+        return "{" in path and "}" in path
+
+    def _compile_path_pattern(self, path: str, is_prefix: bool = False) -> Pattern:
+        """
+        Compile a parameterized path pattern to regex.
+
+        Supports syntax: /path/{param:type}/more
+
+        Types:
+            - uuid: UUID v4 format (case-insensitive)
+
+        Args:
+            path: Path pattern with {param:type} placeholders
+            is_prefix: If True, don't anchor end of pattern (for prefix matching)
+
+        Returns:
+            Compiled regex pattern
+
+        Raises:
+            ValueError: If syntax is invalid or type is unsupported
+
+        Examples:
+            >>> _compile_path_pattern('/api/{id:uuid}')
+            re.compile(r'^/api/[0-9a-f]{8}-...$', re.IGNORECASE)
+
+            >>> _compile_path_pattern('/api/{version:uuid}', is_prefix=True)
+            re.compile(r'^/api/[0-9a-f]{8}-...', re.IGNORECASE)
+        """
+        # Pattern to find parameter placeholders: {param:type}
+        param_pattern = r"\{([^}:]+)(?::([^}]+))?\}"
+
+        def replace_param(match: re.Match) -> str:
+            param_name = match.group(1).strip()
+            param_type = match.group(2).strip() if match.group(2) else None
+
+            if param_type is None:
+                raise ValueError(
+                    f"Parameter '{{{param_name}}}' missing type annotation. "
+                    f"Use {{param:type}} syntax (e.g., {{id:uuid}})"
+                )
+
+            if param_type not in TYPE_PATTERNS:
+                supported = ", ".join(TYPE_PATTERNS.keys())
+                raise ValueError(
+                    f"Unsupported type '{param_type}' for parameter '{{{param_name}}}'. "
+                    f"Supported types: {supported}"
+                )
+
+            return f"({TYPE_PATTERNS[param_type]})"
+
+        # Escape special regex characters in path
+        escaped_path = re.escape(path)
+
+        # Unescape { and } for parameter replacement
+        escaped_path = escaped_path.replace(r"\{", "{").replace(r"\}", "}")
+
+        # Replace parameters with regex patterns
+        regex_pattern = re.sub(param_pattern, replace_param, escaped_path)
+
+        # Anchor pattern
+        if is_prefix:
+            regex_pattern = f"^{regex_pattern}"
+        else:
+            regex_pattern = f"^{regex_pattern}$"
+
+        # Compile with case-insensitive flag for UUIDs
+        try:
+            return re.compile(regex_pattern, re.IGNORECASE)
+        except re.error as e:
+            raise ValueError(f"Failed to compile pattern for path '{path}': {e}")
+
+    def _compile_patterns(
+        self, paths_dict: Dict[str, Optional[Set[str]]], is_prefix: bool = False
+    ) -> List[Tuple[Pattern, Optional[Set[str]]]]:
+        """
+        Extract parameterized paths and compile them to regex patterns.
+
+        Args:
+            paths_dict: Dictionary of paths with optional method restrictions
+            is_prefix: If True, compile as prefix patterns (don't anchor end)
+
+        Returns:
+            List of (compiled_pattern, methods) tuples
+
+        Raises:
+            ValueError: If pattern syntax is invalid or type is unsupported
+        """
+        patterns = []
+
+        for path, methods in paths_dict.items():
+            if self._has_parameters(path):
+                try:
+                    compiled_pattern = self._compile_path_pattern(path, is_prefix)
+                    patterns.append((compiled_pattern, methods))
+                except ValueError as e:
+                    raise ValueError(f"Invalid pattern in path '{path}': {e}")
+
+        return patterns
+
+    def _remove_parameterized_from_dicts(self):
+        """
+        Remove parameterized paths from literal path dictionaries.
+        They are now stored in pattern lists.
+        """
+        for path_dict in [
+            self.excluded_paths_dict,
+            self.excluded_prefixes_dict,
+            self.optional_auth_dict,
+        ]:
+            parameterized_keys = [key for key in path_dict.keys() if self._has_parameters(key)]
+            for key in parameterized_keys:
+                del path_dict[key]
+
     def is_excluded(self, path: str, method: str) -> bool:
-        """Check if path is excluded from authentication for the given method"""
-        # Exact match
+        """
+        Check if path is excluded from authentication for the given method.
+
+        Matching order (highest to lowest priority):
+        1. Exact literal match in excluded_paths
+        2. Parameterized pattern match in excluded_paths
+        3. Prefix literal match in excluded_prefixes
+        4. Prefix pattern match in excluded_prefixes
+
+        Args:
+            path: Request path (e.g., '/api/v1/categories/7b5bcc8f-...')
+            method: HTTP method (e.g., 'GET', 'POST')
+
+        Returns:
+            True if path is excluded from authentication for this method
+        """
+        # 1. Exact literal match (O(1) dict lookup)
         for p, methods in self.excluded_paths_dict.items():
             if path == p and (methods is None or method in methods):
+                logger.debug(f"Exact match excluded: {path} [{method}]")
+                return True
+
+        # 2. Parameterized pattern match (O(n) pattern checks)
+        for pattern, methods in self._excluded_patterns:
+            if pattern.match(path) and (methods is None or method in methods):
+                logger.debug(f"Pattern match excluded: {path} [{method}] via {pattern.pattern}")
                 return True
 
-        # Prefix match
+        # 3. Prefix literal match (O(n) prefix checks)
         for p, methods in self.excluded_prefixes_dict.items():
             if path.startswith(p) and (methods is None or method in methods):
+                logger.debug(f"Prefix match excluded: {path} [{method}]")
+                return True
+
+        # 4. Prefix pattern match (O(n) pattern checks)
+        for pattern, methods in self._excluded_prefix_patterns:
+            # For prefix patterns, check if path starts with pattern match
+            match = pattern.match(path)
+            if match and (methods is None or method in methods):
+                logger.debug(
+                    f"Prefix pattern match excluded: {path} [{method}] via {pattern.pattern}"
+                )
                 return True
 
         return False
 
     def is_optional_auth(self, path: str, method: str) -> bool:
-        """Check if path has optional authentication for the given method"""
+        """
+        Check if path has optional authentication for the given method.
+
+        Checks both literal paths and parameterized patterns.
+
+        Args:
+            path: Request path
+            method: HTTP method
+
+        Returns:
+            True if authentication is optional for this path and method
+        """
+        # Exact literal match
         for p, methods in self.optional_auth_dict.items():
             if (path == p) and (methods is None or method in methods):
                 return True
+
+        # Parameterized pattern match
+        for pattern, methods in self._optional_patterns:
+            if pattern.match(path) and (methods is None or method in methods):
+                logger.debug(
+                    f"Pattern match optional auth: {path} [{method}] via {pattern.pattern}"
+                )
+                return True
+
         return False
 
     async def dispatch(self, request: Request, call_next):