agentsts-core 0.0.2__tar.gz

agentsts_core-0.0.2/.gitignore

@@ -0,0 +1,207 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/

agentsts_core-0.0.2/PKG-INFO

@@ -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/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agentsts-core"
+version = "0.0.2"
+description = "Security Token Service client implementing RFC 8693 OAuth 2.0 Token Exchange"
+requires-python = ">=3.11.0"
+dependencies = [
+  "httpx>=0.25.0",
+  "pydantic>=2.5.0",
+  "typing-extensions>=4.8.0",
+  "cryptography>=41.0.0",  # For JWT handling
+  "PyJWT>=2.8.0",  # For JWT token parsing
+]
+
+[project.optional-dependencies]
+test = [
+  "pytest>=7.0.0",
+  "pytest-asyncio>=0.21.0",
+  "pytest-mock>=3.0.0",
+]
+
+[tool.ruff]
+extend = "../../pyproject.toml"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_default_fixture_loop_scope = "function"
+asyncio_mode = "auto"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agentsts"]

agentsts_core-0.0.2/src/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-0.0.2/src/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-0.0.2/src/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-0.0.2/src/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-0.0.2/src/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-0.0.2/src/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-0.0.2/src/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-0.0.2/src/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-0.0.2/src/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/tests/test_base.py

@@ -0,0 +1,85 @@
+"""Tests for STSIntegrationBase."""
+
+from typing import Any
+from unittest.mock import AsyncMock, Mock, patch
+
+import pytest
+
+from agentsts.core import STSIntegrationBase
+from agentsts.core.client import TokenType
+
+
+class MockSTSIntegration(STSIntegrationBase):
+    """Concrete implementation for testing."""
+
+    def create_auth_credential(self, access_token: str) -> Any:
+        """Create a mock auth credential."""
+        return {"access_token": access_token, "type": "mock"}
+
+
+class TestSTSIntegrationBase:
+    """Test cases for STSIntegrationBase."""
+
+    @pytest.mark.asyncio
+    async def test_exchange_token_success(self):
+        """Test successful token exchange."""
+        well_known_uri = "https://sts.example.com/.well-known/openid_configuration"
+        subject_token = "subject-token-123"
+        expected_access_token = "access-token-456"
+
+        mock_response = Mock()
+        mock_response.access_token = expected_access_token
+
+        with patch("agentsts.core._base.STSClient") as mock_sts_client_class:
+            mock_sts_client = Mock()
+            mock_sts_client.exchange_token = AsyncMock(return_value=mock_response)
+            mock_sts_client_class.return_value = mock_sts_client
+
+            with patch("agentsts.core._base.ActorTokenService"):
+                integration = MockSTSIntegration(well_known_uri)
+
+                result = await integration.exchange_token(subject_token)
+
+                assert result == expected_access_token
+                mock_sts_client.exchange_token.assert_called_once_with(
+                    subject_token=subject_token,
+                    subject_token_type=TokenType.JWT,
+                    actor_token=None,
+                    actor_token_type=None,
+                    resource=None,
+                    audience=None,
+                    scope=None,
+                    requested_token_type=None,
+                    additional_parameters=None,
+                )
+
+    @pytest.mark.asyncio
+    async def test_exchange_token_failure(self):
+        """Test token exchange failure."""
+        well_known_uri = "https://sts.example.com/.well-known/openid_configuration"
+        subject_token = "invalid-token"
+
+        with patch("agentsts.core._base.STSClient") as mock_sts_client_class:
+            mock_sts_client = Mock()
+            mock_sts_client.exchange_token = AsyncMock(side_effect=Exception("Token exchange failed"))
+            mock_sts_client_class.return_value = mock_sts_client
+
+            with patch("agentsts.core._base.ActorTokenService"):
+                integration = MockSTSIntegration(well_known_uri)
+
+                with pytest.raises(Exception, match="Token exchange failed"):
+                    await integration.exchange_token(subject_token)
+
+    def test_concrete_implementation(self):
+        """Test that concrete implementation works correctly."""
+        well_known_uri = "https://sts.example.com/.well-known/openid_configuration"
+
+        with patch("agentsts.core._base.STSClient"):
+            with patch("agentsts.core._base.ActorTokenService"):
+                integration = MockSTSIntegration(well_known_uri)
+
+                # Test that create_auth_credential works
+                access_token = "test-access-token"
+                credential = integration.create_auth_credential(access_token)
+
+                assert credential == {"access_token": access_token, "type": "mock"}

