solace-agent-mesh 1.6.1__py3-none-any.whl → 1.13.2__py3-none-any.whl

solace_agent_mesh/common/oauth/oauth_client.py

@@ -0,0 +1,408 @@
+"""Pure OAuth 2.0 protocol implementation.
+
+This module provides stateless OAuth 2.0 flow implementations without any
+caching, retry logic, or domain-specific behavior. It implements the core
+OAuth 2.0 flows as defined in RFC 6749.
+"""
+
+import asyncio
+import logging
+import random
+from typing import Any, Dict, Optional, Union
+
+import httpx
+
+from .utils import calculate_expires_at
+
+logger = logging.getLogger(__name__)
+
+
+class OAuth2Client:
+    """Pure OAuth 2.0 protocol implementation.
+
+    This class provides stateless OAuth 2.0 flow implementations without any
+    caching, retry logic, or domain-specific behavior. Each method makes a
+    single HTTP request to the token endpoint and returns the parsed response.
+
+    All OAuth 2.0 flows follow RFC 6749 specification.
+    """
+
+    async def fetch_client_credentials_token(
+        self,
+        token_url: str,
+        client_id: str,
+        client_secret: str,
+        scope: Optional[str] = None,
+        verify: Union[bool, str] = True,
+        timeout: float = 30.0,
+    ) -> Dict[str, Any]:
+        """Execute OAuth 2.0 Client Credentials flow (RFC 6749 Section 4.4).
+
+        This flow is used for server-to-server authentication where the client
+        acts on its own behalf rather than on behalf of a user.
+
+        Args:
+            token_url: OAuth 2.0 token endpoint URL
+            client_id: OAuth 2.0 client identifier
+            client_secret: OAuth 2.0 client secret
+            scope: Optional space-separated list of scopes
+            verify: SSL certificate verification (True, False, or path to CA bundle)
+            timeout: Request timeout in seconds
+
+        Returns:
+            Token response dictionary containing:
+                - access_token: The access token string
+                - expires_in: Token lifetime in seconds
+                - token_type: Token type (usually "Bearer")
+                - scope: Granted scopes (optional)
+                - expires_at: Unix timestamp when token expires (added by this method)
+
+        Raises:
+            httpx.HTTPStatusError: If the token request fails
+            ValueError: If the response is missing required fields
+        """
+        payload = {
+            "grant_type": "client_credentials",
+            "client_id": client_id,
+            "client_secret": client_secret,
+        }
+
+        if scope:
+            payload["scope"] = scope
+
+        return await self._execute_token_request(
+            token_url=token_url,
+            payload=payload,
+            verify=verify,
+            timeout=timeout,
+        )
+
+    async def fetch_authorization_code_token(
+        self,
+        token_url: str,
+        client_id: str,
+        client_secret: str,
+        code: str,
+        redirect_uri: str,
+        verify: Union[bool, str] = True,
+        timeout: float = 30.0,
+    ) -> Dict[str, Any]:
+        """Execute OAuth 2.0 Authorization Code flow (RFC 6749 Section 4.1).
+
+        This flow is used for user-delegated authentication where the application
+        acts on behalf of a user who has granted permission.
+
+        Args:
+            token_url: OAuth 2.0 token endpoint URL
+            client_id: OAuth 2.0 client identifier
+            client_secret: OAuth 2.0 client secret
+            code: Authorization code received from authorization server
+            redirect_uri: Redirect URI used in authorization request (must match)
+            verify: SSL certificate verification (True, False, or path to CA bundle)
+            timeout: Request timeout in seconds
+
+        Returns:
+            Token response dictionary containing:
+                - access_token: The access token string
+                - expires_in: Token lifetime in seconds
+                - refresh_token: Refresh token for obtaining new access tokens (optional)
+                - token_type: Token type (usually "Bearer")
+                - scope: Granted scopes (optional)
+                - expires_at: Unix timestamp when token expires (added by this method)
+
+        Raises:
+            httpx.HTTPStatusError: If the token request fails
+            ValueError: If the response is missing required fields
+        """
+        payload = {
+            "grant_type": "authorization_code",
+            "code": code,
+            "redirect_uri": redirect_uri,
+            "client_id": client_id,
+            "client_secret": client_secret,
+        }
+
+        return await self._execute_token_request(
+            token_url=token_url,
+            payload=payload,
+            verify=verify,
+            timeout=timeout,
+        )
+
+    async def fetch_refresh_token(
+        self,
+        token_url: str,
+        client_id: str,
+        client_secret: str,
+        refresh_token: str,
+        scope: Optional[str] = None,
+        verify: Union[bool, str] = True,
+        timeout: float = 30.0,
+    ) -> Dict[str, Any]:
+        """Execute OAuth 2.0 Refresh Token flow (RFC 6749 Section 6).
+
+        This flow is used to obtain a new access token using a refresh token,
+        without requiring user interaction.
+
+        Args:
+            token_url: OAuth 2.0 token endpoint URL
+            client_id: OAuth 2.0 client identifier
+            client_secret: OAuth 2.0 client secret
+            refresh_token: The refresh token
+            scope: Optional space-separated list of scopes (must not exceed original grant)
+            verify: SSL certificate verification (True, False, or path to CA bundle)
+            timeout: Request timeout in seconds
+
+        Returns:
+            Token response dictionary containing:
+                - access_token: The new access token string
+                - expires_in: Token lifetime in seconds
+                - refresh_token: New refresh token (optional, may be same as input)
+                - token_type: Token type (usually "Bearer")
+                - scope: Granted scopes (optional)
+                - expires_at: Unix timestamp when token expires (added by this method)
+
+        Raises:
+            httpx.HTTPStatusError: If the token request fails
+            ValueError: If the response is missing required fields
+        """
+        payload = {
+            "grant_type": "refresh_token",
+            "refresh_token": refresh_token,
+            "client_id": client_id,
+            "client_secret": client_secret,
+        }
+
+        if scope:
+            payload["scope"] = scope
+
+        return await self._execute_token_request(
+            token_url=token_url,
+            payload=payload,
+            verify=verify,
+            timeout=timeout,
+        )
+
+    async def _execute_token_request(
+        self,
+        token_url: str,
+        payload: Dict[str, str],
+        verify: Union[bool, str],
+        timeout: float,
+    ) -> Dict[str, Any]:
+        """Execute a token request to the OAuth 2.0 token endpoint.
+
+        This is the core HTTP operation shared by all OAuth flows.
+
+        Args:
+            token_url: OAuth 2.0 token endpoint URL
+            payload: Request payload (grant-specific parameters)
+            verify: SSL certificate verification
+            timeout: Request timeout in seconds
+
+        Returns:
+            Token response dictionary with added expires_at field
+
+        Raises:
+            httpx.HTTPStatusError: If the token request fails
+            ValueError: If the response is missing required fields
+        """
+        headers = {
+            "Content-Type": "application/x-www-form-urlencoded",
+            "Accept": "application/json",
+        }
+
+        async with httpx.AsyncClient(verify=verify) as client:
+            response = await client.post(
+                token_url,
+                data=payload,
+                headers=headers,
+                timeout=timeout,
+            )
+            response.raise_for_status()
+
+            token_data = response.json()
+
+            # Validate response contains required fields
+            if "access_token" not in token_data:
+                raise ValueError(
+                    f"Token response missing 'access_token' field. "
+                    f"Response keys: {list(token_data.keys())}"
+                )
+
+            # Add expiration timestamp for convenience
+            expires_in = token_data.get("expires_in", 3600)  # Default 1 hour
+            token_data["expires_at"] = calculate_expires_at(expires_in)
+
+            return token_data
+
+
+class OAuth2RetryClient:
+    """OAuth 2.0 client with configurable retry logic.
+
+    This class wraps OAuth2Client and adds retry logic with exponential backoff
+    for handling transient failures. Retry behavior:
+    - 4xx errors (client errors): No retry - fail immediately
+    - 5xx errors (server errors): Retry with exponential backoff
+    - Network errors: Retry with exponential backoff
+    """
+
+    def __init__(
+        self,
+        max_retries: int = 0,
+        backoff_base: float = 2.0,
+        backoff_jitter: bool = True,
+    ):
+        """Initialize the retry client.
+
+        Args:
+            max_retries: Maximum number of retry attempts (0 = no retries)
+            backoff_base: Base for exponential backoff (delay = base^attempt)
+            backoff_jitter: Whether to add random jitter to backoff delay
+        """
+        self._base_client = OAuth2Client()
+        self._max_retries = max_retries
+        self._backoff_base = backoff_base
+        self._backoff_jitter = backoff_jitter
+
+    async def fetch_client_credentials_token(
+        self,
+        token_url: str,
+        client_id: str,
+        client_secret: str,
+        scope: Optional[str] = None,
+        verify: Union[bool, str] = True,
+        timeout: float = 30.0,
+    ) -> Dict[str, Any]:
+        """Execute Client Credentials flow with retry logic.
+
+        See OAuth2Client.fetch_client_credentials_token for parameter details.
+        """
+        return await self._execute_with_retry(
+            self._base_client.fetch_client_credentials_token,
+            token_url=token_url,
+            client_id=client_id,
+            client_secret=client_secret,
+            scope=scope,
+            verify=verify,
+            timeout=timeout,
+        )
+
+    async def fetch_authorization_code_token(
+        self,
+        token_url: str,
+        client_id: str,
+        client_secret: str,
+        code: str,
+        redirect_uri: str,
+        verify: Union[bool, str] = True,
+        timeout: float = 30.0,
+    ) -> Dict[str, Any]:
+        """Execute Authorization Code flow with retry logic.
+
+        See OAuth2Client.fetch_authorization_code_token for parameter details.
+        """
+        return await self._execute_with_retry(
+            self._base_client.fetch_authorization_code_token,
+            token_url=token_url,
+            client_id=client_id,
+            client_secret=client_secret,
+            code=code,
+            redirect_uri=redirect_uri,
+            verify=verify,
+            timeout=timeout,
+        )
+
+    async def fetch_refresh_token(
+        self,
+        token_url: str,
+        client_id: str,
+        client_secret: str,
+        refresh_token: str,
+        scope: Optional[str] = None,
+        verify: Union[bool, str] = True,
+        timeout: float = 30.0,
+    ) -> Dict[str, Any]:
+        """Execute Refresh Token flow with retry logic.
+
+        See OAuth2Client.fetch_refresh_token for parameter details.
+        """
+        return await self._execute_with_retry(
+            self._base_client.fetch_refresh_token,
+            token_url=token_url,
+            client_id=client_id,
+            client_secret=client_secret,
+            refresh_token=refresh_token,
+            scope=scope,
+            verify=verify,
+            timeout=timeout,
+        )
+
+    async def _execute_with_retry(self, func, **kwargs) -> Dict[str, Any]:
+        """Execute a function with retry logic.
+
+        Args:
+            func: Async function to execute
+            **kwargs: Arguments to pass to the function
+
+        Returns:
+            Result from the function
+
+        Raises:
+            Exception: Last exception if all retries are exhausted
+        """
+        last_exception = None
+
+        for attempt in range(self._max_retries + 1):
+            try:
+                return await func(**kwargs)
+
+            except httpx.HTTPStatusError as e:
+                last_exception = e
+                # Don't retry on 4xx errors (client errors)
+                if 400 <= e.response.status_code < 500:
+                    logger.error(
+                        "OAuth token request failed with client error %d: %s",
+                        e.response.status_code,
+                        e.response.text,
+                    )
+                    raise
+
+                logger.warning(
+                    "OAuth token request failed with status %d (attempt %d/%d): %s",
+                    e.response.status_code,
+                    attempt + 1,
+                    self._max_retries + 1,
+                    e.response.text,
+                )
+
+            except httpx.RequestError as e:
+                last_exception = e
+                logger.warning(
+                    "OAuth token request failed (attempt %d/%d): %s",
+                    attempt + 1,
+                    self._max_retries + 1,
+                    str(e),
+                )
+
+            except Exception as e:
+                last_exception = e
+                logger.error("Unexpected error during OAuth token fetch: %s", str(e))
+                raise
+
+            # Exponential backoff with optional jitter
+            if attempt < self._max_retries:
+                delay = self._backoff_base**attempt
+                if self._backoff_jitter:
+                    delay += random.uniform(0, 1)
+                logger.info("Retrying OAuth token request in %.2f seconds", delay)
+                await asyncio.sleep(delay)
+
+        # All retries exhausted
+        logger.error(
+            "OAuth token request failed after %d attempts", self._max_retries + 1
+        )
+        if last_exception:
+            raise last_exception
+        else:
+            raise RuntimeError("OAuth token request failed after all retries")

