agentsts-core 0.0.2__py3-none-any.whl

agentsts/core/__init__.py

@@ -0,0 +1,11 @@
+from ._actor_service import ActorTokenService
+from ._base import STSIntegrationBase
+from .client import STSClient, STSConfig, TokenType
+
+__all__ = [
+    "STSIntegrationBase",
+    "ActorTokenService",
+    "STSClient",
+    "STSConfig",
+    "TokenType",
+]

agentsts/core/_actor_service.py

@@ -0,0 +1,51 @@
+"""Base actor token service for STS integration."""
+
+import logging
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+SERVICE_ACCOUNT_TOKEN_PATH = "/var/run/secrets/kubernetes.io/serviceaccount/token"
+
+
+class ActorTokenService:
+    """Service that loads actor tokens for STS delegation.
+
+    This service provides a simple, synchronous approach for loading actor tokens
+    (like Kubernetes service account tokens) used in STS token exchange.
+    """
+
+    def __init__(self, token_path: Optional[str] = None):
+        """Initialize the actor token service.
+
+        Args:
+            token_path: Path to the token file. Defaults to Kubernetes service account token path.
+        """
+        self.token_path = token_path or SERVICE_ACCOUNT_TOKEN_PATH
+
+    def get_actor_token(self) -> Optional[str]:
+        """Get the actor token for STS delegation.
+
+        This method reads the token from the file each time it's called.
+        If loading fails, it returns None.
+
+        Returns:
+            Actor token string if available, None otherwise
+        """
+        try:
+            logger.debug(f"Loading actor token from {self.token_path}")
+
+            with open(self.token_path, "r", encoding="utf-8") as f:
+                token = f.read().strip()
+
+            if token:
+                logger.info("Successfully loaded actor token'")
+                return token
+            else:
+                logger.warning(f"No actor token found at {self.token_path}")
+                return None
+
+        except Exception as e:
+            logger.error(f"Failed to load actor token': {e}")
+            logger.error(f"Token path: {self.token_path}")
+            return None

agentsts/core/_base.py

@@ -0,0 +1,99 @@
+"""Base classes for framework-specific STS integration."""
+
+import logging
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Optional, Union
+
+from ._actor_service import ActorTokenService
+from .client import STSClient, STSConfig, TokenType
+
+logger = logging.getLogger(__name__)
+
+
+class STSIntegrationBase(ABC):
+    """Base class for framework-specific STS integrations."""
+
+    def __init__(
+        self,
+        well_known_uri: str,
+        service_account_token_path: Optional[str] = None,
+        timeout: int = 30,
+        verify_ssl: bool = True,
+        additional_config: Optional[Dict[str, Any]] = None,
+    ):
+        """Initialize the STS integration.
+
+        Args:
+            well_known_uri: Well-known configuration URI for the STS server
+            timeout: Request timeout in seconds
+            verify_ssl: Whether to verify SSL certificates
+            additional_config: Additional configuration for the specific framework
+        """
+        self.well_known_uri = well_known_uri
+        self.timeout = timeout
+        self.verify_ssl = verify_ssl
+        self.additional_config = additional_config or {}
+
+        # Initialize STS client
+        config = STSConfig(
+            well_known_uri=well_known_uri,
+            timeout=timeout,
+            verify_ssl=verify_ssl,
+        )
+        self.sts_client = STSClient(config)
+        self.access_token = None  # cached access token
+        self._actor_token = ActorTokenService(service_account_token_path).get_actor_token()
+
+    @abstractmethod
+    def create_auth_credential(self, access_token: str) -> Any:
+        """create a framework specific auth credential object from an access token."""
+        pass
+
+    async def exchange_token(
+        self,
+        subject_token: str,
+        subject_token_type: TokenType = TokenType.JWT,
+        actor_token: Optional[str] = None,
+        actor_token_type: Optional[TokenType] = None,
+        resource: Optional[Union[str, list]] = None,
+        audience: Optional[Union[str, list]] = None,
+        scope: Optional[str] = None,
+        requested_token_type: Optional[TokenType] = None,
+        additional_parameters: Optional[Dict[str, Any]] = None,
+    ) -> str:
+        """Exchange token using STS.
+
+        Args:
+            subject_token: The security token representing the identity
+            subject_token_type: Type of the subject token
+            actor_token: The security token representing the identity of the acting party
+            actor_token_type: Type of the actor token
+            resource: The logical name of the target service or resource
+            audience: The logical name of the target service or resource
+            scope: The scope of the requested token
+            requested_token_type: The type of the requested token
+            additional_parameters: Additional parameters for the request
+
+        Returns:
+            Access token
+
+        Raises:
+            TokenExchangeError: If token exchange fails
+        """
+        try:
+            response = await self.sts_client.exchange_token(
+                subject_token=subject_token,
+                subject_token_type=subject_token_type,
+                actor_token=actor_token,
+                actor_token_type=actor_token_type,
+                resource=resource,
+                audience=audience,
+                scope=scope,
+                requested_token_type=requested_token_type,
+                additional_parameters=additional_parameters,
+            )
+            logger.debug(f"Successfully obtained access token for ADK with length: {len(response.access_token)}")
+            return response.access_token
+        except Exception as e:
+            logger.error(f"Token exchange failed: {e}")
+            raise

