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

fastmcp/server/auth/jwt_issuer.py

@@ -0,0 +1,236 @@
+"""JWT token issuance and verification for FastMCP OAuth Proxy.
+
+This module implements the token factory pattern for OAuth proxies, where the proxy
+issues its own JWT tokens to clients instead of forwarding upstream provider tokens.
+This maintains proper OAuth 2.0 token audience boundaries.
+"""
+
+from __future__ import annotations
+
+import base64
+import time
+from typing import Any, overload
+
+from authlib.jose import JsonWebToken
+from authlib.jose.errors import JoseError
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC
+
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+KDF_ITERATIONS = 1000000
+
+
+@overload
+def derive_jwt_key(*, high_entropy_material: str, salt: str) -> bytes:
+    """Derive JWT signing key from a high-entropy key material and server salt."""
+
+
+@overload
+def derive_jwt_key(*, low_entropy_material: str, salt: str) -> bytes:
+    """Derive JWT signing key from a low-entropy key material and server salt."""
+
+
+def derive_jwt_key(
+    *,
+    high_entropy_material: str | None = None,
+    low_entropy_material: str | None = None,
+    salt: str,
+) -> bytes:
+    """Derive JWT signing key from a high-entropy or low-entropy key material and server salt."""
+    if high_entropy_material is not None and low_entropy_material is not None:
+        raise ValueError(
+            "Either high_entropy_material or low_entropy_material must be provided, but not both"
+        )
+
+    if high_entropy_material is not None:
+        derived_key = HKDF(
+            algorithm=hashes.SHA256(),
+            length=32,
+            salt=salt.encode(),
+            info=b"Fernet",
+        ).derive(key_material=high_entropy_material.encode())
+
+        return base64.urlsafe_b64encode(derived_key)
+
+    if low_entropy_material is not None:
+        pbkdf2 = PBKDF2HMAC(
+            algorithm=hashes.SHA256(),
+            length=32,
+            salt=salt.encode(),
+            iterations=KDF_ITERATIONS,
+        ).derive(key_material=low_entropy_material.encode())
+
+        return base64.urlsafe_b64encode(pbkdf2)
+
+    raise ValueError(
+        "Either high_entropy_material or low_entropy_material must be provided"
+    )
+
+
+class JWTIssuer:
+    """Issues and validates FastMCP-signed JWT tokens using HS256.
+
+    This issuer creates JWT tokens for MCP clients with proper audience claims,
+    maintaining OAuth 2.0 token boundaries. Tokens are signed with HS256 using
+    a key derived from the upstream client secret.
+    """
+
+    def __init__(
+        self,
+        issuer: str,
+        audience: str,
+        signing_key: bytes,
+    ):
+        """Initialize JWT issuer.
+
+        Args:
+            issuer: Token issuer (FastMCP server base URL)
+            audience: Token audience (typically {base_url}/mcp)
+            signing_key: HS256 signing key (32 bytes)
+        """
+        self.issuer = issuer
+        self.audience = audience
+        self._signing_key = signing_key
+        self._jwt = JsonWebToken(["HS256"])
+
+    def issue_access_token(
+        self,
+        client_id: str,
+        scopes: list[str],
+        jti: str,
+        expires_in: int = 3600,
+    ) -> str:
+        """Issue a minimal FastMCP access token.
+
+        FastMCP tokens are reference tokens containing only the minimal claims
+        needed for validation and lookup. The JTI maps to the upstream token
+        which contains actual user identity and authorization data.
+
+        Args:
+            client_id: MCP client ID
+            scopes: Token scopes
+            jti: Unique token identifier (maps to upstream token)
+            expires_in: Token lifetime in seconds
+
+        Returns:
+            Signed JWT token
+        """
+        now = int(time.time())
+
+        header = {"alg": "HS256", "typ": "JWT"}
+        payload = {
+            "iss": self.issuer,
+            "aud": self.audience,
+            "client_id": client_id,
+            "scope": " ".join(scopes),
+            "exp": now + expires_in,
+            "iat": now,
+            "jti": jti,
+        }
+
+        token_bytes = self._jwt.encode(header, payload, self._signing_key)
+        token = token_bytes.decode("utf-8")
+
+        logger.debug(
+            "Issued access token for client=%s jti=%s exp=%d",
+            client_id,
+            jti[:8],
+            payload["exp"],
+        )
+
+        return token
+
+    def issue_refresh_token(
+        self,
+        client_id: str,
+        scopes: list[str],
+        jti: str,
+        expires_in: int,
+    ) -> str:
+        """Issue a minimal FastMCP refresh token.
+
+        FastMCP refresh tokens are reference tokens containing only the minimal
+        claims needed for validation and lookup. The JTI maps to the upstream
+        token which contains actual user identity and authorization data.
+
+        Args:
+            client_id: MCP client ID
+            scopes: Token scopes
+            jti: Unique token identifier (maps to upstream token)
+            expires_in: Token lifetime in seconds (should match upstream refresh expiry)
+
+        Returns:
+            Signed JWT token
+        """
+        now = int(time.time())
+
+        header = {"alg": "HS256", "typ": "JWT"}
+        payload = {
+            "iss": self.issuer,
+            "aud": self.audience,
+            "client_id": client_id,
+            "scope": " ".join(scopes),
+            "exp": now + expires_in,
+            "iat": now,
+            "jti": jti,
+            "token_use": "refresh",
+        }
+
+        token_bytes = self._jwt.encode(header, payload, self._signing_key)
+        token = token_bytes.decode("utf-8")
+
+        logger.debug(
+            "Issued refresh token for client=%s jti=%s exp=%d",
+            client_id,
+            jti[:8],
+            payload["exp"],
+        )
+
+        return token
+
+    def verify_token(self, token: str) -> dict[str, Any]:
+        """Verify and decode a FastMCP token.
+
+        Validates JWT signature, expiration, issuer, and audience.
+
+        Args:
+            token: JWT token to verify
+
+        Returns:
+            Decoded token payload
+
+        Raises:
+            JoseError: If token is invalid, expired, or has wrong claims
+        """
+        try:
+            # Decode and verify signature
+            payload = self._jwt.decode(token, self._signing_key)
+
+            # Validate expiration
+            exp = payload.get("exp")
+            if exp and exp < time.time():
+                logger.debug("Token expired")
+                raise JoseError("Token has expired")
+
+            # Validate issuer
+            if payload.get("iss") != self.issuer:
+                logger.debug("Token has invalid issuer")
+                raise JoseError("Invalid token issuer")
+
+            # Validate audience
+            if payload.get("aud") != self.audience:
+                logger.debug("Token has invalid audience")
+                raise JoseError("Invalid token audience")
+
+            logger.debug(
+                "Token verified successfully for subject=%s", payload.get("sub")
+            )
+            return payload
+
+        except JoseError as e:
+            logger.debug("Token validation failed: %s", e)
+            raise

