solace-agent-mesh 1.11.2__py3-none-any.whl → 1.12.0__py3-none-any.whl

solace_agent_mesh/shared/__init__.py

@@ -0,0 +1,14 @@
+"""
+Shared utilities for Solace Agent Mesh.
+
+This module contains utilities used by both gateways and services:
+- API utilities (pagination, responses, auth)
+- Database utilities (repositories, exceptions, helpers)
+- Exception handling
+- Common utilities (timestamps, enums, types)
+
+Architecture:
+- GATEWAYS (http_sse, slack, webhook) import from shared/
+- SERVICES (platform) import from shared/
+- No cross-dependencies between gateways and services
+"""

solace_agent_mesh/shared/api/__init__.py

@@ -0,0 +1,42 @@
+"""
+API utilities for REST endpoints.
+
+Provides:
+- Pagination patterns (PaginationParams, PaginatedResponse, DataResponse)
+- Response utilities (create_data_response, create_paginated_response)
+- Auth utilities (get_current_user)
+
+Note: Error responses are handled by exception_handlers in shared.exceptions
+"""
+
+from .pagination import (
+    PaginationParams,
+    PaginatedResponse,
+    DataResponse,
+    PaginationMeta,
+    Meta,
+    get_pagination_or_default,
+    DEFAULT_PAGE_NUMBER,
+    DEFAULT_PAGE_SIZE,
+    MAX_PAGE_SIZE,
+)
+from .response_utils import (
+    create_data_response,
+    create_paginated_response,
+)
+from .auth_utils import get_current_user
+
+__all__ = [
+    "PaginationParams",
+    "PaginatedResponse",
+    "DataResponse",
+    "PaginationMeta",
+    "Meta",
+    "get_pagination_or_default",
+    "DEFAULT_PAGE_NUMBER",
+    "DEFAULT_PAGE_SIZE",
+    "MAX_PAGE_SIZE",
+    "create_data_response",
+    "create_paginated_response",
+    "get_current_user",
+]

solace_agent_mesh/shared/auth/__init__.py

@@ -0,0 +1,26 @@
+"""
+Authentication and authorization dependencies.
+
+Provides FastAPI dependencies for:
+- User authentication (extracting current user from request)
+- Authorization (scope-based validation)
+- User configuration resolution
+
+Works with both gateways and services.
+"""
+
+from .dependencies import (
+    get_current_user,
+    get_config_resolver,
+    get_user_config,
+    ValidatedUserConfig,
+    ComponentWithAuth,
+)
+
+__all__ = [
+    "get_current_user",
+    "get_config_resolver",
+    "get_user_config",
+    "ValidatedUserConfig",
+    "ComponentWithAuth",
+]

solace_agent_mesh/shared/auth/dependencies.py