agentsts/core/client/__init__.py

@@ -0,0 +1,23 @@
+from ._client import STSClient
+from ._config import STSConfig
+from ._exceptions import AuthenticationError, ConfigurationError, NetworkError, STSError, TokenExchangeError
+from ._models import GrantType, TokenExchangeRequest, TokenExchangeResponse, TokenType, WellKnownConfiguration
+from ._models import TokenExchangeError as TokenExchangeErrorModel
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "STSClient",
+    "STSConfig",
+    "STSError",
+    "TokenExchangeError",
+    "ConfigurationError",
+    "AuthenticationError",
+    "NetworkError",
+    "TokenExchangeRequest",
+    "TokenExchangeResponse",
+    "TokenExchangeErrorModel",
+    "TokenType",
+    "GrantType",
+    "WellKnownConfiguration",
+]

agentsts/core/client/_client.py

@@ -0,0 +1,217 @@
+import logging
+from typing import Any, Dict, Optional, Union
+
+import httpx
+
+from ._config import STSConfig
+from ._exceptions import AuthenticationError, NetworkError, TokenExchangeError
+from ._models import TokenExchangeRequest, TokenExchangeResponse, TokenType, WellKnownConfiguration
+from ._utils import fetch_well_known_configuration, parse_token_exchange_error
+
+logger = logging.getLogger(__name__)
+
+
+class STSClient:
+    """Security Token Service client implementing RFC 8693 OAuth 2.0 Token Exchange."""
+
+    def __init__(
+        self,
+        config: STSConfig,
+    ):
+        """
+        Initialize STS client.
+
+        Args:
+            config: STS configuration
+        """
+        self.config = config
+        self._well_known_config: Optional[WellKnownConfiguration] = None
+        self._http_client: Optional[httpx.AsyncClient] = None
+
+    async def __aenter__(self):
+        """Async context manager entry."""
+        await self._initialize()
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        """Async context manager exit."""
+        await self.close()
+
+    async def _initialize(self):
+        """Initialize the client by fetching well-known configuration."""
+        if not self._well_known_config:
+            self._well_known_config = await fetch_well_known_configuration(
+                self.config.well_known_uri, self.config.timeout, self.config.verify_ssl
+            )
+
+        if not self._http_client:
+            self._http_client = httpx.AsyncClient(timeout=self.config.timeout, verify=self.config.verify_ssl)
+
+    async def close(self):
+        """Close the HTTP client."""
+        if self._http_client:
+            await self._http_client.aclose()
+            self._http_client = None
+
+    def _build_request_data(self, request: TokenExchangeRequest) -> Dict[str, Any]:
+        """Build form data for the token exchange request."""
+        data = {
+            "grant_type": request.grant_type.value,
+            "subject_token": request.subject_token,
+            "subject_token_type": request.subject_token_type.value,
+        }
+
+        # Add actor token for delegation requests
+        if request.actor_token:
+            data["actor_token"] = request.actor_token
+            data["actor_token_type"] = request.actor_token_type.value
+
+        # Add optional parameters
+        if request.resource:
+            data["resource"] = request.resource
+        if request.audience:
+            data["audience"] = request.audience
+        if request.scope:
+            data["scope"] = request.scope
+        if request.requested_token_type:
+            data["requested_token_type"] = request.requested_token_type.value
+
+        # Add additional parameters
+        if request.additional_parameters:
+            data.update(request.additional_parameters)
+
+        return data
+
+    async def exchange_token(
+        self,
+        subject_token: str,
+        subject_token_type: TokenType = TokenType.JWT,
+        actor_token: Optional[str] = None,
+        actor_token_type: Optional[TokenType] = None,
+        resource: Optional[Union[str, list]] = None,
+        audience: Optional[Union[str, list]] = None,
+        scope: Optional[str] = None,
+        requested_token_type: Optional[TokenType] = None,
+        additional_parameters: Optional[Dict[str, Any]] = None,
+    ) -> TokenExchangeResponse:
+        """
+        Exchange a token using RFC 8693 OAuth 2.0 Token Exchange.
+
+        Args:
+            subject_token: The security token representing the identity
+            subject_token_type: Type of the subject token
+            actor_token: The security token representing the identity of the acting party
+            actor_token_type: Type of the actor token
+            resource: The logical name of the target service or resource
+            audience: The logical name of the target service or resource
+            scope: The scope of the requested token
+            requested_token_type: The type of the requested token
+            additional_parameters: Additional parameters for the request
+
+        Returns:
+            TokenExchangeResponse containing the issued token
+
+        Raises:
+            TokenExchangeError: If token exchange fails
+            NetworkError: If network operation fails
+        """
+        await self._initialize()
+
+        # Build the request
+        request = TokenExchangeRequest(
+            subject_token=subject_token,
+            subject_token_type=subject_token_type,
+            actor_token=actor_token,
+            actor_token_type=actor_token_type,
+            resource=resource,
+            audience=audience,
+            scope=scope,
+            requested_token_type=requested_token_type,
+            additional_parameters=additional_parameters,
+        )
+
+        # Prepare the request
+        data = self._build_request_data(request)
+
+        try:
+            response = await self._http_client.post(self._well_known_config.token_endpoint, data=data)
+
+            if response.status_code == 200:
+                response_data = response.json()
+                result = TokenExchangeResponse.model_validate(response_data)
+                return result
+            else:
+                # Parse error response
+                try:
+                    response_data = response.json()
+                    error = parse_token_exchange_error(response_data)
+                    raise TokenExchangeError(
+                        error=error.error, error_description=error.error_description, status_code=response.status_code
+                    )
+                except (ValueError, KeyError, TypeError) as e:
+                    response_text = response.text
+                    raise TokenExchangeError(
+                        error="invalid_response",
+                        error_description=f"Invalid error response: {response_text}",
+                        status_code=response.status_code,
+                    ) from e
+
+        except httpx.RequestError as e:
+            raise NetworkError(f"Network error during token exchange: {e}") from e
+
+    async def impersonate(
+        self, subject_token: str, subject_token_type: TokenType = TokenType.JWT, **kwargs
+    ) -> TokenExchangeResponse:
+        """
+        Perform impersonation token exchange (no actor token).
+
+        Args:
+            subject_token: The security token representing the identity to impersonate
+            subject_token_type: Type of the subject token
+            **kwargs: Additional parameters for the token exchange
+
+        Returns:
+            TokenExchangeResponse containing the issued token
+        """
+        try:
+            result = await self.exchange_token(
+                subject_token=subject_token, subject_token_type=subject_token_type, **kwargs
+            )
+            return result
+        except Exception as e:
+            logger.error(f"Exception in impersonate method: {type(e)} - {e}")
+            logger.error(f"Exception args: {e.args}")
+            raise
+
+    async def delegate(
+        self, subject_token: str, subject_token_type: TokenType, actor_token: str, actor_token_type: TokenType, **kwargs
+    ) -> TokenExchangeResponse:
+        """
+        Perform delegation token exchange (with actor token).
+
+        Args:
+            subject_token: The security token representing the identity to delegate
+            subject_token_type: Type of the subject token
+            actor_token: The security token representing the identity of the acting party
+            actor_token_type: Type of the actor token
+            **kwargs: Additional parameters for the token exchange
+
+        Returns:
+            TokenExchangeResponse containing the issued token
+        """
+        if not subject_token:
+            raise AuthenticationError("Subject token required for delegation")
+
+        try:
+            result = await self.exchange_token(
+                subject_token=subject_token,
+                subject_token_type=subject_token_type,
+                actor_token=actor_token,
+                actor_token_type=actor_token_type,
+                **kwargs,
+            )
+            return result
+        except Exception as e:
+            logger.error(f"Exception in delegate method: {type(e)} - {e}")
+            logger.error(f"Exception args: {e.args}")
+            raise

