claude-mpm 5.6.23__py3-none-any.whl → 5.6.73__py3-none-any.whl

claude_mpm/auth/oauth_manager.py

@@ -0,0 +1,266 @@
+"""OAuth manager for orchestrating complete OAuth2 authentication flows.
+
+This module provides a high-level interface for OAuth authentication,
+coordinating providers, callback servers, and token storage.
+"""
+
+import webbrowser
+from typing import Optional
+
+from claude_mpm.auth.callback_server import OAuthCallbackServer
+from claude_mpm.auth.models import OAuthToken, StoredToken, TokenMetadata, TokenStatus
+from claude_mpm.auth.providers.base import OAuthProvider
+from claude_mpm.auth.providers.google import GoogleOAuthProvider, OAuthError
+from claude_mpm.auth.token_storage import TokenStorage
+
+# Mapping of provider names to provider classes
+PROVIDERS: dict[str, type[OAuthProvider]] = {
+    "google": GoogleOAuthProvider,
+}
+
+
+class OAuthManager:
+    """High-level OAuth authentication manager.
+
+    Orchestrates the complete OAuth2 flow including authorization,
+    token exchange, storage, refresh, and revocation.
+
+    Attributes:
+        storage: Token storage instance for persisting credentials.
+
+    Example:
+        ```python
+        manager = OAuthManager()
+
+        # Authenticate with Google
+        token = await manager.authenticate(
+            service_name="gmail-mcp",
+            provider_name="google",
+            scopes=["https://www.googleapis.com/auth/gmail.readonly"],
+        )
+
+        # Check token status
+        status, stored = manager.get_status("gmail-mcp")
+        if status == TokenStatus.EXPIRED:
+            token = await manager.refresh_if_needed("gmail-mcp")
+
+        # Revoke when done
+        await manager.revoke("gmail-mcp")
+        ```
+    """
+
+    def __init__(self, storage: Optional[TokenStorage] = None) -> None:
+        """Initialize OAuth manager.
+
+        Args:
+            storage: Token storage instance. Creates default if not provided.
+        """
+        self.storage = storage or TokenStorage()
+
+    def get_provider(self, provider_name: str) -> OAuthProvider:
+        """Get an OAuth provider instance by name.
+
+        Args:
+            provider_name: Name of the provider (e.g., "google").
+
+        Returns:
+            Configured provider instance.
+
+        Raises:
+            ValueError: If provider name is not recognized.
+        """
+        provider_class = PROVIDERS.get(provider_name.lower())
+        if provider_class is None:
+            available = ", ".join(PROVIDERS.keys())
+            raise ValueError(
+                f"Unknown provider: {provider_name}. Available providers: {available}"
+            )
+        return provider_class()
+
+    async def authenticate(
+        self,
+        service_name: str,
+        provider_name: str,
+        scopes: Optional[list[str]] = None,
+        open_browser: bool = True,
+    ) -> OAuthToken:
+        """Perform complete OAuth2 authentication flow.
+
+        This method orchestrates the full OAuth flow:
+        1. Start callback server
+        2. Generate PKCE and state
+        3. Build authorization URL
+        4. Open browser for user authorization
+        5. Wait for callback with authorization code
+        6. Exchange code for tokens
+        7. Store tokens securely
+
+        Args:
+            service_name: Unique identifier for this service/credential.
+            provider_name: Name of the OAuth provider (e.g., "google").
+            scopes: OAuth scopes to request. Uses provider defaults if not specified.
+            open_browser: Whether to automatically open the authorization URL.
+
+        Returns:
+            OAuthToken containing access and refresh tokens.
+
+        Raises:
+            ValueError: If provider is not recognized.
+            OAuthError: If authentication fails at any step.
+        """
+        # Get provider instance
+        provider = self.get_provider(provider_name)
+
+        # Use provider's default scopes if none specified
+        if scopes is None:
+            if hasattr(provider, "DEFAULT_SCOPES"):
+                scopes = provider.DEFAULT_SCOPES
+            else:
+                scopes = []
+
+        # Step 1: Start callback server
+        callback_server = OAuthCallbackServer()
+
+        # Step 2: Generate PKCE and state
+        pkce = OAuthProvider.generate_pkce()
+        state = callback_server.generate_state()
+
+        # Step 3: Build authorization URL
+        auth_url = provider.get_authorization_url(
+            redirect_uri=callback_server.callback_url,
+            scopes=scopes,
+            state=state,
+            code_challenge=pkce.code_challenge,
+        )
+
+        # Step 4: Open browser for user authorization
+        if open_browser:
+            webbrowser.open(auth_url)
+
+        # Step 5: Wait for callback
+        result = await callback_server.wait_for_callback(
+            expected_state=state,
+            timeout=300.0,
+        )
+
+        if not result.success:
+            raise OAuthError(
+                f"Authorization failed: {result.error_description or result.error}",
+                error_code=result.error,
+            )
+
+        if result.code is None:
+            raise OAuthError("No authorization code received")
+
+        # Step 6: Exchange code for tokens
+        token = await provider.exchange_code(
+            code=result.code,
+            redirect_uri=callback_server.callback_url,
+            code_verifier=pkce.code_verifier,
+        )
+
+        # Step 7: Store tokens
+        metadata = TokenMetadata(
+            service_name=service_name,
+            provider=provider_name,
+        )
+        self.storage.store(service_name, token, metadata)
+
+        return token
+
+    async def refresh_if_needed(self, service_name: str) -> Optional[OAuthToken]:
+        """Refresh token if expired or about to expire.
+
+        Checks if the stored token is expired and refreshes it using
+        the refresh token if available.
+
+        Args:
+            service_name: Unique identifier for the service.
+
+        Returns:
+            New OAuthToken if refreshed, existing token if still valid,
+            None if no token exists or refresh failed.
+
+        Raises:
+            OAuthError: If token refresh fails.
+        """
+        stored = self.storage.retrieve(service_name)
+        if stored is None:
+            return None
+
+        # Check if token is still valid (with 60 second buffer)
+        if not stored.token.is_expired():
+            return stored.token
+
+        # Need to refresh
+        if stored.token.refresh_token is None:
+            return None
+
+        # Get provider and refresh
+        provider = self.get_provider(stored.metadata.provider)
+        new_token = await provider.refresh_token(stored.token.refresh_token)
+
+        # Update stored token
+        self.storage.store(service_name, new_token, stored.metadata)
+
+        return new_token
+
+    async def revoke(self, service_name: str) -> bool:
+        """Revoke tokens and delete stored credentials.
+
+        Revokes the token with the OAuth provider and removes
+        the stored credentials.
+
+        Args:
+            service_name: Unique identifier for the service.
+
+        Returns:
+            True if revocation and deletion succeeded, False otherwise.
+        """
+        stored = self.storage.retrieve(service_name)
+        if stored is None:
+            return False
+
+        # Get provider and revoke
+        provider = self.get_provider(stored.metadata.provider)
+
+        # Try to revoke the refresh token first (more thorough)
+        revoked = False
+        if stored.token.refresh_token:
+            revoked = await provider.revoke_token(stored.token.refresh_token)
+
+        # If no refresh token or revocation failed, try access token
+        if not revoked:
+            revoked = await provider.revoke_token(stored.token.access_token)
+
+        # Delete stored credentials regardless of revocation result
+        self.storage.delete(service_name)
+
+        return revoked
+
+    def get_status(
+        self, service_name: str
+    ) -> tuple[TokenStatus, Optional[StoredToken]]:
+        """Get the status of a stored token.
+
+        Args:
+            service_name: Unique identifier for the service.
+
+        Returns:
+            Tuple of (TokenStatus, StoredToken or None).
+        """
+        status = self.storage.get_status(service_name)
+        stored = (
+            self.storage.retrieve(service_name)
+            if status != TokenStatus.MISSING
+            else None
+        )
+        return (status, stored)
+
+    def list_authenticated_services(self) -> list[str]:
+        """List all services with stored tokens.
+
+        Returns:
+            List of service names that have stored credentials.
+        """
+        return self.storage.list_services()

