amazon-ads-mcp 0.2.7__py3-none-any.whl

amazon_ads_mcp/auth/oauth_state_store.py

@@ -0,0 +1,277 @@
+"""Secure OAuth state store for CSRF protection."""
+
+import hashlib
+import hmac
+import json
+import logging
+import secrets
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Dict, Optional
+
+from pydantic import BaseModel, Field
+
+logger = logging.getLogger(__name__)
+
+
+class OAuthStateEntry(BaseModel):
+    """OAuth state entry with metadata."""
+
+    state: str = Field(description="OAuth state parameter")
+    nonce: str = Field(description="Random nonce for additional entropy")
+    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    expires_at: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc) + timedelta(minutes=10)
+    )
+    auth_url: str = Field(description="Authorization URL")
+    user_agent: Optional[str] = Field(
+        default=None, description="User agent for validation"
+    )
+    ip_address: Optional[str] = Field(
+        default=None, description="IP address for validation"
+    )
+    completed: bool = Field(default=False, description="Whether callback was received")
+
+
+class OAuthStateStore:
+    """
+    Secure store for OAuth state validation.
+
+    This store provides CSRF protection by:
+    1. Generating cryptographically secure state tokens
+    2. Storing state with expiration and metadata
+    3. Validating state on callback with timing checks
+    4. Using HMAC signatures for state integrity
+
+    For production, this should be replaced with Redis or similar.
+    """
+
+    def __init__(
+        self,
+        secret_key: Optional[str] = None,
+        store_path: Optional[Path] = None,
+    ):
+        """
+        Initialize OAuth state store.
+
+        Args:
+            secret_key: Secret for HMAC signatures (auto-generated if not provided)
+            store_path: Path for persistent storage (memory-only if not provided)
+        """
+        self.secret_key = secret_key or secrets.token_hex(32)
+        self.store_path = store_path
+        self._memory_store: Dict[str, OAuthStateEntry] = {}
+
+        # Load existing states if using file storage
+        if self.store_path:
+            self._load_store()
+
+    def generate_state(
+        self,
+        auth_url: str,
+        user_agent: Optional[str] = None,
+        ip_address: Optional[str] = None,
+        ttl_minutes: int = 10,
+    ) -> str:
+        """
+        Generate a secure OAuth state token.
+
+        Args:
+            auth_url: The authorization URL
+            user_agent: Optional user agent for validation
+            ip_address: Optional IP address for validation
+            ttl_minutes: Time-to-live in minutes
+
+        Returns:
+            Secure state token
+        """
+        # Generate random components
+        state_base = secrets.token_urlsafe(32)
+        nonce = secrets.token_hex(16)
+
+        # Create HMAC signature
+        message = f"{state_base}:{nonce}:{auth_url}"
+        signature = hmac.new(
+            self.secret_key.encode(), message.encode(), hashlib.sha256
+        ).hexdigest()[:16]  # Use first 16 chars for brevity
+
+        # Combine into final state
+        state = f"{state_base}.{signature}"
+
+        # Store state entry
+        entry = OAuthStateEntry(
+            state=state,
+            nonce=nonce,
+            auth_url=auth_url,
+            user_agent=user_agent,
+            ip_address=ip_address,
+            expires_at=datetime.now(timezone.utc) + timedelta(minutes=ttl_minutes),
+        )
+
+        self._memory_store[state] = entry
+        self._save_store()
+
+        logger.debug(f"Generated OAuth state with length: {len(state)}")
+        return state
+
+    def validate_state(
+        self,
+        state: str,
+        user_agent: Optional[str] = None,
+        ip_address: Optional[str] = None,
+    ) -> tuple[bool, Optional[str]]:
+        """
+        Validate an OAuth state token.
+
+        Args:
+            state: The state token to validate
+            user_agent: Optional user agent to verify
+            ip_address: Optional IP address to verify
+
+        Returns:
+            Tuple of (is_valid, error_message)
+        """
+        # Clean expired states first
+        self._clean_expired()
+
+        # Check if state exists
+        if state not in self._memory_store:
+            return False, "Invalid or expired state"
+
+        entry = self._memory_store[state]
+
+        # Check if already used
+        if entry.completed:
+            logger.warning("Attempted reuse of OAuth state")
+            return False, "State already used"
+
+        # Check expiration
+        if datetime.now(timezone.utc) > entry.expires_at:
+            return False, "State expired"
+
+        # Validate HMAC signature
+        try:
+            state_base, signature = state.rsplit(".", 1)
+            message = f"{state_base}:{entry.nonce}:{entry.auth_url}"
+            expected_signature = hmac.new(
+                self.secret_key.encode(), message.encode(), hashlib.sha256
+            ).hexdigest()[:16]
+
+            if not hmac.compare_digest(signature, expected_signature):
+                logger.warning("Invalid OAuth state signature")
+                return False, "Invalid state signature"
+        except (ValueError, KeyError) as e:
+            logger.warning(f"Malformed OAuth state: {e}")
+            return False, "Malformed state"
+
+        # Optional: Validate user agent
+        if entry.user_agent and user_agent and entry.user_agent != user_agent:
+            logger.warning("User agent mismatch in OAuth callback")
+            # Don't fail for user agent changes (browser updates, etc)
+
+        # Optional: Validate IP address
+        if entry.ip_address and ip_address and entry.ip_address != ip_address:
+            logger.warning("IP address mismatch in OAuth callback")
+            # Could be VPN, mobile network change, etc - log but don't fail
+
+        # Mark as completed
+        entry.completed = True
+        self._save_store()
+
+        return True, None
+
+    def get_auth_url(self, state: str) -> Optional[str]:
+        """Get the auth URL for a given state."""
+        entry = self._memory_store.get(state)
+        return entry.auth_url if entry else None
+
+    def _clean_expired(self):
+        """Remove expired state entries."""
+        now = datetime.now(timezone.utc)
+        expired = [
+            state
+            for state, entry in self._memory_store.items()
+            if now > entry.expires_at + timedelta(hours=1)  # Grace period
+        ]
+
+        for state in expired:
+            del self._memory_store[state]
+            logger.debug("Cleaned expired OAuth state")
+
+        if expired:
+            self._save_store()
+
+    def _load_store(self):
+        """Load state store from file."""
+        if not self.store_path or not self.store_path.exists():
+            return
+
+        try:
+            with open(self.store_path, "r") as f:
+                data = json.load(f)
+                for state, entry_data in data.items():
+                    # Parse datetime strings
+                    entry_data["created_at"] = datetime.fromisoformat(
+                        entry_data["created_at"]
+                    )
+                    entry_data["expires_at"] = datetime.fromisoformat(
+                        entry_data["expires_at"]
+                    )
+                    self._memory_store[state] = OAuthStateEntry(**entry_data)
+            logger.debug(
+                f"Loaded {len(self._memory_store)} OAuth states from {self.store_path}"
+            )
+        except Exception as e:
+            logger.warning(f"Could not load OAuth state store: {e}")
+
+    def _save_store(self):
+        """Save state store to file."""
+        if not self.store_path:
+            return
+
+        try:
+            # Ensure directory exists
+            self.store_path.parent.mkdir(parents=True, exist_ok=True)
+
+            # Convert to JSON-serializable format
+            data = {}
+            for state, entry in self._memory_store.items():
+                entry_dict = entry.model_dump()
+                # Convert datetime to ISO format
+                entry_dict["created_at"] = entry_dict["created_at"].isoformat()
+                entry_dict["expires_at"] = entry_dict["expires_at"].isoformat()
+                data[state] = entry_dict
+
+            # Write atomically
+            tmp_path = self.store_path.with_suffix(".tmp")
+            with open(tmp_path, "w") as f:
+                json.dump(data, f, indent=2)
+            tmp_path.replace(self.store_path)
+
+        except Exception as e:
+            logger.warning(f"Could not save OAuth state store: {e}")
+
+
+# Global instance for the application
+_oauth_state_store: Optional[OAuthStateStore] = None
+
+
+def get_oauth_state_store() -> OAuthStateStore:
+    """Get or create the global OAuth state store."""
+    global _oauth_state_store
+    if _oauth_state_store is None:
+        # Use environment variable for secret if available
+        import os
+
+        secret_key = os.getenv("OAUTH_STATE_SECRET")
+
+        # Use file storage in development, memory in production
+        store_path = None
+        if os.getenv("OAUTH_STATE_PERSIST") == "true":
+            store_path = Path.home() / ".amazon_ads_mcp" / "oauth_states.json"
+
+        _oauth_state_store = OAuthStateStore(
+            secret_key=secret_key, store_path=store_path
+        )
+
+    return _oauth_state_store