agentsts/core/client/_config.py

@@ -0,0 +1,9 @@
+from pydantic import BaseModel, Field
+
+
+class STSConfig(BaseModel):
+    """Configuration for STS client."""
+
+    well_known_uri: str = Field(..., description="The well-known configuration URI")
+    timeout: int = Field(default=5, description="Request timeout in seconds")
+    verify_ssl: bool = Field(default=True, description="Whether to verify SSL certificates")

agentsts/core/client/_exceptions.py

@@ -0,0 +1,35 @@
+from typing import Optional
+
+
+class STSError(Exception):
+    """Base exception for STS client errors."""
+
+    pass
+
+
+class TokenExchangeError(STSError):
+    """Exception raised when token exchange fails."""
+
+    def __init__(self, error: str, error_description: Optional[str] = None, status_code: Optional[int] = None):
+        self.error = error
+        self.error_description = error_description
+        self.status_code = status_code
+        super().__init__(f"Token exchange failed: {error} - {error_description}")
+
+
+class ConfigurationError(STSError):
+    """Exception raised when STS configuration is invalid."""
+
+    pass
+
+
+class AuthenticationError(STSError):
+    """Exception raised when authentication fails."""
+
+    pass
+
+
+class NetworkError(STSError):
+    """Exception raised when network operations fail."""
+
+    pass