@@ -0,0 +1,204 @@
+"""
+Shared authentication dependencies for both gateways and services.
+
+Provides FastAPI dependencies for:
+- User authentication (get_current_user)
+- Authorization/scope validation (ValidatedUserConfig)
+- Config resolution (get_config_resolver, get_user_config)
+
+These work with any component that implements the required interface:
+- get_config_resolver() -> ConfigResolver
+- get_namespace() -> str
+"""
+
+import logging
+from typing import Any, Protocol
+
+from fastapi import Depends, HTTPException, Request, status
+from solace_agent_mesh.common.middleware.config_resolver import ConfigResolver
+
+log = logging.getLogger(__name__)
+
+
+class ComponentWithAuth(Protocol):
+    """
+    Protocol for components that support authentication and authorization.
+
+    Both WebUIBackendComponent (gateway) and PlatformServiceComponent (service)
+    implement this interface.
+    """
+    def get_config_resolver(self) -> ConfigResolver: ...
+    def get_namespace(self) -> str: ...
+
+
+def get_current_user(request: Request) -> dict:
+    """
+    Extract authenticated user from request state.
+
+    The user is set by OAuth middleware during request processing.
+    Works with both gateway and service contexts.
+
+    Args:
+        request: FastAPI Request object
+
+    Returns:
+        Dictionary containing user information (id, email, name, authenticated, etc.)
+
+    Raises:
+        HTTPException: 401 if user is not authenticated
+    """
+    if not hasattr(request.state, "user") or not request.state.user:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Authentication required",
+        )
+    return request.state.user
+
+
+def _get_component_from_context() -> ComponentWithAuth:
+    """
+    Get component instance from either gateway or service context.
+
+    Tries platform service first, then falls back to http_sse gateway.
+
+    Returns:
+        Component instance implementing ComponentWithAuth protocol
+
+    Raises:
+        HTTPException: 503 if no component is available
+    """
+    try:
+        from solace_agent_mesh.services.platform.api.dependencies import platform_component_instance
+        if platform_component_instance is not None:
+            return platform_component_instance
+    except ImportError:
+        pass
+
+    try:
+        from solace_agent_mesh.gateway.http_sse.dependencies import sac_component_instance
+        if sac_component_instance is not None:
+            return sac_component_instance
+    except ImportError:
+        pass
+
+    raise HTTPException(
+        status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+        detail="Component not initialized"
+    )
+
+
+def get_config_resolver() -> ConfigResolver:
+    """
+    Get ConfigResolver from current component context.
+
+    Works with both gateway and service components.
+
+    Returns:
+        ConfigResolver instance for authorization checks
+    """
+    component = _get_component_from_context()
+    return component.get_config_resolver()
+
+
+async def get_user_config(
+    request: Request,
+    user: dict = Depends(get_current_user),
+    config_resolver: ConfigResolver = Depends(get_config_resolver),
+) -> dict[str, Any]:
+    """
+    Get user configuration including profile and permissions.
+
+    Works with both gateway and service components.
+
+    Args:
+        request: FastAPI Request object
+        user: Authenticated user (from get_current_user dependency)
+        config_resolver: ConfigResolver (from get_config_resolver dependency)
+
+    Returns:
+        Dictionary containing user configuration and permissions
+    """
+    component = _get_component_from_context()
+    user_id = user.get("id")
+
+    log.debug(f"get_user_config called for user_id: {user_id}")
+
+    namespace = component.get_namespace()
+
+    app_config = {}
+    if hasattr(component, "component_config"):
+        app_config = getattr(component, "component_config", {}).get("app_config", {})
+
+    gateway_context = {}
+    if hasattr(component, "gateway_id"):
+        gateway_context = {
+            "gateway_id": component.gateway_id,
+            "gateway_app_config": app_config,
+            "request": request,
+        }
+
+    return await config_resolver.resolve_user_config(
+        user_id, gateway_context, app_config
+    )
+
+
+class ValidatedUserConfig:
+    """
+    FastAPI dependency for scope-based authorization.
+
+    Validates that the current user has required scopes before allowing access.
+    Works with both gateways (http_sse) and services (platform).
+
+    Args:
+        required_scopes: List of scope strings required for authorization
+
+    Raises:
+        HTTPException: 403 if user lacks required scopes
+
+    Example:
+        @router.post("/agents")
+        async def create_agent(
+            user_config: dict = Depends(ValidatedUserConfig(["sam:agents:create"])),
+        ):
+            # Only users with sam:agents:create scope can access
+            ...
+    """
+
+    def __init__(self, required_scopes: list[str]):
+        self.required_scopes = required_scopes
+
+    async def __call__(
+        self,
+        request: Request,
+        config_resolver: ConfigResolver = Depends(get_config_resolver),
+        user_config: dict[str, Any] = Depends(get_user_config),
+    ) -> dict[str, Any]:
+        user_id = user_config.get("user_profile", {}).get("id")
+
+        log.debug(
+            f"ValidatedUserConfig called for user_id: {user_id} with required scopes: {self.required_scopes}"
+        )
+
+        if not config_resolver.is_feature_enabled(
+            user_config,
+            {"tool_metadata": {"required_scopes": self.required_scopes}},
+            {},
+        ):
+            log.warning(
+                f"Authorization denied for user '{user_id}'. Required scopes: {self.required_scopes}"
+            )
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail=f"Not authorized. Required scopes: {self.required_scopes}",
+            )
+
+        return user_config
+
+
+__all__ = [
+    "get_current_user",
+    "get_config_resolver",
+    "get_user_config",
+    "ValidatedUserConfig",
+    "ComponentWithAuth",
+]