amazon_ads_mcp/auth/providers/__init__.py

@@ -0,0 +1,14 @@
+"""Authentication providers package.
+
+This package contains implementations of various authentication providers.
+Each provider is automatically registered when imported.
+"""
+
+# Import providers to trigger auto-registration
+from .direct import DirectAmazonAdsProvider
+from .openbridge import OpenBridgeProvider
+
+__all__ = [
+    "DirectAmazonAdsProvider",
+    "OpenBridgeProvider",
+]

amazon_ads_mcp/auth/providers/direct.py

@@ -0,0 +1,393 @@
+"""Direct Amazon Ads API authentication provider.
+
+This module implements direct authentication using Amazon Ads API credentials,
+if you are using your own Amazon Ads API credentials/app.
+"""
+
+import logging
+from datetime import datetime, timedelta, timezone
+from typing import Dict, List, Optional
+
+import httpx
+
+from ...models import AuthCredentials, Identity, Token
+from ...utils.http import get_http_client
+from ..base import BaseAmazonAdsProvider, BaseIdentityProvider, ProviderConfig
+from ..registry import register_provider
+
+logger = logging.getLogger(__name__)
+
+
+@register_provider("direct")
+class DirectAmazonAdsProvider(BaseAmazonAdsProvider, BaseIdentityProvider):
+    """Direct Amazon Ads API authentication provider.
+
+    Provides authentication using Amazon Ads API credentials directly,
+    implementing the "Bring Your Own API" (BYOA) pathway.
+    """
+
+    def __init__(self, config: ProviderConfig):
+        """Initialize direct Amazon Ads provider.
+
+        :param config: Provider configuration with client_id, client_secret, refresh_token
+        :type config: ProviderConfig
+        """
+        self.client_id = config.get("client_id")
+        self.client_secret = config.get("client_secret")
+        self.refresh_token = config.get("refresh_token")
+
+        # Allow missing refresh_token for OAuth flow bootstrapping
+        if not self.client_id or not self.client_secret:
+            raise ValueError(
+                "Direct provider requires 'client_id' and 'client_secret' in config"
+            )
+
+        if not self.refresh_token:
+            logger.warning(
+                "No refresh_token configured. Use OAuth tools to obtain one: "
+                "start_oauth_flow -> visit URL -> check_oauth_status"
+            )
+
+        self.profile_id = config.get("profile_id")
+        self._region = config.get("region", "na")
+        self._access_token: Optional[Token] = None
+
+    @property
+    def provider_type(self) -> str:
+        """
+        Return the provider type identifier.
+
+        :return: Provider type identifier 'direct'
+        :rtype: str
+        """
+        return "direct"
+
+    @property
+    def region(self) -> str:
+        """
+        Get the current region.
+
+        :return: Region code (na, eu, or fe)
+        :rtype: str
+        """
+        return self._region
+
+    async def initialize(self) -> None:
+        """
+        Initialize the provider.
+
+        Performs any asynchronous initialization required for the direct
+        authentication provider.
+
+        :return: None
+        :rtype: None
+        """
+        logger.info(
+            f"Initializing Direct Amazon Ads provider for region {self._region}"
+        )
+
+    async def _get_client(self) -> httpx.AsyncClient:
+        """
+        Get shared HTTP client.
+
+        Retrieves the shared HTTP client instance for making API requests.
+
+        :return: Shared HTTP client instance
+        :rtype: httpx.AsyncClient
+        """
+        return await get_http_client()
+
+    async def get_token(self) -> Token:
+        """
+        Get current access token from Amazon Ads API.
+
+        Retrieves the current access token, first attempting to retrieve
+        from cache, then refreshing if necessary.
+
+        :return: Valid access token
+        :rtype: Token
+        :raises ValueError: If no refresh token is available
+        """
+        # Try to get from AuthManager's token store first
+        auth_manager = None
+        try:
+            from ..manager import get_auth_manager
+
+            auth_manager = get_auth_manager()
+
+            if auth_manager and hasattr(auth_manager, "get_token"):
+                from ..token_store import TokenKind
+
+                token_entry = await auth_manager.get_token(
+                    provider_type="direct",
+                    identity_id="direct-auth",
+                    token_kind=TokenKind.ACCESS,
+                    region=self._region,
+                )
+
+                if token_entry and not token_entry.is_expired():
+                    self._access_token = Token(
+                        value=token_entry.value,
+                        expires_at=token_entry.expires_at,
+                        token_type="Bearer",
+                        metadata=token_entry.metadata,
+                    )
+                    logger.debug("Retrieved access token from unified token store")
+                    return self._access_token
+        except Exception as e:
+            logger.debug(f"Could not get token from store: {e}")
+
+        # Check local cache
+        if self._access_token and await self.validate_token(self._access_token):
+            return self._access_token
+
+        return await self._refresh_access_token()
+
+    async def _refresh_access_token(self) -> Token:
+        """
+        Exchange refresh token for access token via Amazon OAuth2.
+
+        Performs OAuth2 token refresh to obtain a new access token
+        from Amazon's authentication servers.
+
+        :return: New access token with expiration
+        :rtype: Token
+        :raises ValueError: If no refresh token is available or token response is invalid
+        :raises httpx.HTTPError: If the OAuth2 token request fails
+        """
+        # Check if refresh token is available from secure store
+        if not self.refresh_token:
+            try:
+                from ..secure_token_store import get_secure_token_store
+
+                secure_store = get_secure_token_store()
+                token_entry = secure_store.get_token("oauth_refresh_token")
+                if token_entry and token_entry.get("value"):
+                    self.refresh_token = token_entry["value"]
+                    logger.info("Found refresh token in secure store")
+                else:
+                    raise ValueError(
+                        "No refresh token available. Use OAuth tools to obtain one: "
+                        "start_oauth_flow -> visit URL -> check_oauth_status"
+                    )
+            except ImportError:
+                logger.warning("Secure token store not available")
+                raise ValueError(
+                    "No refresh token available. Use OAuth tools to obtain one: "
+                    "start_oauth_flow -> visit URL -> check_oauth_status"
+                )
+            except Exception as e:
+                logger.error(f"Error accessing secure token store: {e}")
+                raise ValueError(
+                    "No refresh token available. Use OAuth tools to obtain one: "
+                    "start_oauth_flow -> visit URL -> check_oauth_status"
+                )
+
+        logger.debug("Exchanging refresh token for Amazon Ads access token")
+
+        client = await self._get_client()
+        auth_endpoint = self.get_oauth_endpoint()
+
+        try:
+            response = await client.post(
+                auth_endpoint,
+                data={
+                    "grant_type": "refresh_token",
+                    "refresh_token": self.refresh_token,
+                    "client_id": self.client_id,
+                    "client_secret": self.client_secret,
+                },
+                headers={"Content-Type": "application/x-www-form-urlencoded"},
+            )
+
+            if response.status_code != 200:
+                logger.error(
+                    f"Token refresh failed: {response.status_code} - {response.text}"
+                )
+                response.raise_for_status()
+
+            data = response.json()
+            access_token = data.get("access_token")
+            expires_in = data.get("expires_in", 3600)
+
+            if not access_token:
+                raise ValueError("No access token in Amazon response")
+
+            expires_at = datetime.now(timezone.utc) + timedelta(seconds=expires_in)
+
+            self._access_token = Token(
+                value=access_token,
+                expires_at=expires_at,
+                token_type="Bearer",
+                metadata={
+                    "client_id": self.client_id,
+                    "region": self._region,
+                },
+            )
+
+            # Store in unified token store
+            try:
+                from ..manager import get_auth_manager
+
+                auth_manager = get_auth_manager()
+
+                if auth_manager and hasattr(auth_manager, "set_token"):
+                    from ..token_store import TokenKind
+
+                    await auth_manager.set_token(
+                        provider_type="direct",
+                        identity_id="direct-auth",
+                        token_kind=TokenKind.ACCESS,
+                        token=access_token,
+                        expires_at=expires_at,
+                        metadata={
+                            "client_id": self.client_id,
+                            "region": self._region,
+                            "token_type": "Bearer",
+                        },
+                        region=self._region,
+                    )
+                    logger.debug("Stored access token in unified token store")
+            except Exception as e:
+                logger.debug(f"Could not store token: {e}")
+
+            logger.debug(f"Amazon Ads access token obtained, expires at {expires_at}")
+            return self._access_token
+
+        except httpx.HTTPError as e:
+            logger.error(f"Failed to refresh Amazon Ads token: {e}")
+            raise
+        except Exception as e:
+            logger.error(f"Error processing Amazon token response: {e}")
+            raise
+
+    async def validate_token(self, token: Token) -> bool:
+        """
+        Validate if token is still valid.
+
+        Checks if the provided token is still valid, considering a 5-minute
+        buffer before expiration to ensure safe usage.
+
+        :param token: Token to validate
+        :type token: Token
+        :return: True if token is valid, False otherwise
+        :rtype: bool
+        """
+        buffer = timedelta(minutes=5)
+        now = datetime.now(timezone.utc)
+        expiry = token.expires_at
+        # Ensure both datetimes are timezone-aware for comparison
+        if expiry.tzinfo is None:
+            expiry = expiry.replace(tzinfo=timezone.utc)
+        return now < (expiry - buffer)
+
+    async def list_identities(self, **kwargs) -> List[Identity]:
+        """
+        List identities for direct auth.
+
+        For direct auth, creates a single synthetic identity
+        representing the authenticated account.
+
+        :param kwargs: Unused filter parameters
+        :type kwargs: Any
+        :return: List containing the single direct auth identity
+        :rtype: List[Identity]
+        """
+        identity = Identity(
+            id="direct-auth",
+            type="amazon_ads_direct",
+            attributes={
+                "name": "Direct Amazon Ads Account",
+                "client_id": self.client_id,
+                "region": self._region,
+                "profile_id": self.profile_id,
+                "auth_method": "direct",
+            },
+        )
+        return [identity]
+
+    async def get_identity(self, identity_id: str) -> Optional[Identity]:
+        """
+        Get specific identity by ID.
+
+        Retrieves the direct auth identity if the ID matches.
+
+        :param identity_id: Identity ID to retrieve
+        :type identity_id: str
+        :return: Identity if ID matches 'direct-auth', None otherwise
+        :rtype: Optional[Identity]
+        """
+        if identity_id == "direct-auth":
+            identities = await self.list_identities()
+            return identities[0]
+        return None
+
+    async def get_identity_credentials(self, identity_id: str) -> AuthCredentials:
+        """
+        Get Amazon Ads credentials for the direct auth identity.
+
+        Retrieves authentication credentials including access token and
+        required headers for API requests.
+
+        :param identity_id: Identity ID (must be 'direct-auth')
+        :type identity_id: str
+        :return: Authentication credentials for Amazon Ads API
+        :rtype: AuthCredentials
+        :raises ValueError: If identity_id is not 'direct-auth'
+        """
+        if identity_id != "direct-auth":
+            raise ValueError(f"Unknown identity: {identity_id}")
+
+        logger.info("Getting credentials for direct Amazon Ads auth")
+
+        token = await self.get_token()
+        headers = await self.get_headers()
+
+        return AuthCredentials(
+            identity_id=identity_id,
+            access_token=token.value,
+            expires_at=token.expires_at,
+            base_url=self.get_region_endpoint(),
+            headers=headers,
+        )
+
+    async def get_headers(self) -> Dict[str, str]:
+        """
+        Get authentication headers for API requests.
+
+        Generates the required headers for Amazon Ads API requests,
+        including Authorization and ClientId headers.
+
+        :return: Dictionary of authentication headers
+        :rtype: Dict[str, str]
+        """
+        # If no refresh token, return minimal headers for OAuth flow
+        if not self.refresh_token:
+            return {
+                "Amazon-Advertising-API-ClientId": self.client_id,
+                # No Authorization header without token
+            }
+
+        token = await self.get_token()
+
+        headers = {
+            "Authorization": f"Bearer {token.value}",
+            "Amazon-Advertising-API-ClientId": self.client_id,
+        }
+
+        # Add profile ID if configured
+        if self.profile_id:
+            headers["Amazon-Advertising-API-Scope"] = self.profile_id
+
+        return headers
+
+    async def close(self) -> None:
+        """
+        Clean up provider resources.
+
+        Clears cached tokens and releases any held resources.
+
+        :return: None
+        :rtype: None
+        """
+        self._access_token = None