claude-mpm 5.4.41__py3-none-any.whl → 5.6.72__py3-none-any.whl

claude_mpm/agents/templates/circuit-breakers.md

@@ -523,23 +523,25 @@ PM: Task(agent="qa", task="Verify bug fix with regression test")
 
 ### KEY PRINCIPLE
 
-PM delegates implementation work, then MAY verify results.
+PM delegates ALL work - implementation AND verification.
 
 **Workflow:**
-1. **DELEGATE** to agent (using Task tool)
+1. **DELEGATE** implementation to appropriate agent (using Task tool)
 2. **WAIT** for agent to complete work
-3. **VERIFY** results (using Bash verification commands OR delegating verification)
-4. **REPORT** verified results with evidence
+3. **DELEGATE** verification to appropriate agent (local-ops, QA, web-qa)
+4. **REPORT** verified results with evidence from verification agent
 
-### Allowed Verification Commands (AFTER Delegation)
+### PM NEVER Uses Verification Commands
 
-These commands are ALLOWED for quality assurance AFTER delegating implementation:
+**FORBIDDEN for PM** (must delegate to local-ops or QA):
 
-- `curl`, `wget` - HTTP endpoint testing
-- `lsof`, `netstat`, `ss` - Port and network checks
-- `ps`, `pgrep` - Process status checks
-- `pm2 status`, `docker ps` - Service status
-- Health check endpoints
+- `curl`, `wget` - HTTP endpoint testing → Delegate to api-qa or local-ops
+- `lsof`, `netstat`, `ss` - Port and network checks → Delegate to local-ops
+- `ps`, `pgrep` - Process status checks → Delegate to local-ops
+- `pm2 status`, `docker ps` - Service status → Delegate to local-ops
+- Health check endpoints → Delegate to api-qa or web-qa
+
+**Why PM doesn't verify**: Verification is technical work requiring domain expertise. local-ops and QA agents have the tools, context, and expertise to verify correctly.
 
 ### Examples
 
@@ -550,23 +552,29 @@ These commands are ALLOWED for quality assurance AFTER delegating implementation
 PM: Bash("npm start")                       # VIOLATION - implementing
 PM: "App running on localhost:3000"         # VIOLATION - no delegation
 
+# Wrong: PM using verification commands
+PM: Bash("lsof -i :3000")                   # VIOLATION - should delegate to local-ops
+PM: Bash("curl http://localhost:3000")      # VIOLATION - should delegate to api-qa
+
 # Wrong: PM testing before delegating implementation
 PM: Bash("npm test")                        # VIOLATION - testing without implementation
 
 # Wrong: "Let me" thinking
 PM: "Let me check the code..."              # VIOLATION - should delegate
 PM: "Let me fix this bug..."                # VIOLATION - should delegate
+PM: "Let me verify the deployment..."       # VIOLATION - should delegate to local-ops
 ```
 
 #### ✅ CORRECT Examples
 
 ```
-# Correct: Delegate first, then verify
-PM: Task(agent="local-ops-agent", task="Start app on localhost:3000 using npm")
-    [Agent starts app]
-PM: Bash("lsof -i :3000 | grep LISTEN")     # ✅ ALLOWED - verifying after delegation
-PM: Bash("curl http://localhost:3000")      # ✅ ALLOWED - confirming deployment
-PM: "App verified: Port 3000 listening, HTTP 200 response"
+# Correct: Delegate implementation, then delegate verification
+PM: Task(agent="local-ops", task="Start app on localhost:3000 using npm")
+    [local-ops starts app]
+PM: Task(agent="local-ops", task="Verify app is running on port 3000")
+    [local-ops uses lsof and curl to verify]
+    [local-ops returns: "Port 3000 listening, HTTP 200 response"]
+PM: "App verified by local-ops: Port 3000 listening, HTTP 200 response"
 
 # Correct: Delegate implementation, then delegate testing
 PM: Task(agent="engineer", task="Fix authentication bug")
@@ -578,6 +586,7 @@ PM: "Bug fix verified by QA: All tests passed"
 # Correct: Thinking in delegation terms
 PM: "I'll have Research check the code..."
 PM: "I'll delegate this fix to Engineer..."