fastmcp/server/auth/middleware.py

@@ -0,0 +1,96 @@
+"""Enhanced authentication middleware with better error messages.
+
+This module provides enhanced versions of MCP SDK authentication middleware
+that return more helpful error messages for developers troubleshooting
+authentication issues.
+"""
+
+from __future__ import annotations
+
+import json
+
+from mcp.server.auth.middleware.bearer_auth import (
+    RequireAuthMiddleware as SDKRequireAuthMiddleware,
+)
+from starlette.types import Send
+
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class RequireAuthMiddleware(SDKRequireAuthMiddleware):
+    """Enhanced authentication middleware with detailed error messages.
+
+    Extends the SDK's RequireAuthMiddleware to provide more actionable
+    error messages when authentication fails. This helps developers
+    understand what went wrong and how to fix it.
+    """
+
+    async def _send_auth_error(
+        self, send: Send, status_code: int, error: str, description: str
+    ) -> None:
+        """Send an authentication error response with enhanced error messages.
+
+        Overrides the SDK's _send_auth_error to provide more detailed
+        error descriptions that help developers troubleshoot authentication
+        issues.
+
+        Args:
+            send: ASGI send callable
+            status_code: HTTP status code (401 or 403)
+            error: OAuth error code
+            description: Base error description
+        """
+        # Enhance error descriptions based on error type
+        enhanced_description = description
+
+        if error == "invalid_token" and status_code == 401:
+            # This is the "Authentication required" error
+            enhanced_description = (
+                "Authentication failed. The provided bearer token is invalid, expired, or no longer recognized by the server. "
+                "To resolve: clear authentication tokens in your MCP client and reconnect. "
+                "Your client should automatically re-register and obtain new tokens."
+            )
+        elif error == "insufficient_scope":
+            # Scope error - already has good detail from SDK
+            pass
+
+        # Build WWW-Authenticate header value
+        www_auth_parts = [
+            f'error="{error}"',
+            f'error_description="{enhanced_description}"',
+        ]
+        if self.resource_metadata_url:
+            www_auth_parts.append(f'resource_metadata="{self.resource_metadata_url}"')
+
+        www_authenticate = f"Bearer {', '.join(www_auth_parts)}"
+
+        # Send response
+        body = {"error": error, "error_description": enhanced_description}
+        body_bytes = json.dumps(body).encode()
+
+        await send(
+            {
+                "type": "http.response.start",
+                "status": status_code,
+                "headers": [
+                    (b"content-type", b"application/json"),
+                    (b"content-length", str(len(body_bytes)).encode()),
+                    (b"www-authenticate", www_authenticate.encode()),
+                ],
+            }
+        )
+
+        await send(
+            {
+                "type": "http.response.body",
+                "body": body_bytes,
+            }
+        )
+
+        logger.info(
+            "Auth error returned: %s (status=%d)",
+            error,
+            status_code,
+        )