golf-mcp 0.1.20__py3-none-any.whl → 0.2.0__py3-none-any.whl

golf/auth/providers.py

@@ -0,0 +1,396 @@
+"""Modern authentication provider configurations for Golf MCP servers.
+
+This module provides configuration classes for FastMCP 2.11+ authentication providers,
+replacing the legacy custom OAuth implementation with the new built-in auth system.
+"""
+
+import os
+from typing import Any, Literal
+from urllib.parse import urlparse
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+
+class JWTAuthConfig(BaseModel):
+    """Configuration for JWT token verification using FastMCP's JWTVerifier.
+
+    Use this when you have JWT tokens issued by an external OAuth server
+    (like Auth0, Okta, etc.) and want to verify them in your Golf server.
+
+    Security Note:
+        For production use, it's strongly recommended to specify both `issuer` and `audience`
+        to ensure tokens are validated against the expected issuer and intended audience.
+        This prevents token misuse across different services or environments.
+    """
+
+    provider_type: Literal["jwt"] = "jwt"
+
+    # JWT verification settings
+    public_key: str | None = Field(None, description="PEM-encoded public key for JWT verification")
+    jwks_uri: str | None = Field(None, description="URI to fetch JSON Web Key Set for verification")
+    issuer: str | None = Field(None, description="Expected JWT issuer claim (strongly recommended for production)")
+    audience: str | list[str] | None = Field(
+        None, description="Expected JWT audience claim(s) (strongly recommended for production)"
+    )
+    algorithm: str = Field("RS256", description="JWT signing algorithm")
+
+    # Scope and access control
+    required_scopes: list[str] = Field(default_factory=list, description="Scopes required for all requests")
+
+    # Environment variable names for runtime configuration
+    public_key_env_var: str | None = Field(None, description="Environment variable name for public key")
+    jwks_uri_env_var: str | None = Field(None, description="Environment variable name for JWKS URI")
+    issuer_env_var: str | None = Field(None, description="Environment variable name for issuer")
+    audience_env_var: str | None = Field(None, description="Environment variable name for audience")
+
+    @model_validator(mode="after")
+    def validate_jwt_config(self) -> "JWTAuthConfig":
+        """Validate JWT configuration requirements."""
+        # Ensure exactly one of public_key or jwks_uri is provided
+        if not self.public_key and not self.jwks_uri and not self.public_key_env_var and not self.jwks_uri_env_var:
+            raise ValueError("Either public_key, jwks_uri, or their environment variable equivalents must be provided")
+
+        if (self.public_key or self.public_key_env_var) and (self.jwks_uri or self.jwks_uri_env_var):
+            raise ValueError("Provide either public_key or jwks_uri (or their env vars), not both")
+
+        # Warn about missing issuer/audience in production-like environments
+        is_production = (
+            os.environ.get("GOLF_ENV", "").lower() in ("prod", "production")
+            or os.environ.get("NODE_ENV", "").lower() == "production"
+            or os.environ.get("ENVIRONMENT", "").lower() in ("prod", "production")
+        )
+
+        if is_production:
+            missing_fields = []
+            if not self.issuer and not self.issuer_env_var:
+                missing_fields.append("issuer")
+            if not self.audience and not self.audience_env_var:
+                missing_fields.append("audience")
+
+            if missing_fields:
+                import warnings
+
+                warnings.warn(
+                    f"JWT configuration is missing recommended fields for production: {', '.join(missing_fields)}. "
+                    "This may allow tokens from unintended issuers or audiences to be accepted.",
+                    UserWarning,
+                    stacklevel=2,
+                )
+
+        return self
+
+
+class StaticTokenConfig(BaseModel):
+    """Configuration for static token verification for development/testing.
+
+    Use this for local development and testing when you need predictable
+    API keys without setting up a full OAuth server.
+
+    WARNING: Never use in production!
+    """
+
+    provider_type: Literal["static"] = "static"
+
+    # Static tokens mapping: token_string -> metadata
+    tokens: dict[str, dict[str, Any]] = Field(
+        default_factory=dict,
+        description="Static tokens with their metadata (client_id, scopes, expires_at)",
+    )
+
+    # Scope and access control
+    required_scopes: list[str] = Field(default_factory=list, description="Scopes required for all requests")
+
+
+class OAuthServerConfig(BaseModel):
+    """Configuration for full OAuth authorization server using FastMCP's OAuthProvider.
+
+    Use this when you want your Golf server to act as a complete OAuth server,
+    handling authorization flows and token issuance.
+
+    Security Considerations:
+        - URLs are validated to prevent SSRF attacks
+        - Scopes are validated against OAuth 2.0 standards
+        - Base URL must use HTTPS in production environments
+        - Client registration is disabled for security
+    """
+
+    provider_type: Literal["oauth_server"] = "oauth_server"
+
+    # OAuth server URLs
+    base_url: str = Field(..., description="Public URL of this Golf server (must use HTTPS in production)")
+    issuer_url: str | None = Field(None, description="OAuth issuer URL (defaults to base_url, must be HTTPS)")
+    service_documentation_url: str | None = Field(None, description="URL of service documentation")
+
+    # Client registration settings
+    valid_scopes: list[str] = Field(
+        default_factory=list, description="Valid scopes for client registration (OAuth 2.0 format)"
+    )
+    default_scopes: list[str] = Field(default_factory=list, description="Default scopes for new clients")
+
+    # Token revocation settings
+    allow_token_revocation: bool = Field(True, description="Allow token revocation")
+
+    # Access control
+    required_scopes: list[str] = Field(default_factory=list, description="Scopes required for all requests")
+
+    # Environment variable names for runtime configuration
+    base_url_env_var: str | None = Field(None, description="Environment variable name for base URL")
+
+    @field_validator("base_url")
+    @classmethod
+    def validate_base_url(cls, v: str) -> str:
+        """Validate base URL for security and format compliance."""
+        if not v or not v.strip():
+            raise ValueError("base_url cannot be empty")
+
+        url = v.strip()
+        try:
+            parsed = urlparse(url)
+            if not parsed.scheme or not parsed.netloc:
+                raise ValueError(f"Invalid base URL format: '{url}' - must include scheme and netloc")
+
+            if parsed.scheme not in ("http", "https"):
+                raise ValueError(f"Base URL must use http or https scheme: '{url}'")
+
+            # Warn about HTTP in production-like environments
+            is_production = (
+                os.environ.get("GOLF_ENV", "").lower() in ("prod", "production")
+                or os.environ.get("NODE_ENV", "").lower() == "production"
+                or os.environ.get("ENVIRONMENT", "").lower() in ("prod", "production")
+            )
+
+            if is_production and parsed.scheme == "http":
+                import warnings
+
+                warnings.warn(
+                    f"Base URL '{url}' uses HTTP in production environment. "
+                    "HTTPS is strongly recommended for OAuth servers to prevent token interception.",
+                    UserWarning,
+                    stacklevel=2,
+                )
+
+            # Prevent common SSRF targets
+            if parsed.hostname in ("localhost", "127.0.0.1", "0.0.0.0"):
+                if is_production:
+                    raise ValueError(f"Base URL cannot use localhost/loopback addresses in production: '{url}'")
+
+        except Exception as e:
+            if isinstance(e, ValueError):
+                raise
+            raise ValueError(f"Invalid base URL '{url}': {e}") from e
+
+        return url
+
+    @field_validator("issuer_url", "service_documentation_url")
+    @classmethod
+    def validate_optional_urls(cls, v: str | None) -> str | None:
+        """Validate optional URLs for security and format compliance."""
+        if not v:
+            return v
+
+        url = v.strip()
+        if not url:
+            return None
+
+        try:
+            parsed = urlparse(url)
+            if not parsed.scheme or not parsed.netloc:
+                raise ValueError(f"Invalid URL format: '{url}' - must include scheme and netloc")
+
+            if parsed.scheme not in ("http", "https"):
+                raise ValueError(f"URL must use http or https scheme: '{url}'")
+
+            # Check for HTTPS requirement in production for issuer URL
+            if v == cls.__dict__.get("issuer_url"):  # This is the issuer_url field
+                is_production = (
+                    os.environ.get("GOLF_ENV", "").lower() in ("prod", "production")
+                    or os.environ.get("NODE_ENV", "").lower() == "production"
+                    or os.environ.get("ENVIRONMENT", "").lower() in ("prod", "production")
+                )
+
+                if is_production and parsed.scheme == "http":
+                    import warnings
+
+                    warnings.warn(
+                        f"Issuer URL '{url}' uses HTTP in production. HTTPS is required for OAuth issuer URLs.",
+                        UserWarning,
+                        stacklevel=2,
+                    )
+
+        except Exception as e:
+            if isinstance(e, ValueError):
+                raise
+            raise ValueError(f"Invalid URL '{url}': {e}") from e
+
+        return url
+
+    @field_validator("valid_scopes", "default_scopes", "required_scopes")
+    @classmethod
+    def validate_scopes(cls, v: list[str]) -> list[str]:
+        """Validate OAuth 2.0 scopes format and security."""
+        if not v:
+            return v
+
+        valid_scopes = []
+        for scope in v:
+            scope = scope.strip()
+            if not scope:
+                raise ValueError("Scopes cannot be empty or whitespace-only")
+
+            # OAuth 2.0 scope format validation (RFC 6749)
+            # Scopes should be ASCII printable characters except space, and no control characters
+            if not all(32 < ord(c) < 127 and c not in ' "\\' for c in scope):
+                raise ValueError(
+                    f"Invalid scope format: '{scope}' - must be ASCII printable without spaces, quotes, or backslashes"
+                )
+
+            # Reasonable length limit to prevent abuse
+            if len(scope) > 128:
+                raise ValueError(f"Scope too long: '{scope}' - maximum 128 characters")
+
+            # Prevent potentially dangerous scope names
+            dangerous_scopes = {"admin", "root", "superuser", "system", "*", "all"}
+            if scope.lower() in dangerous_scopes:
+                import warnings
+
+                warnings.warn(
+                    f"Potentially dangerous scope detected: '{scope}'. "
+                    "Consider using more specific, principle-of-least-privilege scopes.",
+                    UserWarning,
+                    stacklevel=2,
+                )
+
+            valid_scopes.append(scope)
+
+        return valid_scopes
+
+    @model_validator(mode="after")
+    def validate_oauth_server_config(self) -> "OAuthServerConfig":
+        """Validate OAuth server configuration for security and consistency."""
+        # Validate default_scopes are subset of valid_scopes
+        if self.default_scopes and self.valid_scopes:
+            invalid_defaults = set(self.default_scopes) - set(self.valid_scopes)
+            if invalid_defaults:
+                raise ValueError(f"default_scopes contains invalid scopes not in valid_scopes: {invalid_defaults}")
+
+        # Validate required_scopes are subset of valid_scopes
+        if self.required_scopes and self.valid_scopes:
+            invalid_required = set(self.required_scopes) - set(self.valid_scopes)
+            if invalid_required:
+                raise ValueError(f"required_scopes contains invalid scopes not in valid_scopes: {invalid_required}")
+
+        return self
+
+
+class RemoteAuthConfig(BaseModel):
+    """Configuration for remote authorization server integration.
+
+    Use this when you have token verification logic and want to advertise
+    the authorization servers that issue valid tokens (RFC 9728 compliance).
+    """
+
+    provider_type: Literal["remote"] = "remote"
+
+    # Authorization servers that issue tokens
+    authorization_servers: list[str] = Field(
+        ..., description="List of authorization server URLs that issue valid tokens"
+    )
+
+    # This server's URL
+    resource_server_url: str = Field(..., description="URL of this resource server")
+
+    # Token verification (delegate to another config)
+    token_verifier_config: JWTAuthConfig | StaticTokenConfig = Field(
+        ..., description="Configuration for the underlying token verifier"
+    )
+
+    # Environment variable names for runtime configuration
+    authorization_servers_env_var: str | None = Field(
+        None, description="Environment variable name for comma-separated authorization server URLs"
+    )
+    resource_server_url_env_var: str | None = Field(
+        None, description="Environment variable name for resource server URL"
+    )
+
+    @field_validator("authorization_servers")
+    @classmethod
+    def validate_authorization_servers(cls, v: list[str]) -> list[str]:
+        """Validate authorization servers are non-empty and valid URLs."""
+        if not v:
+            raise ValueError(
+                "authorization_servers cannot be empty - at least one authorization server URL is required"
+            )
+
+        valid_urls = []
+        for url in v:
+            url = url.strip()
+            if not url:
+                raise ValueError("authorization_servers cannot contain empty URLs")
+
+            # Validate URL format
+            try:
+                parsed = urlparse(url)
+                if not parsed.scheme or not parsed.netloc:
+                    raise ValueError(
+                        f"Invalid URL format for authorization server: '{url}' - must include scheme and netloc"
+                    )
+                if parsed.scheme not in ("http", "https"):
+                    raise ValueError(f"Authorization server URL must use http or https scheme: '{url}'")
+            except Exception as e:
+                raise ValueError(f"Invalid authorization server URL '{url}': {e}") from e
+
+            valid_urls.append(url)
+
+        return valid_urls
+
+    @field_validator("resource_server_url")
+    @classmethod
+    def validate_resource_server_url(cls, v: str) -> str:
+        """Validate resource server URL is a valid URL."""
+        if not v or not v.strip():
+            raise ValueError("resource_server_url cannot be empty")
+
+        url = v.strip()
+        try:
+            parsed = urlparse(url)
+            if not parsed.scheme or not parsed.netloc:
+                raise ValueError(f"Invalid URL format for resource server: '{url}' - must include scheme and netloc")
+            if parsed.scheme not in ("http", "https"):
+                raise ValueError(f"Resource server URL must use http or https scheme: '{url}'")
+        except Exception as e:
+            raise ValueError(f"Invalid resource server URL '{url}': {e}") from e
+
+        return url
+
+    @model_validator(mode="after")
+    def validate_token_verifier_compatibility(self) -> "RemoteAuthConfig":
+        """Validate that the token verifier config is compatible with token verification."""
+        # The duck-typing check is already handled by the factory function, but we can
+        # add a basic sanity check here that the config types are ones we know work
+        config = self.token_verifier_config
+
+        if not isinstance(config, JWTAuthConfig | StaticTokenConfig):
+            raise ValueError(
+                f"token_verifier_config must be JWTAuthConfig or StaticTokenConfig, got {type(config).__name__}"
+            )
+
+        # For JWT configs, ensure they have the minimum required fields
+        if isinstance(config, JWTAuthConfig) and (
+            not config.public_key
+            and not config.jwks_uri
+            and not config.public_key_env_var
+            and not config.jwks_uri_env_var
+        ):
+            raise ValueError(
+                "JWT token verifier config must provide public_key, jwks_uri, or their environment variable equivalents"
+            )
+
+        # For static token configs, ensure they have tokens
+        if isinstance(config, StaticTokenConfig) and not config.tokens:
+            raise ValueError("Static token verifier config must provide at least one token")
+
+        return self
+
+
+# Union type for all auth configurations
+AuthConfig = JWTAuthConfig | StaticTokenConfig | OAuthServerConfig | RemoteAuthConfig