agentsts_core-0.0.2/tests/test_client.py

@@ -0,0 +1,237 @@
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import httpx
+import pytest
+
+from agentsts.core.client import (
+    AuthenticationError,
+    NetworkError,
+    STSClient,
+    STSConfig,
+    TokenExchangeError,
+    TokenType,
+)
+
+
+class MockWellKnownConfig:
+    """Mock well-known configuration for testing."""
+
+    def __init__(self):
+        self.issuer = "https://auth.example.com"
+        self.token_endpoint = "https://auth.example.com/oauth/token"
+        self.token_endpoint_auth_methods_supported = ["client_secret_basic"]
+        self.token_endpoint_auth_signing_alg_values_supported = ["RS256"]
+
+
+@pytest.fixture
+def config():
+    """Create test configuration."""
+    return STSConfig(
+        well_known_uri="https://auth.example.com/.well-known/oauth-authorization-server",
+    )
+
+
+@pytest.fixture
+def mock_well_known_config():
+    """Create mock well-known configuration."""
+    return MockWellKnownConfig()
+
+
+@pytest.mark.asyncio
+async def test_impersonation_token_exchange(config, mock_well_known_config):
+    """Test impersonation token exchange."""
+    with patch("agentsts.core.client._client.fetch_well_known_configuration") as mock_fetch:
+        mock_fetch.return_value = mock_well_known_config
+
+        async with STSClient(config) as client:
+            # Mock successful response
+            with patch.object(client._http_client, "post", new_callable=AsyncMock) as mock_post:
+                mock_response = MagicMock()
+                mock_response.status_code = 200
+                mock_response.json.return_value = {
+                    "access_token": "eyJhbGciOiJFUzI1NiIsImtpZCI6IjcyIn0.eyJhdWQiOiJ1cm46ZXhhbXBsZTpjb29wZXJhdGlvbi1jb250ZXh0IiwiaXNzIjoiaHR0cHM6Ly9hcy5leGFtcGxlLmNvbSIsImV4cCI6MTQ0MTkxMzYxMCwic2NvcGUiOiJzdGF0dXMgZmVlZCIsInN1YiI6InVzZXJAZXhhbXBsZS5uZXQifQ.3paKl9UySKYB5ng6_cUtQ2qlO8Rc_y7Mea7IwEXTcYbNdwG9-G1EKCFe5fW3H0hwX-MSZ49Wpcb1SiAZaOQBtw",
+                    "issued_token_type": "urn:ietf:params:oauth:token-type:jwt",
+                    "token_type": "Bearer",
+                    "expires_in": 3600,
+                }
+                mock_post.return_value = mock_response
+
+                response = await client.impersonate("subject_token")
+
+                assert (
+                    response.access_token
+                    == "eyJhbGciOiJFUzI1NiIsImtpZCI6IjcyIn0.eyJhdWQiOiJ1cm46ZXhhbXBsZTpjb29wZXJhdGlvbi1jb250ZXh0IiwiaXNzIjoiaHR0cHM6Ly9hcy5leGFtcGxlLmNvbSIsImV4cCI6MTQ0MTkxMzYxMCwic2NvcGUiOiJzdGF0dXMgZmVlZCIsInN1YiI6InVzZXJAZXhhbXBsZS5uZXQifQ.3paKl9UySKYB5ng6_cUtQ2qlO8Rc_y7Mea7IwEXTcYbNdwG9-G1EKCFe5fW3H0hwX-MSZ49Wpcb1SiAZaOQBtw"
+                )
+                assert response.issued_token_type == TokenType.JWT
+                assert response.token_type == "Bearer"
+                assert response.expires_in == 3600
+
+
+@pytest.mark.asyncio
+async def test_delegation_token_exchange(config, mock_well_known_config):
+    """Test delegation token exchange."""
+    with patch("agentsts.core.client._client.fetch_well_known_configuration") as mock_fetch:
+        mock_fetch.return_value = mock_well_known_config
+
+        async with STSClient(config) as client:
+            # Mock successful response
+            with patch.object(client._http_client, "post", new_callable=AsyncMock) as mock_post:
+                mock_response = MagicMock()
+                mock_response.status_code = 200
+                mock_response.json.return_value = {
+                    "access_token": "eyJhbGciOiJFUzI1NiIsImtpZCI6IjcyIn0.eyJhdWQiOiJ1cm46ZXhhbXBsZTpjb29wZXJhdGlvbi1jb250ZXh0IiwiaXNzIjoiaHR0cHM6Ly9hcy5leGFtcGxlLmNvbSIsImV4cCI6MTQ0MTkxMzYxMCwic2NvcGUiOiJzdGF0dXMgZmVlZCIsInN1YiI6InVzZXJAZXhhbXBsZS5uZXQiLCJhY3QiOnsic3ViIjoiYWRtaW5AZXhhbXBsZS5uZXQifX0.3paKl9UySKYB5ng6_cUtQ2qlO8Rc_y7Mea7IwEXTcYbNdwG9-G1EKCFe5fW3H0hwX-MSZ49Wpcb1SiAZaOQBtw",
+                    "issued_token_type": "urn:ietf:params:oauth:token-type:jwt",
+                    "token_type": "N_A",
+                    "expires_in": 3600,
+                }
+                mock_post.return_value = mock_response
+
+                response = await client.delegate(
+                    subject_token="subject_token",
+                    subject_token_type=TokenType.JWT,
+                    actor_token="actor_token",
+                    actor_token_type=TokenType.JWT,
+                )
+
+                assert (
+                    response.access_token
+                    == "eyJhbGciOiJFUzI1NiIsImtpZCI6IjcyIn0.eyJhdWQiOiJ1cm46ZXhhbXBsZTpjb29wZXJhdGlvbi1jb250ZXh0IiwiaXNzIjoiaHR0cHM6Ly9hcy5leGFtcGxlLmNvbSIsImV4cCI6MTQ0MTkxMzYxMCwic2NvcGUiOiJzdGF0dXMgZmVlZCIsInN1YiI6InVzZXJAZXhhbXBsZS5uZXQiLCJhY3QiOnsic3ViIjoiYWRtaW5AZXhhbXBsZS5uZXQifX0.3paKl9UySKYB5ng6_cUtQ2qlO8Rc_y7Mea7IwEXTcYbNdwG9-G1EKCFe5fW3H0hwX-MSZ49Wpcb1SiAZaOQBtw"
+                )
+                assert response.issued_token_type == TokenType.JWT
+                assert response.token_type == "N_A"
+                assert response.expires_in == 3600
+
+
+@pytest.mark.asyncio
+async def test_delegation_without_subject_token(config, mock_well_known_config):
+    """Test delegation without identity token raises error."""
+    with patch("agentsts.core.client._client.fetch_well_known_configuration") as mock_fetch:
+        mock_fetch.return_value = mock_well_known_config
+
+        async with STSClient(config) as client:  # No identity token
+            with pytest.raises(AuthenticationError) as exc_info:
+                await client.delegate(
+                    subject_token=None,
+                    subject_token_type=TokenType.JWT,
+                    actor_token="actor_token",
+                    actor_token_type=TokenType.JWT,
+                )
+
+                assert "Subject token required for delegation" in str(exc_info.value)
+
+
+@pytest.mark.asyncio
+async def test_token_exchange_error_response(config, mock_well_known_config):
+    """Test token exchange error response handling."""
+    with patch("agentsts.core.client._client.fetch_well_known_configuration") as mock_fetch:
+        mock_fetch.return_value = mock_well_known_config
+
+        async with STSClient(config) as client:
+            with patch.object(client._http_client, "post", new_callable=AsyncMock) as mock_post:
+                mock_response = MagicMock()
+                mock_response.status_code = 400
+                mock_response.json.return_value = {
+                    "error": "invalid_request",
+                    "error_description": "The request is missing a required parameter",
+                }
+                mock_response.text = "Invalid error response"
+                mock_post.return_value = mock_response
+
+                with pytest.raises(TokenExchangeError) as exc_info:
+                    await client.impersonate("subject_token")
+
+                assert exc_info.value.error == "invalid_request"
+                assert exc_info.value.error_description == "The request is missing a required parameter"
+                assert exc_info.value.status_code == 400
+
+
+@pytest.mark.asyncio
+async def test_network_error(config, mock_well_known_config):
+    """Test network error handling."""
+    with patch("agentsts.core.client._client.fetch_well_known_configuration") as mock_fetch:
+        mock_fetch.return_value = mock_well_known_config
+
+        async with STSClient(config) as client:
+            with patch.object(client._http_client, "post", new_callable=AsyncMock) as mock_post:
+                mock_post.side_effect = httpx.RequestError("Network error")
+
+                with pytest.raises(NetworkError) as exc_info:
+                    await client.impersonate("subject_token")
+
+                assert "Network error during token exchange" in str(exc_info.value)
+
+
+@pytest.mark.asyncio
+async def test_request_data_building(config, mock_well_known_config):
+    """Test that request data is built correctly."""
+    with patch("agentsts.core.client._client.fetch_well_known_configuration") as mock_fetch:
+        mock_fetch.return_value = mock_well_known_config
+
+        async with STSClient(config) as client:
+            with patch.object(client._http_client, "post", new_callable=AsyncMock) as mock_post:
+                mock_response = MagicMock()
+                mock_response.status_code = 200
+                mock_response.json.return_value = {
+                    "access_token": "new_token",
+                    "issued_token_type": "urn:ietf:params:oauth:token-type:jwt",
+                    "token_type": "Bearer",
+                }
+                mock_post.return_value = mock_response
+
+                await client.delegate(
+                    subject_token="subject_token",
+                    subject_token_type=TokenType.JWT,
+                    actor_token="actor_token",
+                    actor_token_type=TokenType.JWT,
+                    audience="https://api.example.com",
+                    scope="read write",
+                )
+
+                # Verify the request was made with correct data
+                mock_post.assert_called_once()
+                call_args = mock_post.call_args
+
+                # Check URL
+                assert call_args[0][0] == "https://auth.example.com/oauth/token"
+
+                # Check data
+                data = call_args[1]["data"]
+                assert data["grant_type"] == "urn:ietf:params:oauth:grant-type:token-exchange"
+                assert data["subject_token"] == "subject_token"
+                assert data["subject_token_type"] == "urn:ietf:params:oauth:token-type:jwt"
+                assert data["actor_token"] == "actor_token"
+                assert data["actor_token_type"] == "urn:ietf:params:oauth:token-type:jwt"
+                assert data["audience"] == "https://api.example.com"
+                assert data["scope"] == "read write"
+
+
+@pytest.mark.asyncio
+async def test_context_manager(config, mock_well_known_config):
+    """Test async context manager functionality."""
+    with patch("agentsts.core.client._client.fetch_well_known_configuration") as mock_fetch:
+        mock_fetch.return_value = mock_well_known_config
+
+        async with STSClient(config) as client:
+            assert client._well_known_config is not None
+            assert client._http_client is not None
+
+        # After context exit, client should be closed
+        assert client._http_client is None
+
+
+@pytest.mark.asyncio
+async def test_manual_initialization_and_close(config, mock_well_known_config):
+    """Test manual initialization and close."""
+    with patch("agentsts.core.client._client.fetch_well_known_configuration") as mock_fetch:
+        mock_fetch.return_value = mock_well_known_config
+
+        client = STSClient(config)
+        assert client._well_known_config is None
+        assert client._http_client is None
+
+        await client._initialize()
+        assert client._well_known_config is not None
+        assert client._http_client is not None
+
+        await client.close()
+        assert client._http_client is None