solace_agent_mesh/common/oauth/utils.py

@@ -0,0 +1,50 @@
+"""Utility functions for OAuth 2.0 operations."""
+
+import time
+from urllib.parse import urlparse
+
+
+def validate_https_url(url: str) -> None:
+    """Validate that a URL uses HTTPS scheme.
+
+    OAuth 2.0 requires HTTPS for security when transmitting credentials.
+
+    Args:
+        url: The URL to validate
+
+    Raises:
+        ValueError: If the URL does not use HTTPS scheme
+    """
+    parsed_url = urlparse(url)
+    if parsed_url.scheme != "https":
+        raise ValueError(
+            f"OAuth 2.0 URLs must use HTTPS for security. "
+            f"Got scheme: {parsed_url.scheme}"
+        )
+
+
+def calculate_expires_at(expires_in: int) -> float:
+    """Calculate expiration timestamp from expires_in seconds.
+
+    Args:
+        expires_in: Number of seconds until token expires
+
+    Returns:
+        Unix timestamp (float) when the token will expire
+    """
+    return time.time() + expires_in
+
+
+def is_token_expired(expires_at: float, buffer_seconds: int = 0) -> bool:
+    """Check if a token is expired or will expire within buffer time.
+
+    Args:
+        expires_at: Unix timestamp when token expires
+        buffer_seconds: Optional buffer to consider token expired early
+                       (useful for proactive refresh)
+
+    Returns:
+        True if token is expired or within buffer time of expiring
+    """
+    current_time = time.time()
+    return current_time >= (expires_at - buffer_seconds)