solace_agent_mesh/shared/auth/middleware.py

@@ -0,0 +1,291 @@
+"""
+OAuth2 authentication middleware for both gateways and services.
+
+Provides reusable OAuth2 token validation middleware that works with any
+component that has OAuth configuration.
+"""
+
+import httpx
+import logging
+from fastapi import Request as FastAPIRequest
+from fastapi.responses import JSONResponse
+from fastapi import status
+
+log = logging.getLogger(__name__)
+
+
+def _extract_access_token(request: FastAPIRequest) -> str:
+    """
+    Extract access token from request (header, session, or query param).
+
+    Args:
+        request: FastAPI request object
+
+    Returns:
+        Access token string if found, None otherwise
+    """
+    auth_header = request.headers.get("Authorization")
+    if auth_header and auth_header.startswith("Bearer "):
+        return auth_header[7:]
+
+    try:
+        if "access_token" in request.session:
+            log.debug("AuthMiddleware: Found token in session.")
+            return request.session["access_token"]
+    except AssertionError:
+        log.debug("AuthMiddleware: Could not access request.session.")
+
+    if "token" in request.query_params:
+        return request.query_params["token"]
+
+    return None
+
+
+async def _validate_token(
+    auth_service_url: str, auth_provider: str, access_token: str
+) -> bool:
+    """
+    Validate token with external OAuth service.
+
+    Args:
+        auth_service_url: Base URL of OAuth service
+        auth_provider: OAuth provider name (azure, google, okta, etc.)
+        access_token: Bearer token to validate
+
+    Returns:
+        True if token is valid, False otherwise
+    """
+    async with httpx.AsyncClient() as client:
+        validation_response = await client.post(
+            f"{auth_service_url}/is_token_valid",
+            json={"provider": auth_provider},
+            headers={"Authorization": f"Bearer {access_token}"},
+        )
+    return validation_response.status_code == 200
+
+
+async def _get_user_info(
+    auth_service_url: str, auth_provider: str, access_token: str
+) -> dict:
+    """
+    Get user info from OAuth service.
+
+    Args:
+        auth_service_url: Base URL of OAuth service
+        auth_provider: OAuth provider name
+        access_token: Bearer token
+
+    Returns:
+        User info dictionary if successful, None otherwise
+    """
+    async with httpx.AsyncClient() as client:
+        userinfo_response = await client.get(
+            f"{auth_service_url}/user_info?provider={auth_provider}",
+            headers={"Authorization": f"Bearer {access_token}"},
+        )
+
+    if userinfo_response.status_code != 200:
+        return None
+
+    return userinfo_response.json()
+
+
+def _extract_user_identifier(user_info: dict) -> str:
+    """Extract user identifier from OAuth user info."""
+    user_identifier = (
+        user_info.get("sub")
+        or user_info.get("client_id")
+        or user_info.get("username")
+        or user_info.get("oid")
+        or user_info.get("preferred_username")
+        or user_info.get("upn")
+        or user_info.get("unique_name")
+        or user_info.get("email")
+        or user_info.get("name")
+        or user_info.get("azp")
+        or user_info.get("user_id")
+    )
+
+    if user_identifier and user_identifier.lower() == "unknown":
+        log.warning("AuthMiddleware: IDP returned 'Unknown' as user identifier. Using fallback.")
+        return "sam_dev_user"
+
+    return user_identifier
+
+
+def _extract_user_details(user_info: dict, user_identifier: str) -> tuple:
+    """Extract email and display name from OAuth user info."""
+    email_from_auth = (
+        user_info.get("email")
+        or user_info.get("preferred_username")
+        or user_info.get("upn")
+        or user_identifier
+    )
+
+    display_name = (
+        user_info.get("name")
+        or user_info.get("given_name", "") + " " + user_info.get("family_name", "")
+        or user_info.get("preferred_username")
+        or user_identifier
+    ).strip()
+
+    return email_from_auth, display_name
+
+
+async def _create_user_state(
+    user_identifier: str, email_from_auth: str, display_name: str
+) -> dict:
+    """Create user state dictionary from OAuth info."""
+    final_user_id = user_identifier or email_from_auth or "sam_dev_user"
+    if not final_user_id or final_user_id.lower() in ["unknown", "null", "none", ""]:
+        final_user_id = "sam_dev_user"
+        log.warning("AuthMiddleware: Had to use fallback user ID due to invalid identifier")
+
+    return {
+        "id": final_user_id,
+        "email": email_from_auth or final_user_id,
+        "name": display_name or final_user_id,
+        "authenticated": True,
+        "auth_method": "oidc",
+    }
+
+
+def create_oauth_middleware(component):
+    """
+    Create OAuth2 authentication middleware for any component (gateway or service).
+
+    Works with any component that has:
+    - external_auth_service_url config
+    - external_auth_provider config
+    - use_authorization config
+
+    Args:
+        component: Component instance (gateway or service)
+
+    Returns:
+        AuthMiddleware class configured for the component
+    """
+
+    class AuthMiddleware:
+        def __init__(self, app, component):
+            self.app = app
+            self.component = component
+
+        async def __call__(self, scope, receive, send):
+            if scope["type"] != "http":
+                await self.app(scope, receive, send)
+                return
+
+            request = FastAPIRequest(scope, receive)
+
+            if not request.url.path.startswith("/api"):
+                await self.app(scope, receive, send)
+                return
+
+            skip_paths = [
+                "/api/v1/config",
+                "/api/v1/auth/callback",
+                "/api/v1/auth/tool/callback",
+                "/api/v1/auth/login",
+                "/api/v1/auth/refresh",
+                "/api/v1/csrf-token",
+                "/health",
+            ]
+
+            if any(request.url.path.startswith(path) for path in skip_paths):
+                await self.app(scope, receive, send)
+                return
+
+            if request.method == "OPTIONS":
+                await self.app(scope, receive, send)
+                return
+
+            use_auth = self.component.get_config("frontend_use_authorization", False)
+
+            if use_auth:
+                if await self._handle_authenticated_request(request, scope, receive, send):
+                    return
+            else:
+                request.state.user = {
+                    "id": "sam_dev_user",
+                    "name": "Sam Dev User",
+                    "email": "sam@dev.local",
+                    "authenticated": True,
+                    "auth_method": "development",
+                }
+                log.debug("AuthMiddleware: Set development user (frontend_use_authorization=false)")
+
+            await self.app(scope, receive, send)
+
+        async def _handle_authenticated_request(self, request, scope, receive, send) -> bool:
+            """
+            Handle authentication for a request.
+
+            Returns:
+                True if an error response was sent (caller should not continue),
+                False if authentication succeeded (caller should proceed with app).
+            """
+            access_token = _extract_access_token(request)
+
+            if not access_token:
+                log.warning("AuthMiddleware: No access token found. Returning 401.")
+                response = JSONResponse(
+                    status_code=status.HTTP_401_UNAUTHORIZED,
+                    content={
+                        "detail": "Not authenticated",
+                        "error_type": "authentication_required",
+                    },
+                )
+                await response(scope, receive, send)
+                return True
+
+            auth_service_url = getattr(self.component, "external_auth_service_url", None)
+            auth_provider = getattr(self.component, "external_auth_provider", "generic")
+
+            if not auth_service_url:
+                log.error("Auth service URL not configured.")
+                response = JSONResponse(
+                    status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                    content={"detail": "Auth service not configured"},
+                )
+                await response(scope, receive, send)
+                return True
+
+            if not await _validate_token(auth_service_url, auth_provider, access_token):
+                log.warning("AuthMiddleware: Token validation failed")
+                response = JSONResponse(
+                    status_code=status.HTTP_401_UNAUTHORIZED,
+                    content={"detail": "Invalid token", "error_type": "invalid_token"},
+                )
+                await response(scope, receive, send)
+                return True
+
+            user_info = await _get_user_info(auth_service_url, auth_provider, access_token)
+            if not user_info:
+                log.warning("AuthMiddleware: Failed to get user info")
+                response = JSONResponse(
+                    status_code=status.HTTP_401_UNAUTHORIZED,
+                    content={"detail": "Could not retrieve user info"},
+                )
+                await response(scope, receive, send)
+                return True
+
+            user_identifier = _extract_user_identifier(user_info)
+            email_from_auth, display_name = _extract_user_details(user_info, user_identifier)
+
+            request.state.user = await _create_user_state(
+                user_identifier, email_from_auth, display_name
+            )
+
+            log.debug(f"AuthMiddleware: Authenticated user: {request.state.user['id']}")
+            return False
+
+    return AuthMiddleware
+
+
+__all__ = [
+    "create_oauth_middleware",
+    "_extract_access_token",
+    "_validate_token",
+    "_get_user_info",
+]