agentsts/core/client/_models.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any, Dict, List, Optional, Union
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+
+class TokenType(str, Enum):
+    """RFC 8693 defined token types."""
+
+    JWT = "urn:ietf:params:oauth:token-type:jwt"
+    SAML2 = "urn:ietf:params:oauth:token-type:saml2"
+    SAML1 = "urn:ietf:params:oauth:token-type:saml1"
+    ID_TOKEN = "urn:ietf:params:oauth:token-type:id_token"
+    ACCESS_TOKEN = "urn:ietf:params:oauth:token-type:access_token"
+
+
+class GrantType(str, Enum):
+    """OAuth 2.0 grant types."""
+
+    TOKEN_EXCHANGE = "urn:ietf:params:oauth:grant-type:token-exchange"
+
+
+class TokenExchangeRequest(BaseModel):
+    """RFC 8693 Token Exchange Request model."""
+
+    grant_type: GrantType = GrantType.TOKEN_EXCHANGE
+    subject_token: str = Field(
+        ...,
+        description="The security token representing the identity of the party on behalf of whom the new token is being requested",
+    )
+    subject_token_type: TokenType = Field(..., description="The type of the subject_token")
+    actor_token: Optional[str] = Field(
+        None, description="The security token representing the identity of the acting party"
+    )
+    actor_token_type: Optional[TokenType] = Field(None, description="The type of the actor_token")
+    resource: Optional[Union[str, List[str]]] = Field(
+        None, description="The logical name of the target service or resource"
+    )
+    audience: Optional[Union[str, List[str]]] = Field(
+        None, description="The logical name of the target service or resource"
+    )
+    scope: Optional[str] = Field(None, description="The scope of the requested token")
+    requested_token_type: Optional[TokenType] = Field(None, description="The type of the requested token")
+    additional_parameters: Optional[Dict[str, Any]] = Field(None, description="Additional parameters for the request")
+
+    @model_validator(mode="after")
+    def actor_token_type_required_with_actor_token(self):
+        if self.actor_token and not self.actor_token_type:
+            raise ValueError("actor_token_type is required when actor_token is provided")
+        return self
+
+    def is_delegation_request(self) -> bool:
+        """Check if this is a delegation request (has actor_token)."""
+        return self.actor_token is not None
+
+    def is_impersonation_request(self) -> bool:
+        """Check if this is an impersonation request (no actor_token)."""
+        return self.actor_token is None
+
+
+class TokenExchangeResponse(BaseModel):
+    """RFC 8693 Token Exchange Response model."""
+
+    access_token: str = Field(..., description="The issued security token")
+    issued_token_type: TokenType = Field(..., description="The type of the issued token")
+    token_type: str = Field(default="Bearer", description="The type of the access token")
+    expires_in: Optional[int] = Field(None, description="The lifetime in seconds of the access token")
+    scope: Optional[str] = Field(None, description="The scope of the access token")
+    refresh_token: Optional[str] = Field(None, description="Refresh token if applicable")
+    additional_parameters: Optional[Dict[str, Any]] = Field(None, description="Additional response parameters")
+
+
+class TokenExchangeError(BaseModel):
+    """RFC 8693 Token Exchange Error model."""
+
+    error: str = Field(..., description="Error code")
+    error_description: Optional[str] = Field(None, description="Human-readable error description")
+    error_uri: Optional[str] = Field(None, description="URI identifying the error")
+    additional_parameters: Optional[Dict[str, Any]] = Field(None, description="Additional error parameters")
+
+
+class WellKnownConfiguration(BaseModel):
+    """OAuth 2.0 Authorization Server Metadata model."""
+
+    issuer: str = Field(..., description="The authorization server's issuer identifier")
+    token_endpoint: str = Field(..., description="The token endpoint URL")
+    token_endpoint_auth_methods_supported: List[str] = Field(default_factory=list)
+    token_endpoint_auth_signing_alg_values_supported: List[str] = Field(default_factory=list)
+    additional_parameters: Optional[Dict[str, Any]] = Field(None, description="Additional configuration parameters")