golf/auth/registry.py

@@ -0,0 +1,256 @@
+"""Provider registry system for extensible authentication providers.
+
+This module provides a registry-based dispatch system that allows custom
+authentication providers to be added without modifying the core factory code.
+"""
+
+from typing import Protocol, TYPE_CHECKING
+from abc import ABC, abstractmethod
+
+if TYPE_CHECKING:
+    from fastmcp.server.auth.auth import AuthProvider
+
+from .providers import AuthConfig
+
+
+class AuthProviderFactory(Protocol):
+    """Protocol for auth provider factory functions.
+
+    Custom provider factories must implement this interface to be compatible
+    with the registry system.
+    """
+
+    def __call__(self, config: AuthConfig) -> "AuthProvider":
+        """Create an AuthProvider from configuration.
+
+        Args:
+            config: Authentication configuration object
+
+        Returns:
+            Configured FastMCP AuthProvider instance
+
+        Raises:
+            ValueError: If configuration is invalid
+            ImportError: If required dependencies are missing
+        """
+        ...
+
+
+class BaseProviderPlugin(ABC):
+    """Base class for auth provider plugins.
+
+    Provider plugins can extend this class to provide both configuration
+    and factory logic in a single cohesive unit.
+    """
+
+    @property
+    @abstractmethod
+    def provider_type(self) -> str:
+        """Return the provider type identifier."""
+        ...
+
+    @property
+    @abstractmethod
+    def config_class(self) -> type[AuthConfig]:
+        """Return the configuration class for this provider."""
+        ...
+
+    @abstractmethod
+    def create_provider(self, config: AuthConfig) -> "AuthProvider":
+        """Create the auth provider from configuration.
+
+        Args:
+            config: Authentication configuration (must be instance of config_class)
+
+        Returns:
+            Configured FastMCP AuthProvider instance
+        """
+        ...
+
+    def validate_config(self, config: AuthConfig) -> None:
+        """Validate the configuration before creating provider.
+
+        Override this method to add custom validation logic.
+        Default implementation checks config is correct type.
+
+        Args:
+            config: Configuration to validate
+
+        Raises:
+            ValueError: If configuration is invalid
+        """
+        if not isinstance(config, self.config_class):
+            raise ValueError(
+                f"Expected {self.config_class.__name__} for {self.provider_type} provider, got {type(config).__name__}"
+            )
+
+
+class AuthProviderRegistry:
+    """Registry for authentication provider factories and plugins.
+
+    This registry allows custom authentication providers to be registered
+    without modifying the core factory code. Providers can be registered
+    either as simple factory functions or as full plugin classes.
+    """
+
+    def __init__(self) -> None:
+        self._factories: dict[str, AuthProviderFactory] = {}
+        self._plugins: dict[str, BaseProviderPlugin] = {}
+
+    def register_factory(self, provider_type: str, factory: AuthProviderFactory) -> None:
+        """Register a factory function for a provider type.
+
+        Args:
+            provider_type: Unique identifier for the provider type
+            factory: Factory function that creates providers
+
+        Raises:
+            ValueError: If provider_type is already registered
+        """
+        if provider_type in self._factories or provider_type in self._plugins:
+            raise ValueError(f"Provider type '{provider_type}' is already registered")
+
+        self._factories[provider_type] = factory
+
+    def register_plugin(self, plugin: BaseProviderPlugin) -> None:
+        """Register a provider plugin.
+
+        Args:
+            plugin: Provider plugin instance
+
+        Raises:
+            ValueError: If provider type is already registered
+        """
+        provider_type = plugin.provider_type
+        if provider_type in self._factories or provider_type in self._plugins:
+            raise ValueError(f"Provider type '{provider_type}' is already registered")
+
+        self._plugins[provider_type] = plugin
+
+    def unregister(self, provider_type: str) -> None:
+        """Unregister a provider type.
+
+        Args:
+            provider_type: Provider type to remove
+
+        Raises:
+            KeyError: If provider type is not registered
+        """
+        if provider_type in self._factories:
+            del self._factories[provider_type]
+        elif provider_type in self._plugins:
+            del self._plugins[provider_type]
+        else:
+            raise KeyError(f"Provider type '{provider_type}' is not registered")
+
+    def get_factory(self, provider_type: str) -> AuthProviderFactory:
+        """Get factory function for a provider type.
+
+        Args:
+            provider_type: Provider type to look up
+
+        Returns:
+            Factory function for the provider type
+
+        Raises:
+            KeyError: If provider type is not registered
+        """
+        # Check factories first
+        if provider_type in self._factories:
+            return self._factories[provider_type]
+
+        # Check plugins
+        if provider_type in self._plugins:
+            plugin = self._plugins[provider_type]
+
+            # Wrap plugin method to match factory signature
+            def plugin_factory(config: AuthConfig) -> "AuthProvider":
+                plugin.validate_config(config)
+                return plugin.create_provider(config)
+
+            return plugin_factory
+
+        raise KeyError(f"No provider registered for type '{provider_type}'")
+
+    def create_provider(self, config: AuthConfig) -> "AuthProvider":
+        """Create a provider from configuration using the registry.
+
+        Args:
+            config: Authentication configuration
+
+        Returns:
+            Configured AuthProvider instance
+
+        Raises:
+            KeyError: If provider type is not registered
+            ValueError: If configuration is invalid
+        """
+        provider_type = getattr(config, "provider_type", None)
+        if not provider_type:
+            raise ValueError(f"Configuration {type(config).__name__} missing provider_type attribute")
+
+        factory = self.get_factory(provider_type)
+        return factory(config)
+
+    def list_providers(self) -> list[str]:
+        """List all registered provider types.
+
+        Returns:
+            List of provider type identifiers
+        """
+        return sorted(list(self._factories.keys()) + list(self._plugins.keys()))
+
+    def is_registered(self, provider_type: str) -> bool:
+        """Check if a provider type is registered.
+
+        Args:
+            provider_type: Provider type to check
+
+        Returns:
+            True if provider type is registered
+        """
+        return provider_type in self._factories or provider_type in self._plugins
+
+
+# Global registry instance
+_default_registry = AuthProviderRegistry()
+
+
+def get_provider_registry() -> AuthProviderRegistry:
+    """Get the default provider registry.
+
+    Returns:
+        Default AuthProviderRegistry instance
+    """
+    return _default_registry
+
+
+def register_provider_factory(provider_type: str, factory: AuthProviderFactory) -> None:
+    """Register a factory function in the default registry.
+
+    Args:
+        provider_type: Unique identifier for the provider type
+        factory: Factory function that creates providers
+    """
+    _default_registry.register_factory(provider_type, factory)
+
+
+def register_provider_plugin(plugin: BaseProviderPlugin) -> None:
+    """Register a provider plugin in the default registry.
+
+    Args:
+        plugin: Provider plugin instance
+    """
+    _default_registry.register_plugin(plugin)
+
+
+def create_auth_provider_from_registry(config: AuthConfig) -> "AuthProvider":
+    """Create an auth provider using the default registry.
+
+    Args:
+        config: Authentication configuration
+
+    Returns:
+        Configured AuthProvider instance
+    """
+    return _default_registry.create_provider(config)