claude_mpm/auth/providers/__init__.py

@@ -0,0 +1,12 @@
+"""OAuth providers for authentication.
+
+This module exports OAuth provider implementations for various services.
+"""
+
+from claude_mpm.auth.providers.base import OAuthProvider
+from claude_mpm.auth.providers.google import GoogleOAuthProvider
+
+__all__ = [
+    "GoogleOAuthProvider",
+    "OAuthProvider",
+]

claude_mpm/auth/providers/base.py

@@ -0,0 +1,165 @@
+"""Abstract base class for OAuth providers.
+
+This module defines the interface that all OAuth providers must implement,
+providing a consistent API for OAuth2 authentication flows with PKCE support.
+"""
+
+import base64
+import hashlib
+import secrets
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+from claude_mpm.auth.models import OAuthToken
+
+
+@dataclass(frozen=True)
+class PKCEChallenge:
+    """PKCE code verifier and challenge pair.
+
+    Attributes:
+        code_verifier: Random string used to generate the challenge.
+        code_challenge: SHA256 hash of the verifier, base64url encoded.
+    """
+
+    code_verifier: str
+    code_challenge: str
+
+
+class OAuthProvider(ABC):
+    """Abstract base class for OAuth2 providers.
+
+    Defines the interface for OAuth authentication flows including
+    authorization URL generation, token exchange, refresh, and revocation.
+    All implementations should support PKCE (Proof Key for Code Exchange).
+
+    Attributes:
+        name: Human-readable name of the OAuth provider.
+        authorization_url: URL for user authorization.
+        token_url: URL for token exchange.
+    """
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Human-readable name of the OAuth provider."""
+        ...
+
+    @property
+    @abstractmethod
+    def authorization_url(self) -> str:
+        """URL for initiating user authorization."""
+        ...
+
+    @property
+    @abstractmethod
+    def token_url(self) -> str:
+        """URL for exchanging authorization code for tokens."""
+        ...
+
+    @abstractmethod
+    def get_authorization_url(
+        self,
+        redirect_uri: str,
+        scopes: list[str],
+        state: str,
+        code_challenge: str,
+    ) -> str:
+        """Build the authorization URL with PKCE support.
+
+        Constructs the full authorization URL including all required
+        parameters for the OAuth2 flow with PKCE.
+
+        Args:
+            redirect_uri: URL to redirect to after authorization.
+            scopes: List of OAuth scopes to request.
+            state: Random state string for CSRF protection.
+            code_challenge: PKCE code challenge (S256 hash of verifier).
+
+        Returns:
+            Complete authorization URL for user redirect.
+        """
+        ...
+
+    @abstractmethod
+    async def exchange_code(
+        self,
+        code: str,
+        redirect_uri: str,
+        code_verifier: str,
+    ) -> OAuthToken:
+        """Exchange authorization code for tokens.
+
+        Completes the OAuth2 flow by exchanging the authorization code
+        for access and refresh tokens.
+
+        Args:
+            code: Authorization code received from the provider.
+            redirect_uri: Same redirect URI used in authorization.
+            code_verifier: PKCE code verifier used to generate the challenge.
+
+        Returns:
+            OAuthToken containing access token and optional refresh token.
+
+        Raises:
+            OAuthError: If token exchange fails.
+        """
+        ...
+
+    @abstractmethod
+    async def refresh_token(self, refresh_token: str) -> OAuthToken:
+        """Refresh an expired access token.
+
+        Uses the refresh token to obtain a new access token without
+        requiring user interaction.
+
+        Args:
+            refresh_token: Valid refresh token from previous authentication.
+
+        Returns:
+            OAuthToken with new access token (may include new refresh token).
+
+        Raises:
+            OAuthError: If token refresh fails or refresh token is invalid.
+        """
+        ...
+
+    @abstractmethod
+    async def revoke_token(self, token: str) -> bool:
+        """Revoke an access or refresh token.
+
+        Invalidates the token with the OAuth provider, preventing
+        further use.
+
+        Args:
+            token: Access token or refresh token to revoke.
+
+        Returns:
+            True if revocation succeeded, False otherwise.
+        """
+        ...
+
+    @staticmethod
+    def generate_pkce() -> PKCEChallenge:
+        """Generate PKCE code verifier and challenge.
+
+        Creates a cryptographically secure code verifier and derives
+        the S256 challenge from it per RFC 7636.
+
+        Returns:
+            PKCEChallenge containing verifier and challenge strings.
+        """
+        # Generate 32 bytes of random data (256 bits)
+        code_verifier_bytes = secrets.token_bytes(32)
+        # Base64url encode without padding
+        code_verifier = (
+            base64.urlsafe_b64encode(code_verifier_bytes).rstrip(b"=").decode("ascii")
+        )
+
+        # Create S256 challenge: BASE64URL(SHA256(code_verifier))
+        challenge_digest = hashlib.sha256(code_verifier.encode("ascii")).digest()
+        code_challenge = (
+            base64.urlsafe_b64encode(challenge_digest).rstrip(b"=").decode("ascii")
+        )
+
+        return PKCEChallenge(code_verifier=code_verifier, code_challenge=code_challenge)

claude_mpm/auth/providers/google.py

@@ -0,0 +1,261 @@
+"""Google OAuth2 provider implementation.
+
+This module provides OAuth2 authentication for Google services including
+Gmail, Calendar, Drive, Docs, and Sheets with PKCE support.
+"""
+
+import os
+from datetime import datetime, timedelta, timezone
+from urllib.parse import urlencode
+
+import aiohttp
+
+from claude_mpm.auth.models import OAuthToken
+from claude_mpm.auth.providers.base import OAuthProvider
+
+
+class OAuthError(Exception):
+    """Exception raised for OAuth-related errors."""
+
+    def __init__(self, message: str, error_code: str | None = None) -> None:
+        """Initialize OAuthError.
+
+        Args:
+            message: Human-readable error message.
+            error_code: Optional OAuth error code from provider.
+        """
+        super().__init__(message)
+        self.error_code = error_code
+
+
+class GoogleOAuthProvider(OAuthProvider):
+    """Google OAuth2 provider with PKCE support.
+
+    Implements OAuth2 authentication for Google services with support
+    for offline access (refresh tokens) and PKCE security.
+
+    Attributes:
+        AUTHORIZATION_ENDPOINT: Google OAuth2 authorization URL.
+        TOKEN_ENDPOINT: Google OAuth2 token exchange URL.
+        REVOKE_ENDPOINT: Google OAuth2 token revocation URL.
+        DEFAULT_SCOPES: Default OAuth scopes for common Google services.
+
+    Environment Variables:
+        GOOGLE_OAUTH_CLIENT_ID: Google OAuth client ID (required).
+        GOOGLE_OAUTH_CLIENT_SECRET: Google OAuth client secret (required).
+    """
+
+    AUTHORIZATION_ENDPOINT = "https://accounts.google.com/o/oauth2/v2/auth"
+    TOKEN_ENDPOINT = "https://oauth2.googleapis.com/token"  # nosec B105 - public OAuth2 endpoint
+    REVOKE_ENDPOINT = "https://oauth2.googleapis.com/revoke"
+
+    DEFAULT_SCOPES: list[str] = [
+        "https://www.googleapis.com/auth/gmail.modify",
+        "https://www.googleapis.com/auth/calendar",
+        "https://www.googleapis.com/auth/drive",
+        "https://www.googleapis.com/auth/documents",
+        "https://www.googleapis.com/auth/spreadsheets",
+    ]
+
+    def __init__(
+        self,
+        client_id: str | None = None,
+        client_secret: str | None = None,
+    ) -> None:
+        """Initialize Google OAuth provider.
+
+        Args:
+            client_id: Google OAuth client ID. Defaults to GOOGLE_OAUTH_CLIENT_ID env var.
+            client_secret: Google OAuth client secret. Defaults to GOOGLE_OAUTH_CLIENT_SECRET env var.
+
+        Raises:
+            ValueError: If client ID or secret is not provided and not in environment.
+        """
+        self._client_id = client_id or os.environ.get("GOOGLE_OAUTH_CLIENT_ID")
+        self._client_secret = client_secret or os.environ.get(
+            "GOOGLE_OAUTH_CLIENT_SECRET"
+        )
+
+        if not self._client_id:
+            raise ValueError(
+                "Google OAuth client ID is required. "
+                "Set GOOGLE_OAUTH_CLIENT_ID environment variable or pass client_id parameter."
+            )
+        if not self._client_secret:
+            raise ValueError(
+                "Google OAuth client secret is required. "
+                "Set GOOGLE_OAUTH_CLIENT_SECRET environment variable or pass client_secret parameter."
+            )
+
+    @property
+    def name(self) -> str:
+        """Human-readable name of the OAuth provider."""
+        return "Google"
+
+    @property
+    def authorization_url(self) -> str:
+        """URL for initiating user authorization."""
+        return self.AUTHORIZATION_ENDPOINT
+
+    @property
+    def token_url(self) -> str:
+        """URL for exchanging authorization code for tokens."""
+        return self.TOKEN_ENDPOINT
+
+    def get_authorization_url(
+        self,
+        redirect_uri: str,
+        scopes: list[str],
+        state: str,
+        code_challenge: str,
+    ) -> str:
+        """Build the Google authorization URL with PKCE support.
+
+        Constructs the authorization URL with offline access and consent
+        prompt to ensure a refresh token is issued.
+
+        Args:
+            redirect_uri: URL to redirect to after authorization.
+            scopes: List of OAuth scopes to request.
+            state: Random state string for CSRF protection.
+            code_challenge: PKCE code challenge (S256 hash of verifier).
+
+        Returns:
+            Complete authorization URL for user redirect.
+        """
+        params = {
+            "client_id": self._client_id,
+            "redirect_uri": redirect_uri,
+            "response_type": "code",
+            "scope": " ".join(scopes),
+            "state": state,
+            "code_challenge": code_challenge,
+            "code_challenge_method": "S256",
+            "access_type": "offline",
+            "prompt": "consent",
+        }
+        return f"{self.AUTHORIZATION_ENDPOINT}?{urlencode(params)}"
+
+    async def exchange_code(
+        self,
+        code: str,
+        redirect_uri: str,
+        code_verifier: str,
+    ) -> OAuthToken:
+        """Exchange authorization code for Google tokens.
+
+        Args:
+            code: Authorization code received from Google.
+            redirect_uri: Same redirect URI used in authorization.
+            code_verifier: PKCE code verifier used to generate the challenge.
+
+        Returns:
+            OAuthToken containing access token and refresh token.
+
+        Raises:
+            OAuthError: If token exchange fails.
+        """
+        data = {
+            "client_id": self._client_id,
+            "client_secret": self._client_secret,
+            "code": code,
+            "code_verifier": code_verifier,
+            "grant_type": "authorization_code",
+            "redirect_uri": redirect_uri,
+        }
+
+        async with aiohttp.ClientSession() as session:
+            async with session.post(
+                self.TOKEN_ENDPOINT,
+                data=data,
+                headers={"Content-Type": "application/x-www-form-urlencoded"},
+            ) as response:
+                result = await response.json()
+
+                if response.status != 200:
+                    error_msg = result.get(
+                        "error_description", result.get("error", "Unknown error")
+                    )
+                    raise OAuthError(
+                        f"Token exchange failed: {error_msg}",
+                        error_code=result.get("error"),
+                    )
+
+                # Calculate expiration time
+                expires_in = result.get("expires_in", 3600)
+                expires_at = datetime.now(timezone.utc) + timedelta(seconds=expires_in)
+
+                return OAuthToken(
+                    access_token=result["access_token"],
+                    refresh_token=result.get("refresh_token"),
+                    expires_at=expires_at,
+                    scopes=result.get("scope", "").split(),
+                    token_type=result.get("token_type", "Bearer"),
+                )
+
+    async def refresh_token(self, refresh_token: str) -> OAuthToken:
+        """Refresh an expired Google access token.
+
+        Args:
+            refresh_token: Valid refresh token from previous authentication.
+
+        Returns:
+            OAuthToken with new access token.
+
+        Raises:
+            OAuthError: If token refresh fails.
+        """
+        data = {
+            "client_id": self._client_id,
+            "client_secret": self._client_secret,
+            "refresh_token": refresh_token,
+            "grant_type": "refresh_token",
+        }
+
+        async with aiohttp.ClientSession() as session:
+            async with session.post(
+                self.TOKEN_ENDPOINT,
+                data=data,
+                headers={"Content-Type": "application/x-www-form-urlencoded"},
+            ) as response:
+                result = await response.json()
+
+                if response.status != 200:
+                    error_msg = result.get(
+                        "error_description", result.get("error", "Unknown error")
+                    )
+                    raise OAuthError(
+                        f"Token refresh failed: {error_msg}",
+                        error_code=result.get("error"),
+                    )
+
+                # Calculate expiration time
+                expires_in = result.get("expires_in", 3600)
+                expires_at = datetime.now(timezone.utc) + timedelta(seconds=expires_in)
+
+                return OAuthToken(
+                    access_token=result["access_token"],
+                    # Google may or may not return a new refresh token
+                    refresh_token=result.get("refresh_token", refresh_token),
+                    expires_at=expires_at,
+                    scopes=result.get("scope", "").split(),
+                    token_type=result.get("token_type", "Bearer"),
+                )
+
+    async def revoke_token(self, token: str) -> bool:
+        """Revoke a Google access or refresh token.
+
+        Args:
+            token: Access token or refresh token to revoke.
+
+        Returns:
+            True if revocation succeeded, False otherwise.
+        """
+        async with aiohttp.ClientSession() as session:
+            async with session.post(
+                self.REVOKE_ENDPOINT,
+                data={"token": token},
+                headers={"Content-Type": "application/x-www-form-urlencoded"},
+            ) as response:
+                # Google returns 200 on success, various error codes on failure
+                return response.status == 200