agentsts/core/client/_utils.py

@@ -0,0 +1,62 @@
+import json
+from typing import Any, Dict
+
+import httpx
+from pydantic import ValidationError
+
+from ._exceptions import ConfigurationError, NetworkError
+from ._exceptions import TokenExchangeError as TokenExchangeException
+from ._models import WellKnownConfiguration
+
+# Protocol constants
+HTTP_PROTOCOL = "http://"
+HTTPS_PROTOCOL = "https://"
+
+
+async def fetch_well_known_configuration(
+    well_known_uri: str, timeout: int = 5, verify_ssl: bool = True
+) -> WellKnownConfiguration:
+    try:
+        async with httpx.AsyncClient(timeout=timeout, verify=verify_ssl) as client:
+            response = await client.get(well_known_uri)
+            response.raise_for_status()
+
+            data = response.json()
+
+            # add protocol to token_endpoint if it's missing
+            if "token_endpoint" in data and not data["token_endpoint"].startswith((HTTP_PROTOCOL, HTTPS_PROTOCOL)):
+                # use the protocol from the well_known_uri
+                if well_known_uri.startswith(HTTPS_PROTOCOL):
+                    protocol = HTTPS_PROTOCOL
+                else:
+                    protocol = HTTP_PROTOCOL
+                data["token_endpoint"] = protocol + data["token_endpoint"]
+
+            config = WellKnownConfiguration.model_validate(data)
+            return config
+
+    except httpx.HTTPStatusError as e:
+        raise NetworkError(f"Failed to fetch well-known configuration: HTTP {e.response.status_code}") from e
+    except httpx.RequestError as e:
+        raise NetworkError(f"Network error fetching well-known configuration: {e}") from e
+    except (json.JSONDecodeError, ValidationError) as e:
+        raise ConfigurationError(f"Invalid well-known configuration response: {e}") from e
+
+
+def parse_token_exchange_error(response_data: Dict[str, Any]) -> TokenExchangeException:
+    """Parse token exchange error response."""
+    return TokenExchangeException(
+        error=response_data.get("error", "unknown_error"),
+        error_description=response_data.get("error_description"),
+    )
+
+
+def extract_jwt_claims(token: str) -> Dict[str, Any]:
+    """Extract claims from a JWT token without verification."""
+    try:
+        import jwt
+
+        # Decode without verification to extract claims
+        return jwt.decode(token, options={"verify_signature": False})
+    except Exception as e:
+        raise ValueError(f"Failed to extract JWT claims: {e}") from e