solace_agent_mesh/shared/database/__init__.py

@@ -0,0 +1,20 @@
+"""
+Database utilities for repositories and data access.
+
+Provides:
+- Base repository classes (PaginatedRepository, ValidationMixin)
+- Database exception handlers
+- Database helpers (SimpleJSON type)
+"""
+
+from .base_repository import PaginatedRepository, ValidationMixin
+from .database_exceptions import DatabaseExceptionHandler, DatabaseErrorDecorator
+from .database_helpers import SimpleJSON
+
+__all__ = [
+    "PaginatedRepository",
+    "ValidationMixin",
+    "DatabaseExceptionHandler",
+    "DatabaseErrorDecorator",
+    "SimpleJSON",
+]

solace_agent_mesh/{gateway/http_sse/shared → shared/database}/base_repository.py

@@ -10,7 +10,7 @@ from typing import Any, Generic, TypeVar
 
 from sqlalchemy.orm import Session
 
-from .exceptions import EntityNotFoundError
+from ..exceptions.exceptions import EntityNotFoundError
 
 T = TypeVar("T")
 ModelType = TypeVar("ModelType")

solace_agent_mesh/{gateway/http_sse/shared → shared/database}/database_exceptions.py

@@ -8,7 +8,7 @@ that can be properly handled by the API layer.
 
 from typing import Optional, Dict, List
 from sqlalchemy.exc import IntegrityError, SQLAlchemyError, OperationalError, DatabaseError
