fastmcp 2.12.5__py3-none-any.whl → 2.13.2__py3-none-any.whl

fastmcp/server/auth/providers/debug.py

@@ -0,0 +1,114 @@
+"""Debug token verifier for testing and special cases.
+
+This module provides a flexible token verifier that delegates validation
+to a custom callable. Useful for testing, development, or scenarios where
+standard verification isn't possible (like opaque tokens without introspection).
+
+Example:
+    ```python
+    from fastmcp import FastMCP
+    from fastmcp.server.auth.providers.debug import DebugTokenVerifier
+
+    # Accept all tokens (default - useful for testing)
+    auth = DebugTokenVerifier()
+
+    # Custom sync validation logic
+    auth = DebugTokenVerifier(validate=lambda token: token.startswith("valid-"))
+
+    # Custom async validation logic
+    async def check_cache(token: str) -> bool:
+        return await redis.exists(f"token:{token}")
+
+    auth = DebugTokenVerifier(validate=check_cache)
+
+    mcp = FastMCP("My Server", auth=auth)
+    ```
+"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Awaitable, Callable
+
+from fastmcp.server.auth import TokenVerifier
+from fastmcp.server.auth.auth import AccessToken
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class DebugTokenVerifier(TokenVerifier):
+    """Token verifier with custom validation logic.
+
+    This verifier delegates token validation to a user-provided callable.
+    By default, it accepts all non-empty tokens (useful for testing).
+
+    Use cases:
+    - Testing: Accept any token without real verification
+    - Development: Custom validation logic for prototyping
+    - Opaque tokens: When you have tokens with no introspection endpoint
+
+    WARNING: This bypasses standard security checks. Only use in controlled
+    environments or when you understand the security implications.
+    """
+
+    def __init__(
+        self,
+        validate: Callable[[str], bool]
+        | Callable[[str], Awaitable[bool]] = lambda token: True,
+        client_id: str = "debug-client",
+        scopes: list[str] | None = None,
+        required_scopes: list[str] | None = None,
+    ):
+        """Initialize the debug token verifier.
+
+        Args:
+            validate: Callable that takes a token string and returns True if valid.
+                Can be sync or async. Default accepts all tokens.
+            client_id: Client ID to assign to validated tokens
+            scopes: Scopes to assign to validated tokens
+            required_scopes: Required scopes (inherited from TokenVerifier base class)
+        """
+        super().__init__(required_scopes=required_scopes)
+        self.validate = validate
+        self.client_id = client_id
+        self.scopes = scopes or []
+
+    async def verify_token(self, token: str) -> AccessToken | None:
+        """Verify token using custom validation logic.
+
+        Args:
+            token: The token string to validate
+
+        Returns:
+            AccessToken if validation succeeds, None otherwise
+        """
+        # Reject empty tokens
+        if not token or not token.strip():
+            logger.debug("Rejecting empty token")
+            return None
+
+        try:
+            # Call validation function and await if result is awaitable
+            result = self.validate(token)
+            if inspect.isawaitable(result):
+                is_valid = await result
+            else:
+                is_valid = result
+
+            if not is_valid:
+                logger.debug("Token validation failed: callable returned False")
+                return None
+
+            # Return valid AccessToken
+            return AccessToken(
+                token=token,
+                client_id=self.client_id,
+                scopes=self.scopes,
+                expires_at=None,  # No expiration
+                claims={"token": token},  # Store original token in claims
+            )
+
+        except Exception as e:
+            logger.debug("Token validation error: %s", e, exc_info=True)
+            return None

fastmcp/server/auth/providers/descope.py

@@ -7,16 +7,18 @@ for seamless MCP client authentication.
 
 from __future__ import annotations
 
-from typing import Any
+from urllib.parse import urlparse
 
 import httpx
-from pydantic import AnyHttpUrl
+from pydantic import AnyHttpUrl, field_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 from starlette.responses import JSONResponse
 from starlette.routing import Route
 
 from fastmcp.server.auth import RemoteAuthProvider, TokenVerifier
 from fastmcp.server.auth.providers.jwt import JWTVerifier
+from fastmcp.settings import ENV_FILE
+from fastmcp.utilities.auth import parse_scopes
 from fastmcp.utilities.logging import get_logger
 from fastmcp.utilities.types import NotSet, NotSetT
 
@@ -26,13 +28,20 @@ logger = get_logger(__name__)
 class DescopeProviderSettings(BaseSettings):
     model_config = SettingsConfigDict(
         env_prefix="FASTMCP_SERVER_AUTH_DESCOPEPROVIDER_",
-        env_file=".env",
+        env_file=ENV_FILE,
         extra="ignore",
     )
 
-    project_id: str
+    config_url: AnyHttpUrl | None = None
+    project_id: str | None = None
+    descope_base_url: AnyHttpUrl | str | None = None
     base_url: AnyHttpUrl
-    descope_base_url: AnyHttpUrl = AnyHttpUrl("https://api.descope.com")
+    required_scopes: list[str] | None = None
+
+    @field_validator("required_scopes", mode="before")
+    @classmethod
+    def _parse_scopes(cls, v):
+        return parse_scopes(v)
 
 
 class DescopeProvider(RemoteAuthProvider):
@@ -45,15 +54,15 @@ class DescopeProvider(RemoteAuthProvider):
 
     IMPORTANT SETUP REQUIREMENTS:
 
-    1. Enable Dynamic Client Registration in Descope Console:
-       - Go to the [Inbound Apps page](https://app.descope.com/apps/inbound) of the Descope Console
-       - Click **DCR Settings**
-       - Enable **Dynamic Client Registration (DCR)**
-       - Define allowed scopes
+    1. Create an MCP Server in Descope Console:
+       - Go to the [MCP Servers page](https://app.descope.com/mcp-servers) of the Descope Console
+       - Create a new MCP Server
+       - Ensure that **Dynamic Client Registration (DCR)** is enabled
+       - Note your Well-Known URL
 
-    2. Note your Project ID:
-       - Save your Project ID from [Project Settings](https://app.descope.com/settings/project)
-       - Example: P2abc...123
+    2. Note your Well-Known URL:
+       - Save your Well-Known URL from [MCP Server Settings](https://app.descope.com/mcp-servers)
+       - Format: ``https://.../v1/apps/agentic/P.../M.../.well-known/openid-configuration``
 
     For detailed setup instructions, see:
     https://docs.descope.com/identity-federation/inbound-apps/creating-inbound-apps#method-2-dynamic-client-registration-dcr
@@ -64,9 +73,8 @@ class DescopeProvider(RemoteAuthProvider):
 
         # Create Descope metadata provider (JWT verifier created automatically)
         descope_auth = DescopeProvider(
-            project_id="P2abc...123",
+            config_url="https://.../v1/apps/agentic/P.../M.../.well-known/openid-configuration",
             base_url="https://your-fastmcp-server.com",
-            descope_base_url="https://api.descope.com",
         )
 
         # Use with FastMCP
@@ -77,57 +85,106 @@ class DescopeProvider(RemoteAuthProvider):
     def __init__(
         self,
         *,
+        config_url: AnyHttpUrl | str | NotSetT = NotSet,
         project_id: str | NotSetT = NotSet,
-        base_url: AnyHttpUrl | str | NotSetT = NotSet,
         descope_base_url: AnyHttpUrl | str | NotSetT = NotSet,
+        base_url: AnyHttpUrl | str | NotSetT = NotSet,
+        required_scopes: list[str] | NotSetT | None = NotSet,
         token_verifier: TokenVerifier | None = None,
     ):
         """Initialize Descope metadata provider.
 
         Args:
-            project_id: Your Descope Project ID (e.g., "P2abc...123")
+            config_url: Your Descope Well-Known URL (e.g., "https://.../v1/apps/agentic/P.../M.../.well-known/openid-configuration")
+                This is the new recommended way. If provided, project_id and descope_base_url are ignored.
+            project_id: Your Descope Project ID (e.g., "P2abc123"). Used with descope_base_url for backwards compatibility.
+            descope_base_url: Your Descope base URL (e.g., "https://api.descope.com"). Used with project_id for backwards compatibility.
             base_url: Public URL of this FastMCP server
-            descope_base_url: Descope API base URL (defaults to https://api.descope.com)
+            required_scopes: Optional list of scopes that must be present in validated tokens.
+                These scopes will be included in the protected resource metadata.
             token_verifier: Optional token verifier. If None, creates JWT verifier for Descope
         """
         settings = DescopeProviderSettings.model_validate(
             {
                 k: v
                 for k, v in {
+                    "config_url": config_url,
                     "project_id": project_id,
-                    "base_url": base_url,
                     "descope_base_url": descope_base_url,
+                    "base_url": base_url,
+                    "required_scopes": required_scopes,
                 }.items()
                 if v is not NotSet
             }
         )
 
-        self.project_id = settings.project_id
-        self.base_url = str(settings.base_url).rstrip("/")
-        self.descope_base_url = str(settings.descope_base_url).rstrip("/")
+        self.base_url = AnyHttpUrl(str(settings.base_url).rstrip("/"))
+
+        # Determine which API is being used
+        if settings.config_url is not None:
+            # New API: use config_url
+            # Strip /.well-known/openid-configuration from config_url if present
+            issuer_url = str(settings.config_url)
+            if issuer_url.endswith("/.well-known/openid-configuration"):
+                issuer_url = issuer_url[: -len("/.well-known/openid-configuration")]
+
+            # Parse the issuer URL to extract descope_base_url and project_id for other uses
+            parsed_url = urlparse(issuer_url)
+            path_parts = parsed_url.path.strip("/").split("/")
+
+            # Extract project_id from path (format: /v1/apps/agentic/P.../M...)
+            if "agentic" in path_parts:
+                agentic_index = path_parts.index("agentic")
+                if agentic_index + 1 < len(path_parts):
+                    self.project_id = path_parts[agentic_index + 1]
+                else:
+                    raise ValueError(
+                        f"Could not extract project_id from config_url: {issuer_url}"
+                    )
+            else:
+                raise ValueError(
+                    f"Could not find 'agentic' in config_url path: {issuer_url}"
+                )
+
+            # Extract descope_base_url (scheme + netloc)
+            self.descope_base_url = f"{parsed_url.scheme}://{parsed_url.netloc}".rstrip(
+                "/"
+            )
+        elif settings.project_id is not None and settings.descope_base_url is not None:
+            # Old API: use project_id and descope_base_url
+            self.project_id = settings.project_id
+            descope_base_url_str = str(settings.descope_base_url).rstrip("/")
+            # Ensure descope_base_url has a scheme
+            if not descope_base_url_str.startswith(("http://", "https://")):
+                descope_base_url_str = f"https://{descope_base_url_str}"
+            self.descope_base_url = descope_base_url_str
+            # Old issuer format
+            issuer_url = f"{self.descope_base_url}/v1/apps/{self.project_id}"
+        else:
+            raise ValueError(
+                "Either config_url (new API) or both project_id and descope_base_url (old API) must be provided"
+            )
 
         # Create default JWT verifier if none provided
         if token_verifier is None:
             token_verifier = JWTVerifier(
                 jwks_uri=f"{self.descope_base_url}/{self.project_id}/.well-known/jwks.json",
-                issuer=f"{self.descope_base_url}/v1/apps/{self.project_id}",
+                issuer=issuer_url,
                 algorithm="RS256",
                 audience=self.project_id,
+                required_scopes=settings.required_scopes,
             )
 
         # Initialize RemoteAuthProvider with Descope as the authorization server
         super().__init__(
             token_verifier=token_verifier,
-            authorization_servers=[
-                AnyHttpUrl(f"{self.descope_base_url}/v1/apps/{self.project_id}")
-            ],
+            authorization_servers=[AnyHttpUrl(issuer_url)],
             base_url=self.base_url,
         )
 
     def get_routes(
         self,
         mcp_path: str | None = None,
-        mcp_endpoint: Any | None = None,
     ) -> list[Route]:
         """Get OAuth routes including Descope authorization server metadata forwarding.
 
@@ -136,10 +193,10 @@ class DescopeProvider(RemoteAuthProvider):
 
         Args:
             mcp_path: The path where the MCP endpoint is mounted (e.g., "/mcp")
-            mcp_endpoint: The MCP endpoint handler to protect with auth
+                This is used to advertise the resource URL in metadata.
         """
         # Get the standard protected resource routes from RemoteAuthProvider
-        routes = super().get_routes(mcp_path, mcp_endpoint)
+        routes = super().get_routes(mcp_path)
 
         async def oauth_authorization_server_metadata(request):
             """Forward Descope OAuth authorization server metadata with FastMCP customizations."""

fastmcp/server/auth/providers/discord.py

@@ -0,0 +1,308 @@
+"""Discord OAuth provider for FastMCP.
+
+This module provides a complete Discord OAuth integration that's ready to use
+with just a client ID and client secret. It handles all the complexity of
+Discord's OAuth flow, token validation, and user management.
+
+Example:
+    ```python
+    from fastmcp import FastMCP
+    from fastmcp.server.auth.providers.discord import DiscordProvider
+
+    # Simple Discord OAuth protection
+    auth = DiscordProvider(
+        client_id="your-discord-client-id",
+        client_secret="your-discord-client-secret"
+    )
+
+    mcp = FastMCP("My Protected Server", auth=auth)
+    ```
+"""
+
+from __future__ import annotations
+
+import time
+from datetime import datetime
+
+import httpx
+from key_value.aio.protocols import AsyncKeyValue
+from pydantic import AnyHttpUrl, SecretStr, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from fastmcp.server.auth import TokenVerifier
+from fastmcp.server.auth.auth import AccessToken
+from fastmcp.server.auth.oauth_proxy import OAuthProxy
+from fastmcp.settings import ENV_FILE
+from fastmcp.utilities.auth import parse_scopes
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.types import NotSet, NotSetT
+
+logger = get_logger(__name__)
+
+
+class DiscordProviderSettings(BaseSettings):
+    """Settings for Discord OAuth provider."""
+
+    model_config = SettingsConfigDict(
+        env_prefix="FASTMCP_SERVER_AUTH_DISCORD_",
+        env_file=ENV_FILE,
+        extra="ignore",
+    )
+
+    client_id: str | None = None
+    client_secret: SecretStr | None = None
+    base_url: AnyHttpUrl | str | None = None
+    issuer_url: AnyHttpUrl | str | None = None
+    redirect_path: str | None = None
+    required_scopes: list[str] | None = None
+    timeout_seconds: int | None = None
+    allowed_client_redirect_uris: list[str] | None = None
+    jwt_signing_key: str | None = None
+
+    @field_validator("required_scopes", mode="before")
+    @classmethod
+    def _parse_scopes(cls, v):
+        return parse_scopes(v)
+
+
+class DiscordTokenVerifier(TokenVerifier):
+    """Token verifier for Discord OAuth tokens.
+
+    Discord OAuth tokens are opaque (not JWTs), so we verify them
+    by calling Discord's tokeninfo API to check if they're valid and get user info.
+    """
+
+    def __init__(
+        self,
+        *,
+        required_scopes: list[str] | None = None,
+        timeout_seconds: int = 10,
+    ):
+        """Initialize the Discord token verifier.
+
+        Args:
+            required_scopes: Required OAuth scopes (e.g., ['email'])
+            timeout_seconds: HTTP request timeout
+        """
+        super().__init__(required_scopes=required_scopes)
+        self.timeout_seconds = timeout_seconds
+
+    async def verify_token(self, token: str) -> AccessToken | None:
+        """Verify Discord OAuth token by calling Discord's tokeninfo API."""
+        try:
+            async with httpx.AsyncClient(timeout=self.timeout_seconds) as client:
+                # Use Discord's tokeninfo endpoint to validate the token
+                headers = {
+                    "Authorization": f"Bearer {token}",
+                    "User-Agent": "FastMCP-Discord-OAuth",
+                }
+                response = await client.get(
+                    "https://discord.com/api/oauth2/@me",
+                    headers=headers,
+                )
+
+                if response.status_code != 200:
+                    logger.debug(
+                        "Discord token verification failed: %d",
+                        response.status_code,
+                    )
+                    return None
+
+                token_info = response.json()
+
+                # Check if token is expired (Discord returns ISO timestamp)
+                expires_str = token_info.get("expires")
+                expires_at = None
+                if expires_str:
+                    expires_dt = datetime.fromisoformat(
+                        expires_str.replace("Z", "+00:00")
+                    )
+                    expires_at = int(expires_dt.timestamp())
+                    if expires_at <= int(time.time()):
+                        logger.debug("Discord token has expired")
+                        return None
+
+                token_scopes = token_info.get("scopes", [])
+
+                # Check required scopes
+                if self.required_scopes:
+                    token_scopes_set = set(token_scopes)
+                    required_scopes_set = set(self.required_scopes)
+                    if not required_scopes_set.issubset(token_scopes_set):
+                        logger.debug(
+                            "Discord token missing required scopes. Has %d, needs %d",
+                            len(token_scopes_set),
+                            len(required_scopes_set),
+                        )
+                        return None
+
+                user_data = token_info.get("user", {})
+                application = token_info.get("application") or {}
+                client_id = str(application.get("id", "unknown"))
+
+                # Create AccessToken with Discord user info
+                access_token = AccessToken(
+                    token=token,
+                    client_id=client_id,
+                    scopes=token_scopes,
+                    expires_at=expires_at,
+                    claims={
+                        "sub": user_data.get("id"),
+                        "username": user_data.get("username"),
+                        "discriminator": user_data.get("discriminator"),
+                        "avatar": user_data.get("avatar"),
+                        "email": user_data.get("email"),
+                        "verified": user_data.get("verified"),
+                        "locale": user_data.get("locale"),
+                        "discord_user": user_data,
+                        "discord_token_info": token_info,
+                    },
+                )
+                logger.debug("Discord token verified successfully")
+                return access_token
+
+        except httpx.RequestError as e:
+            logger.debug("Failed to verify Discord token: %s", e)
+            return None
+        except Exception as e:
+            logger.debug("Discord token verification error: %s", e)
+            return None
+
+
+class DiscordProvider(OAuthProxy):
+    """Complete Discord OAuth provider for FastMCP.
+
+    This provider makes it trivial to add Discord OAuth protection to any
+    FastMCP server. Just provide your Discord OAuth app credentials and
+    a base URL, and you're ready to go.
+
+    Features:
+    - Transparent OAuth proxy to Discord
+    - Automatic token validation via Discord's API
+    - User information extraction from Discord APIs
+    - Minimal configuration required
+
+    Example:
+        ```python
+        from fastmcp import FastMCP
+        from fastmcp.server.auth.providers.discord import DiscordProvider
+
+        auth = DiscordProvider(
+            client_id="123456789",
+            client_secret="discord-client-secret-abc123...",
+            base_url="https://my-server.com"
+        )
+
+        mcp = FastMCP("My App", auth=auth)
+        ```
+    """
+
+    def __init__(
+        self,
+        *,
+        client_id: str | NotSetT = NotSet,
+        client_secret: str | NotSetT = NotSet,
+        base_url: AnyHttpUrl | str | NotSetT = NotSet,
+        issuer_url: AnyHttpUrl | str | NotSetT = NotSet,
+        redirect_path: str | NotSetT = NotSet,
+        required_scopes: list[str] | NotSetT = NotSet,
+        timeout_seconds: int | NotSetT = NotSet,
+        allowed_client_redirect_uris: list[str] | NotSetT = NotSet,
+        client_storage: AsyncKeyValue | None = None,
+        jwt_signing_key: str | bytes | NotSetT = NotSet,
+        require_authorization_consent: bool = True,
+    ):
+        """Initialize Discord OAuth provider.
+
+        Args:
+            client_id: Discord OAuth client ID (e.g., "123456789")
+            client_secret: Discord OAuth client secret (e.g., "S....")
+            base_url: Public URL where OAuth endpoints will be accessible (includes any mount path)
+            issuer_url: Issuer URL for OAuth metadata (defaults to base_url). Use root-level URL
+                to avoid 404s during discovery when mounting under a path.
+            redirect_path: Redirect path configured in Discord OAuth app (defaults to "/auth/callback")
+            required_scopes: Required Discord scopes (defaults to ["identify"]). Common scopes include:
+                - "identify" for profile info (default)
+                - "email" for email access
+                - "guilds" for server membership info
+            timeout_seconds: HTTP request timeout for Discord API calls
+            allowed_client_redirect_uris: List of allowed redirect URI patterns for MCP clients.
+                If None (default), all URIs are allowed. If empty list, no URIs are allowed.
+            client_storage: Storage backend for OAuth state (client registrations, encrypted tokens).
+                If None, a DiskStore will be created in the data directory (derived from `platformdirs`). The
+                disk store will be encrypted using a key derived from the JWT Signing Key.
+            jwt_signing_key: Secret for signing FastMCP JWT tokens (any string or bytes). If bytes are provided,
+                they will be used as is. If a string is provided, it will be derived into a 32-byte key. If not
+                provided, the upstream client secret will be used to derive a 32-byte key using PBKDF2.
+            require_authorization_consent: Whether to require user consent before authorizing clients (default True).
+                When True, users see a consent screen before being redirected to Discord.
+                When False, authorization proceeds directly without user confirmation.
+                SECURITY WARNING: Only disable for local development or testing environments.
+        """
+
+        settings = DiscordProviderSettings.model_validate(
+            {
+                k: v
+                for k, v in {
+                    "client_id": client_id,
+                    "client_secret": client_secret,
+                    "base_url": base_url,
+                    "issuer_url": issuer_url,
+                    "redirect_path": redirect_path,
+                    "required_scopes": required_scopes,
+                    "timeout_seconds": timeout_seconds,
+                    "allowed_client_redirect_uris": allowed_client_redirect_uris,
+                    "jwt_signing_key": jwt_signing_key,
+                }.items()
+                if v is not NotSet
+            }
+        )
+
+        # Validate required settings
+        if not settings.client_id:
+            raise ValueError(
+                "client_id is required - set via parameter or FASTMCP_SERVER_AUTH_DISCORD_CLIENT_ID"
+            )
+        if not settings.client_secret:
+            raise ValueError(
+                "client_secret is required - set via parameter or FASTMCP_SERVER_AUTH_DISCORD_CLIENT_SECRET"
+            )
+
+        # Apply defaults
+        timeout_seconds_final = settings.timeout_seconds or 10
+        required_scopes_final = settings.required_scopes or ["identify"]
+        allowed_client_redirect_uris_final = settings.allowed_client_redirect_uris
+
+        # Create Discord token verifier
+        token_verifier = DiscordTokenVerifier(
+            required_scopes=required_scopes_final,
+            timeout_seconds=timeout_seconds_final,
+        )
+
+        # Extract secret string from SecretStr
+        client_secret_str = (
+            settings.client_secret.get_secret_value() if settings.client_secret else ""
+        )
+
+        # Initialize OAuth proxy with Discord endpoints
+        super().__init__(
+            upstream_authorization_endpoint="https://discord.com/oauth2/authorize",
+            upstream_token_endpoint="https://discord.com/api/oauth2/token",
+            upstream_client_id=settings.client_id,
+            upstream_client_secret=client_secret_str,
+            token_verifier=token_verifier,
+            base_url=settings.base_url,
+            redirect_path=settings.redirect_path,
+            issuer_url=settings.issuer_url
+            or settings.base_url,  # Default to base_url if not specified
+            allowed_client_redirect_uris=allowed_client_redirect_uris_final,
+            client_storage=client_storage,
+            jwt_signing_key=settings.jwt_signing_key,
+            require_authorization_consent=require_authorization_consent,
+        )
+
+        logger.debug(
+            "Initialized Discord OAuth provider for client %s with scopes: %s",
+            settings.client_id,
+            required_scopes_final,
+        )