agentsts_core-0.0.2.dist-info/METADATA

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: agentsts-core
+Version: 0.0.2
+Summary: Security Token Service client implementing RFC 8693 OAuth 2.0 Token Exchange
+Requires-Python: >=3.11.0
+Requires-Dist: cryptography>=41.0.0
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: pydantic>=2.5.0
+Requires-Dist: pyjwt>=2.8.0
+Requires-Dist: typing-extensions>=4.8.0
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'test'
+Requires-Dist: pytest-mock>=3.0.0; extra == 'test'
+Requires-Dist: pytest>=7.0.0; extra == 'test'

agentsts_core-0.0.2.dist-info/RECORD

@@ -0,0 +1,12 @@
+agentsts/core/__init__.py,sha256=Jcy4HnEVedco0WfFdzc6-1DSkMCIKlf3RWtUDeT7Q_Q,253
+agentsts/core/_actor_service.py,sha256=SAgk-E0KwNs0_MxH37d_fWJ99PmYeIcXSTtssKe3lmU,1685
+agentsts/core/_base.py,sha256=qKzKEWoD4TVN8wv4HcO_dRJ2dAho0ndOZ_MsOpSChVA,3751
+agentsts/core/client/__init__.py,sha256=IgYBFJp8aJk-JbYuFgkdIJUsxSX1YLKt3jfhxs_HUwY,688
+agentsts/core/client/_client.py,sha256=Ryko-Y_Rourlrhgc3ygt56gLfc4-sfqN0hP_8g7LZ0I,8297
+agentsts/core/client/_config.py,sha256=x3NrAozxKy2Jel93vNcFDHzyaRFMCyOsHoL4XPwxKE8,365
+agentsts/core/client/_exceptions.py,sha256=giYHNE3m_TI_Am7qY0l9iwIRq7X5MF0x2ZfV0tB4rzM,831
+agentsts/core/client/_models.py,sha256=n_cFmEay-3HTaWbV7xj3JsgRszEEmvbsZwFOtO2ec7A,4237
+agentsts/core/client/_utils.py,sha256=X5b5hQ1PVNCE7sh-bH_7ykX1WkeF_R3HixwXsv5yD94,2386
+agentsts_core-0.0.2.dist-info/METADATA,sha256=j7QAvqExLcJiZENhHqTKq8PGS3V_V1tiFTLm-FdkYeI,506
+agentsts_core-0.0.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+agentsts_core-0.0.2.dist-info/RECORD,,

agentsts_core-0.0.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any