-from .exceptions import ValidationError, DataIntegrityError, EntityAlreadyExistsError
+from ..exceptions.exceptions import ValidationError, DataIntegrityError, EntityAlreadyExistsError
 
 
 class DatabaseExceptionHandler:

solace_agent_mesh/{gateway/http_sse/shared → shared/database}/database_helpers.py

@@ -7,7 +7,7 @@ Separated from dependencies.py to avoid circular imports.
 
 import json
 from sqlalchemy import Text, TypeDecorator
-from .exceptions import DataIntegrityError
+from ..exceptions.exceptions import DataIntegrityError
 
 
 class SimpleJSON(TypeDecorator):

solace_agent_mesh/shared/exceptions/__init__.py

@@ -0,0 +1,36 @@
+"""
+Exception types and handlers for consistent error handling.
+
+Provides:
+- Business exception types (ValidationError, EntityNotFoundError, etc.)
+- FastAPI exception handlers
+- Error DTOs for API responses
+"""
+
+from .exceptions import (
+    WebUIBackendException,
+    ValidationError,
+    EntityNotFoundError,
+    EntityAlreadyExistsError,
+    BusinessRuleViolationError,
+    ConfigurationError,
+    DataIntegrityError,
+    ExternalServiceError,
+    EntityOperation,
+)
+from .exception_handlers import register_exception_handlers
+from .error_dto import EventErrorDTO
+
+__all__ = [
+    "WebUIBackendException",
+    "ValidationError",
+    "EntityNotFoundError",
+    "EntityAlreadyExistsError",
+    "BusinessRuleViolationError",
+    "ConfigurationError",
+    "DataIntegrityError",
+    "ExternalServiceError",
+    "EntityOperation",
+    "register_exception_handlers",
+    "EventErrorDTO",
+]

solace_agent_mesh/{gateway/http_sse/shared → shared/exceptions}/exception_handlers.py

@@ -193,7 +193,7 @@ def register_exception_handlers(app):
 
     Example:
         from fastapi import FastAPI
-        from solace_agent_mesh.gateway.http_sse.shared.exception_handlers import register_exception_handlers
+        from solace_agent_mesh.shared.exceptions.exception_handlers import register_exception_handlers
 
         app = FastAPI()
         register_exception_handlers(app)