solace_agent_mesh/common/rag_dto.py

@@ -0,0 +1,156 @@
+"""
+Pydantic models for RAG (Retrieval-Augmented Generation) metadata.
+Handles automatic conversion between snake_case (backend) and camelCase (frontend).
+
+This module is placed in common/ to be shared across different components
+(agent tools, gateway, etc.) without creating cross-layer dependencies.
+"""
+
+from typing import Any, Dict, List, Optional
+from pydantic import BaseModel, Field
+
+
+class RAGSourceResponse(BaseModel):
+    """Schema for RAG source with automatic snake_case to camelCase conversion"""
+    citation_id: str = Field(..., alias="citationId", description="Unique citation ID")
+    file_id: Optional[str] = Field(None, alias="fileId", description="File identifier")
+    filename: Optional[str] = Field(None, description="Filename or title")
+    title: Optional[str] = Field(None, description="Source title")
+    source_type: Optional[str] = Field(None, alias="sourceType", description="Type of source (web, kb, etc.)")
+    source_url: Optional[str] = Field(None, alias="sourceUrl", description="Source URL")
+    url: Optional[str] = Field(None, description="Alternative URL field")
+    content_preview: str = Field(..., alias="contentPreview", description="Preview of content")
+    relevance_score: float = Field(..., alias="relevanceScore", description="Relevance score (0-1)")
+    retrieved_at: Optional[str] = Field(None, alias="retrievedAt", description="Timestamp when retrieved")
+    metadata: Dict[str, Any] = Field(default_factory=dict, description="Additional metadata")
+    
+    class Config:
+        from_attributes = True
+        populate_by_name = True  # Accept both snake_case and camelCase
+        by_alias = True  # Serialize using aliases (camelCase)
+
+
+class RAGQueryInfo(BaseModel):
+    """Schema for query information in RAG metadata"""
+    query: str = Field(..., description="Search query")
+    timestamp: str = Field(..., description="Query timestamp")
+    source_citation_ids: List[str] = Field(..., alias="sourceCitationIds", description="Citation IDs for this query")
+    
+    class Config:
+        populate_by_name = True
+        by_alias = True
+
+
+class RAGMetadata(BaseModel):
+    """Schema for RAG metadata"""
+    queries: Optional[List[RAGQueryInfo]] = Field(None, description="Query breakdown for timeline")
+    
+    class Config:
+        populate_by_name = True
+        by_alias = True
+        extra = "allow"  # Allow additional fields
+
+
+class RAGSearchResultResponse(BaseModel):
+    """Schema for RAG search result with automatic snake_case to camelCase conversion"""
+    query: str = Field(..., description="Search query")
+    title: Optional[str] = Field(None, description="Human-readable title for the research (generated by LLM)")
+    search_type: str = Field(..., alias="searchType", description="Type of search (file_search, kb_search, deep_research, web_search)")
+    turn_number: Optional[int] = Field(None, alias="turnNumber", description="Turn number for citation tracking")
+    timestamp: str = Field(..., description="Search timestamp")
+    sources: List[RAGSourceResponse] = Field(default_factory=list, description="List of sources")
+    task_id: Optional[str] = Field(None, alias="taskId", description="Associated task ID")
+    metadata: Optional[RAGMetadata] = Field(None, description="Additional metadata")
+    
+    class Config:
+        from_attributes = True
+        populate_by_name = True
+        by_alias = True
+
+
+def create_rag_source(
+    citation_id: str,
+    content_preview: str,
+    relevance_score: float,
+    file_id: Optional[str] = None,
+    filename: Optional[str] = None,
+    title: Optional[str] = None,
+    source_type: Optional[str] = None,
+    source_url: Optional[str] = None,
+    url: Optional[str] = None,
+    retrieved_at: Optional[str] = None,
+    metadata: Optional[Dict[str, Any]] = None
+) -> Dict[str, Any]:
+    """
+    Helper function to create a RAG source dict that will be automatically
+    converted to camelCase when serialized through RAGSourceResponse.
+    
+    Returns a dict that can be passed to RAGSourceResponse for serialization.
+    """
+    source = RAGSourceResponse(
+        citation_id=citation_id,
+        file_id=file_id,
+        filename=filename,
+        title=title,
+        source_type=source_type,
+        source_url=source_url,
+        url=url,
+        content_preview=content_preview,
+        relevance_score=relevance_score,
+        retrieved_at=retrieved_at,
+        metadata=metadata or {}
+    )
+    return source.model_dump(by_alias=True)
+
+
+def create_rag_search_result(
+    query: str,
+    search_type: str,
+    timestamp: str,
+    sources: List[Dict[str, Any]],
+    task_id: Optional[str] = None,
+    turn_number: Optional[int] = None,
+    metadata: Optional[Dict[str, Any]] = None,
+    title: Optional[str] = None
+) -> Dict[str, Any]:
+    """
+    Helper function to create a RAG search result dict that will be automatically
+    converted to camelCase when serialized through RAGSearchResultResponse.
+    
+    Args:
+        query: Search query
+        search_type: Type of search (file_search, kb_search, deep_research, web_search)
+        timestamp: Search timestamp
+        sources: List of source dicts (will be converted to RAGSourceResponse)
+        task_id: Optional task ID
+        turn_number: Optional turn number
+        metadata: Optional metadata dict
+        title: Optional human-readable title (generated by LLM for deep research)
+    
+    Returns a dict with camelCase keys ready for frontend consumption.
+    """
+    # Convert source dicts to RAGSourceResponse for proper serialization
+    source_responses = [RAGSourceResponse(**src) for src in sources]
+    
+    # Create metadata if provided
+    rag_metadata = None
+    if metadata:
+        # Convert queries if present
+        if "queries" in metadata:
+            query_infos = [RAGQueryInfo(**q) for q in metadata["queries"]]
+            rag_metadata = RAGMetadata(queries=query_infos, **{k: v for k, v in metadata.items() if k != "queries"})
+        else:
+            rag_metadata = RAGMetadata(**metadata)
+    
+    result = RAGSearchResultResponse(
+        query=query,
+        title=title,
+        search_type=search_type,
+        timestamp=timestamp,
+        sources=source_responses,
+        task_id=task_id,
+        turn_number=turn_number,
+        metadata=rag_metadata
+    )
+    
+    return result.model_dump(by_alias=True)