agentsts_core-0.0.2/tests/test_models.py

@@ -0,0 +1,155 @@
+"""Tests for kagent-sts models."""
+
+import pytest
+from pydantic import ValidationError
+
+from agentsts.core.client import (
+    GrantType,
+    TokenExchangeError,
+    TokenExchangeRequest,
+    TokenExchangeResponse,
+    TokenType,
+    WellKnownConfiguration,
+)
+
+
+class TestTokenExchangeRequest:
+    """Test TokenExchangeRequest model."""
+
+    def test_impersonation_request(self):
+        """Test impersonation request creation."""
+        request = TokenExchangeRequest(subject_token="test_token", subject_token_type=TokenType.JWT)
+
+        assert request.grant_type == GrantType.TOKEN_EXCHANGE
+        assert request.subject_token == "test_token"
+        assert request.subject_token_type == TokenType.JWT
+        assert request.actor_token is None
+        assert request.actor_token_type is None
+        assert request.is_impersonation_request() is True
+        assert request.is_delegation_request() is False
+
+    def test_delegation_request(self):
+        """Test delegation request creation."""
+        request = TokenExchangeRequest(
+            subject_token="test_token",
+            subject_token_type=TokenType.JWT,
+            actor_token="actor_token",
+            actor_token_type=TokenType.JWT,
+        )
+
+        assert request.actor_token == "actor_token"
+        assert request.actor_token_type == TokenType.JWT
+        assert request.is_delegation_request() is True
+        assert request.is_impersonation_request() is False
+
+    def test_actor_token_type_required_with_actor_token(self):
+        """Test that actor_token_type is required when actor_token is provided."""
+        with pytest.raises(ValidationError) as exc_info:
+            TokenExchangeRequest(
+                subject_token="test_token",
+                subject_token_type=TokenType.JWT,
+                actor_token="actor_token",
+                # Missing actor_token_type
+            )
+
+        # Check that the error message is in the validation error
+        error_messages = []
+        for error in exc_info.value.errors():
+            error_messages.append(error["msg"])
+
+        assert any("actor_token_type is required when actor_token is provided" in msg for msg in error_messages)
+
+    def test_optional_parameters(self):
+        """Test optional parameters."""
+        request = TokenExchangeRequest(
+            subject_token="test_token",
+            subject_token_type=TokenType.JWT,
+            resource="https://api.example.com",
+            audience="https://api.example.com",
+            scope="read write",
+            requested_token_type=TokenType.JWT,
+        )
+
+        assert request.resource == "https://api.example.com"
+        assert request.audience == "https://api.example.com"
+        assert request.scope == "read write"
+        assert request.requested_token_type == TokenType.JWT
+
+
+class TestTokenExchangeResponse:
+    """Test TokenExchangeResponse model."""
+
+    def test_successful_response(self):
+        """Test successful response creation."""
+        response = TokenExchangeResponse(
+            access_token="new_token",
+            issued_token_type=TokenType.JWT,
+            token_type="Bearer",
+            expires_in=3600,
+            scope="read write",
+        )
+
+        assert response.access_token == "new_token"
+        assert response.issued_token_type == TokenType.JWT
+        assert response.token_type == "Bearer"
+        assert response.expires_in == 3600
+        assert response.scope == "read write"
+
+    def test_minimal_response(self):
+        """Test minimal response creation."""
+        response = TokenExchangeResponse(access_token="new_token", issued_token_type=TokenType.JWT)
+
+        assert response.access_token == "new_token"
+        assert response.issued_token_type == TokenType.JWT
+        assert response.token_type == "Bearer"  # Default value
+        assert response.expires_in is None
+        assert response.scope is None
+
+
+class TestTokenExchangeError:
+    """Test TokenExchangeError model."""
+
+    def test_error_creation(self):
+        """Test error creation."""
+        error = TokenExchangeError(
+            error="invalid_request", error_description="The request is missing a required parameter"
+        )
+
+        assert error.error == "invalid_request"
+        assert error.error_description == "The request is missing a required parameter"
+
+    def test_minimal_error(self):
+        """Test minimal error creation."""
+        error = TokenExchangeError(error="server_error")
+
+        assert error.error == "server_error"
+        assert error.error_description is None
+
+
+class TestWellKnownConfiguration:
+    """Test WellKnownConfiguration model."""
+
+    def test_configuration_creation(self):
+        """Test configuration creation."""
+        config = WellKnownConfiguration(
+            issuer="https://auth.example.com",
+            token_endpoint="https://auth.example.com/oauth/token",
+            token_endpoint_auth_methods_supported=["client_secret_basic", "client_secret_post"],
+            token_endpoint_auth_signing_alg_values_supported=["RS256", "HS256"],
+        )
+
+        assert config.issuer == "https://auth.example.com"
+        assert config.token_endpoint == "https://auth.example.com/oauth/token"
+        assert "client_secret_basic" in config.token_endpoint_auth_methods_supported
+        assert "RS256" in config.token_endpoint_auth_signing_alg_values_supported
+
+    def test_minimal_configuration(self):
+        """Test minimal configuration creation."""
+        config = WellKnownConfiguration(
+            issuer="https://auth.example.com", token_endpoint="https://auth.example.com/oauth/token"
+        )
+
+        assert config.issuer == "https://auth.example.com"
+        assert config.token_endpoint == "https://auth.example.com/oauth/token"
+        assert config.token_endpoint_auth_methods_supported == []
+        assert config.token_endpoint_auth_signing_alg_values_supported == []