+PM: "I'll have local-ops verify the deployment..."
 ```
 
 ---

claude_mpm/auth/__init__.py

@@ -0,0 +1,35 @@
+"""OAuth authentication module for MCP services.
+
+This module provides secure OAuth token management and callback handling
+for authenticating with MCP services that require OAuth2 flows.
+
+Core Components:
+    - OAuthToken: Token data model with expiration handling
+    - TokenStorage: Secure encrypted token persistence
+    - OAuthCallbackServer: Local HTTP server for OAuth callbacks
+    - OAuthProvider: Abstract base class for OAuth providers
+    - GoogleOAuthProvider: Google OAuth2 implementation
+"""
+
+from claude_mpm.auth.callback_server import OAuthCallbackServer
+from claude_mpm.auth.models import (
+    OAuthToken,
+    StoredToken,
+    TokenMetadata,
+    TokenStatus,
+)
+from claude_mpm.auth.oauth_manager import OAuthManager
+from claude_mpm.auth.providers import GoogleOAuthProvider, OAuthProvider
+from claude_mpm.auth.token_storage import TokenStorage
+
+__all__ = [
+    "GoogleOAuthProvider",
+    "OAuthCallbackServer",
+    "OAuthManager",
+    "OAuthProvider",
+    "OAuthToken",
+    "StoredToken",
+    "TokenMetadata",
+    "TokenStatus",
+    "TokenStorage",
+]

claude_mpm/auth/callback_server.py

@@ -0,0 +1,328 @@
+"""OAuth callback server for handling authorization redirects.
+
+This module provides a local HTTP server that handles OAuth2 callback
+redirects, capturing authorization codes and tokens from OAuth providers.
+
+Security Features:
+    - Binds only to localhost (127.0.0.1)
+    - CSRF protection via state parameter validation
+    - Automatic server shutdown after callback received
+    - Configurable timeout for callback wait
+"""
+
+import asyncio
+import secrets
+from dataclasses import dataclass, field
+from typing import Optional
+
+from aiohttp import web
+
+# Default port for OAuth callback server
+DEFAULT_PORT = 8789
+
+# HTML response templates
+SUCCESS_HTML = """
+<!DOCTYPE html>
+<html>
+<head>
+    <title>Authorization Successful</title>
+    <style>
+        body {
+            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+            display: flex;
+            justify-content: center;
+            align-items: center;
+            height: 100vh;
+            margin: 0;
+            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+        }
+        .container {
+            background: white;
+            padding: 40px 60px;
+            border-radius: 12px;
+            box-shadow: 0 10px 40px rgba(0,0,0,0.2);
+            text-align: center;
+        }
+        .success-icon {
+            font-size: 64px;
+            margin-bottom: 20px;
+        }
+        h1 { color: #22c55e; margin: 0 0 10px 0; }
+        p { color: #666; margin: 0; }
+    </style>
+</head>
+<body>
+    <div class="container">
+        <div class="success-icon">&#10004;</div>
+        <h1>Authorization Successful</h1>
+        <p>You can close this window and return to Claude.</p>
+    </div>
+</body>
+</html>
+"""
+
+ERROR_HTML = """
+<!DOCTYPE html>
+<html>
+<head>
+    <title>Authorization Failed</title>
+    <style>
+        body {
+            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+            display: flex;
+            justify-content: center;
+            align-items: center;
+            height: 100vh;
+            margin: 0;
+            background: linear-gradient(135deg, #f87171 0%, #dc2626 100%);
+        }
+        .container {
+            background: white;
+            padding: 40px 60px;
+            border-radius: 12px;
+            box-shadow: 0 10px 40px rgba(0,0,0,0.2);
+            text-align: center;
+        }
+        .error-icon {
+            font-size: 64px;
+            margin-bottom: 20px;
+        }
+        h1 { color: #dc2626; margin: 0 0 10px 0; }
+        p { color: #666; margin: 0; }
+        .error-detail {
+            color: #999;
+            font-size: 14px;
+            margin-top: 15px;
+            padding: 10px;
+            background: #f5f5f5;
+            border-radius: 6px;
+        }
+    </style>
+</head>
+<body>
+    <div class="container">
+        <div class="error-icon">&#10006;</div>
+        <h1>Authorization Failed</h1>
+        <p>An error occurred during authorization.</p>
+        <div class="error-detail">{error}</div>
+    </div>
+</body>
+</html>
+"""
+
+
+@dataclass
+class CallbackResult:
+    """Result from an OAuth callback.
+
+    Attributes:
+        success: Whether the callback was successful.
+        code: Authorization code if successful.
+        state: State parameter from the callback.
+        error: Error message if unsuccessful.
+        error_description: Detailed error description from provider.
+    """
+
+    success: bool
+    code: Optional[str] = None
+    state: Optional[str] = None
+    error: Optional[str] = None
+    error_description: Optional[str] = None
+
+
+@dataclass
+class OAuthCallbackServer:
+    """Local HTTP server for OAuth2 callback handling.
+
+    This server listens on localhost for OAuth redirect callbacks,
+    captures the authorization code or token, and provides it to
+    the calling code.
+
+    The server implements CSRF protection by generating a unique
+    state parameter that must be validated in the callback.
+
+    Attributes:
+        port: Port to listen on, defaults to 8789.
+        host: Host to bind to, always 127.0.0.1 for security.
+
+    Example:
+        ```python
+        server = OAuthCallbackServer()
+        state = server.generate_state()
+
+        # Use server.callback_url and state in OAuth authorization URL
+        auth_url = f"https://provider.com/oauth/authorize?redirect_uri={server.callback_url}&state={state}"
+
+        # Wait for callback (user completes auth in browser)
+        result = await server.wait_for_callback(expected_state=state, timeout=300)
+
+        if result.success:
+            print(f"Got authorization code: {result.code}")
+        else:
+            print(f"Error: {result.error}")
+        ```
+    """
+
+    port: int = DEFAULT_PORT
+    host: str = field(default="127.0.0.1", init=False)
+    _state: Optional[str] = field(default=None, init=False, repr=False)
+    _result: Optional[CallbackResult] = field(default=None, init=False, repr=False)
+    _callback_received: asyncio.Event = field(
+        default_factory=asyncio.Event, init=False, repr=False
+    )
+
+    @property
+    def callback_url(self) -> str:
+        """Get the callback URL for OAuth configuration.
+
+        Returns:
+            The full callback URL including host and port.
+        """
+        return f"http://{self.host}:{self.port}/callback"
+
+    def generate_state(self) -> str:
+        """Generate a cryptographically secure state parameter.
+
+        The state parameter is used for CSRF protection in the OAuth flow.
+        It should be included in the authorization request and validated
+        when the callback is received.
+
+        Returns:
+            A 32-character URL-safe random string.
+        """
+        self._state = secrets.token_urlsafe(24)
+        return self._state
+
+    async def _handle_callback(self, request: web.Request) -> web.Response:
+        """Handle the OAuth callback request.
+
+        Args:
+            request: The incoming HTTP request.
+
+        Returns:
+            HTML response indicating success or failure.
+        """
+        # Extract query parameters
+        code = request.query.get("code")
+        state = request.query.get("state")
+        error = request.query.get("error")
+        error_description = request.query.get("error_description", "")
+
+        # Check for error from provider
+        if error:
+            self._result = CallbackResult(
+                success=False,
+                state=state,
+                error=error,
+                error_description=error_description,
+            )
+            self._callback_received.set()
+            return web.Response(
+                text=ERROR_HTML.format(error=f"{error}: {error_description}"),
+                content_type="text/html",
+            )
+
+        # Validate state parameter (CSRF protection)
+        if self._state and state != self._state:
+            self._result = CallbackResult(
+                success=False,
+                state=state,
+                error="state_mismatch",
+                error_description="State parameter does not match. Possible CSRF attack.",
+            )
+            self._callback_received.set()
+            return web.Response(
+                text=ERROR_HTML.format(error="State mismatch - possible CSRF attack"),
+                content_type="text/html",
+            )
+
+        # Check for authorization code
+        if not code:
+            self._result = CallbackResult(
+                success=False,
+                state=state,
+                error="missing_code",
+                error_description="No authorization code received.",
+            )
+            self._callback_received.set()
+            return web.Response(
+                text=ERROR_HTML.format(error="No authorization code received"),
+                content_type="text/html",
+            )
+
+        # Success
+        self._result = CallbackResult(
+            success=True,
+            code=code,
+            state=state,
+        )
+        self._callback_received.set()
+        return web.Response(text=SUCCESS_HTML, content_type="text/html")
+
+    async def wait_for_callback(
+        self,
+        expected_state: Optional[str] = None,
+        timeout: float = 300.0,
+    ) -> CallbackResult:
+        """Start the server and wait for an OAuth callback.
+
+        This method starts the HTTP server, waits for a callback request,
+        validates the state parameter, and returns the result.
+
+        Args:
+            expected_state: State parameter to validate against.
+                If not provided, uses the last generated state.
+            timeout: Maximum time to wait for callback in seconds.
+                Defaults to 300 seconds (5 minutes).
+
+        Returns:
+            CallbackResult containing the authorization code or error.
+
+        Raises:
+            asyncio.TimeoutError: If no callback received within timeout.
+        """
+        # Set expected state
+        if expected_state:
+            self._state = expected_state
+
+        # Reset state for new wait
+        self._result = None
+        self._callback_received.clear()
+
+        # Create aiohttp app and routes
+        app = web.Application()
+        app.router.add_get("/callback", self._handle_callback)
+
+        # Create and start runner
+        runner = web.AppRunner(app)
+        await runner.setup()
+
+        site = web.TCPSite(runner, self.host, self.port)
+        await site.start()
+
+        try:
+            # Wait for callback with timeout
+            await asyncio.wait_for(
+                self._callback_received.wait(),
+                timeout=timeout,
+            )
+
+            if self._result is None:
+                return CallbackResult(
+                    success=False,
+                    error="unknown_error",
+                    error_description="Callback received but no result set.",
+                )
+
+            return self._result
+
+        except asyncio.TimeoutError:
+            return CallbackResult(
+                success=False,
+                error="timeout",
+                error_description=f"No callback received within {timeout} seconds.",
+            )
+
+        finally:
+            # Clean up server
+            await runner.cleanup()

claude_mpm/auth/models.py

@@ -0,0 +1,104 @@
+"""OAuth data models for token management.
+
+This module defines Pydantic models for OAuth tokens and their metadata,
+providing type-safe token handling with automatic validation.
+"""
+
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class TokenStatus(str, Enum):
+    """Status of an OAuth token."""
+
+    VALID = "valid"
+    EXPIRED = "expired"
+    MISSING = "missing"
+    INVALID = "invalid"
+
+
+class OAuthToken(BaseModel):
+    """OAuth2 token data.
+
+    Represents the token response from an OAuth provider with
+    expiration tracking and scope management.
+
+    Attributes:
+        access_token: The access token string for API authentication.
+        refresh_token: Optional refresh token for token renewal.
+        expires_at: UTC timestamp when the access token expires.
+        scopes: List of granted OAuth scopes.
+        token_type: Token type, typically "Bearer".
+    """
+
+    access_token: str = Field(..., description="OAuth access token")
+    refresh_token: Optional[str] = Field(
+        default=None, description="OAuth refresh token for renewal"
+    )
+    expires_at: datetime = Field(..., description="Token expiration timestamp (UTC)")
+    scopes: list[str] = Field(default_factory=list, description="Granted OAuth scopes")
+    token_type: str = Field(default="Bearer", description="Token type")
+
+    def is_expired(self, buffer_seconds: int = 60) -> bool:
+        """Check if the token is expired or about to expire.
+
+        Args:
+            buffer_seconds: Number of seconds before actual expiration
+                to consider the token expired. Defaults to 60 seconds
+                to allow time for token refresh.
+
+        Returns:
+            True if the token is expired or will expire within the buffer period.
+        """
+        now = datetime.now(timezone.utc)
+        # Ensure expires_at is timezone-aware
+        expires_at = self.expires_at
+        if expires_at.tzinfo is None:
+            expires_at = expires_at.replace(tzinfo=timezone.utc)
+
+        from datetime import timedelta
+
+        return now >= (expires_at - timedelta(seconds=buffer_seconds))
+
+
+class TokenMetadata(BaseModel):
+    """Metadata about a stored OAuth token.
+
+    Tracks service information and timestamps for token lifecycle management.
+
+    Attributes:
+        service_name: Name of the MCP service this token authenticates.
+        provider: OAuth provider identifier (e.g., "github", "google").
+        created_at: When the token was first stored.
+        last_refreshed: When the token was last refreshed, if applicable.
+    """
+
+    service_name: str = Field(..., description="MCP service name")
+    provider: str = Field(..., description="OAuth provider identifier")
+    created_at: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc),
+        description="Token creation timestamp",
+    )
+    last_refreshed: Optional[datetime] = Field(
+        default=None, description="Last token refresh timestamp"
+    )
+
+
+class StoredToken(BaseModel):
+    """Complete stored token with metadata and versioning.
+
+    This is the top-level structure persisted to storage, containing
+    both the token data and metadata needed for management.
+
+    Attributes:
+        version: Schema version for future migration support.
+        metadata: Token metadata including service and provider info.
+        token: The actual OAuth token data.
+    """
+
+    version: int = Field(default=1, description="Schema version for migrations")
+    metadata: TokenMetadata = Field(..., description="Token metadata")
+    token: OAuthToken = Field(..., description="OAuth token data")