1  """Abstract interface for gateway authentication.
  2  
  3  This module defines the auth interface that enterprise implementations
  4  must follow. The community repo provides only the interface - the actual
  5  OAuth implementation lives in solace-agent-mesh-enterprise.
  6  """
  7  
  8  from abc import ABC, abstractmethod
  9  from typing import Dict, Any
 10  
 11  
 12  class AuthHandler(ABC):
 13      """
 14      Base interface for authentication handlers.
 15  
 16      Enterprise implementations (e.g., SAMOAuth2Handler) implement this interface
 17      to provide OAuth2, API key, or other authentication mechanisms.
 18  
 19      The handler is responsible for:
 20      - Initiating authorization flows (OAuth, API key setup, etc.)
 21      - Handling callbacks from auth providers
 22      - Providing auth headers for outgoing requests
 23      - Managing authentication state
 24      """
 25  
 26      @abstractmethod
 27      async def handle_authorize(self, request: Any) -> Any:
 28          """
 29          Initiate authorization flow.
 30  
 31          For OAuth2, this typically redirects to the OAuth2 service.
 32          For API keys, this might return a setup page.
 33  
 34          Args:
 35              request: Framework-specific request object (FastAPI Request, etc.)
 36  
 37          Returns:
 38              Framework-specific redirect response or dict with redirect_url.
 39              For dict responses, should contain:
 40              - redirect_url: str - URL to redirect to
 41              - status_code: int - HTTP status code (default 302)
 42  
 43          Raises:
 44              Exception: If authorization initiation fails
 45          """
 46          pass
 47  
 48      @abstractmethod
 49      async def handle_callback(self, request: Any) -> Dict[str, Any]:
 50          """
 51          Handle OAuth callback or auth completion.
 52  
 53          For OAuth2, this exchanges authorization codes for tokens.
 54          For API keys, this might process key submission.
 55  
 56          Args:
 57              request: Framework-specific request object with callback params
 58                      (e.g., code, state for OAuth2)
 59  
 60          Returns:
 61              Dictionary with callback result:
 62              - success: bool - Whether auth succeeded
 63              - message: str - Human-readable status message
 64              - (optional) redirect_url: str - URL to redirect to after callback
 65  
 66          Raises:
 67              ValueError: If callback parameters are invalid
 68              Exception: If auth exchange/completion fails
 69          """
 70          pass
 71  
 72      @abstractmethod
 73      async def get_auth_headers(self) -> Dict[str, str]:
 74          """
 75          Get authentication headers for outgoing API requests.
 76  
 77          Returns headers that should be included in HTTP requests to
 78          authenticate with external services.
 79  
 80          Returns:
 81              Dictionary of HTTP headers (e.g., {"Authorization": "Bearer ..."})
 82              Returns empty dict {} if not authenticated or no headers needed.
 83  
 84          Examples:
 85              OAuth2: {"Authorization": "Bearer eyJhbGc..."}
 86              API Key: {"X-API-Key": "sk-..."}
 87              Basic Auth: {"Authorization": "Basic dXNlcjpwYXNz"}
 88          """
 89          pass
 90  
 91      @abstractmethod
 92      async def is_authenticated(self) -> bool:
 93          """
 94          Check if currently authenticated.
 95  
 96          Returns:
 97              True if authenticated with valid credentials, False otherwise.
 98  
 99          Notes:
100              This should check if credentials are present AND valid.
101              For token-based auth, this might check token expiration.
102          """
103          pass