gopher-mcp-python 0.1.2.1__tar.gz → 0.1.15__tar.gz

{gopher_mcp_python-0.1.2.1 → gopher_mcp_python-0.1.15}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gopher-mcp-python
-Version: 0.1.2.1
+Version: 0.1.15
 Summary: Python SDK for Gopher MCP - AI Agent orchestration framework with native performance
 Author-email: Gopher Security <dev@gophersecurity.com>
 License: Apache-2.0

{gopher_mcp_python-0.1.2.1 → gopher_mcp_python-0.1.15}/gopher_mcp_python/__init__.py

@@ -25,7 +25,12 @@ Example:
 from gopher_mcp_python.agent import GopherAgent
 from gopher_mcp_python.config import GopherAgentConfig, GopherAgentConfigBuilder
 from gopher_mcp_python.result import AgentResult, AgentResultStatus, AgentResultBuilder
-from gopher_mcp_python.errors import AgentError, ApiKeyError, ConnectionError, TimeoutError
+from gopher_mcp_python.errors import (
+    AgentError,
+    ApiKeyError,
+    ConnectionError,
+    TimeoutError,
+)
 from gopher_mcp_python.server_config import ServerConfig
 from gopher_mcp_python.ffi import GopherOrchLibrary
 
@@ -45,7 +50,7 @@ from gopher_mcp_python.ffi.auth import (
     is_auth_available,
 )
 
-__version__ = "0.1.2"
+__version__ = "0.1.15"
 
 __all__ = [
     # Main classes

gopher_mcp_python-0.1.15/gopher_mcp_python/auth/__init__.py

@@ -0,0 +1,31 @@
+"""
+Auth Module - Reusable OAuth/JWT authentication for Python MCP servers.
+"""
+
+from gopher_mcp_python.auth.gopher_auth import GopherAuth
+from gopher_mcp_python.auth.errors import (
+    GopherAuthError,
+    TokenValidationError,
+    InsufficientScopesError,
+    JwksError,
+    ConfigurationError,
+    TokenExchangeError,
+)
+from gopher_mcp_python.auth.scope_helpers import (
+    has_scope,
+    has_all_scopes,
+    has_any_scope,
+)
+
+__all__ = [
+    "GopherAuth",
+    "GopherAuthError",
+    "TokenValidationError",
+    "InsufficientScopesError",
+    "JwksError",
+    "ConfigurationError",
+    "TokenExchangeError",
+    "has_scope",
+    "has_all_scopes",
+    "has_any_scope",
+]

gopher_mcp_python-0.1.15/gopher_mcp_python/auth/errors.py

@@ -0,0 +1,48 @@
+"""Custom error classes for the auth module."""
+
+
+class GopherAuthError(Exception):
+    """Base error for auth operations."""
+
+    pass
+
+
+class TokenValidationError(GopherAuthError):
+    """Token validation failed."""
+
+    def __init__(self, message: str, error_code: int = 0):
+        super().__init__(message)
+        self.error_code = error_code
+
+
+class InsufficientScopesError(GopherAuthError):
+    """Required scopes not present."""
+
+    def __init__(self, required_scopes: list, actual_scopes: list, message: str = ""):
+        msg = message or (
+            f"Insufficient scopes: required {required_scopes}, actual {actual_scopes}"
+        )
+        super().__init__(msg)
+        self.required_scopes = required_scopes
+        self.actual_scopes = actual_scopes
+
+
+class JwksError(GopherAuthError):
+    """JWKS fetch or parsing failed."""
+
+    pass
+
+
+class ConfigurationError(GopherAuthError):
+    """Invalid configuration."""
+
+    pass
+
+
+class TokenExchangeError(GopherAuthError):
+    """Token exchange failed."""
+
+    def __init__(self, message: str, error_code: str = "", error_description: str = ""):
+        super().__init__(message)
+        self.error_code = error_code
+        self.error_description = error_description

gopher_mcp_python-0.1.15/gopher_mcp_python/auth/gopher_auth.py

@@ -0,0 +1,255 @@
+"""
+GopherAuth - Reusable auth module for Python.
+
+Provides OAuth 2.0 / JWT authentication via native FFI bindings.
+Matches the JS SDK's GopherAuth class API surface.
+"""
+
+from typing import Any, Dict, List, Optional
+
+from gopher_mcp_python.ffi.auth.auth_client import (
+    GopherAuthClient,
+    gopher_init_auth_library,
+    gopher_shutdown_auth_library,
+    gopher_generate_www_authenticate_header_v2,
+)
+from gopher_mcp_python.ffi.auth.config_loader import GopherAuthConfig
+from gopher_mcp_python.ffi.auth.oauth_client import GopherOAuthClient, TokenResponse
+from gopher_mcp_python.ffi.auth.session_manager import GopherSessionManager
+from gopher_mcp_python.ffi.auth.loader import (
+    gopher_auth_build_protected_resource_metadata,
+)
+from gopher_mcp_python.ffi.auth.types import TokenPayload, GopherAuthContext
+
+from gopher_mcp_python.auth.errors import (
+    ConfigurationError,
+    TokenValidationError,
+    InsufficientScopesError,
+    TokenExchangeError,
+)
+from gopher_mcp_python.auth.scope_helpers import (
+    has_scope,
+    has_all_scopes,
+    has_any_scope,
+)
+
+
+class GopherAuth:
+    """Reusable auth module wrapping native FFI bindings."""
+
+    def __init__(
+        self,
+        config_path: Optional[str] = None,
+        config: Optional[Dict[str, Any]] = None,
+        auth_disabled: bool = False,
+    ) -> None:
+        self._config_path = config_path
+        self._config_dict = config
+        self._auth_disabled = auth_disabled
+        self._config: Optional[GopherAuthConfig] = None
+        self._auth_client: Optional[GopherAuthClient] = None
+        self._oauth_client: Optional[GopherOAuthClient] = None
+        self._session_manager: Optional[GopherSessionManager] = None
+        self._initialized = False
+
+    def initialize(self) -> None:
+        """Initialize the auth module. Must be called before any other method."""
+        if self._initialized:
+            return
+
+        if self._auth_disabled:
+            self._initialized = True
+            return
+
+        gopher_init_auth_library()
+
+        if self._config_path:
+            self._config = GopherAuthConfig.load_file(self._config_path)
+        elif self._config_dict:
+            pairs: Dict[str, str] = {}
+            mapping = {
+                "auth_server_url": "auth_server_url",
+                "client_id": "client_id",
+                "client_secret": "client_secret",
+                "audience": "audience",
+                "issuer": "issuer",
+                "jwks_uri": "jwks_uri",
+                "oauth_authorize_url": "oauth_authorize_url",
+                "oauth_token_url": "oauth_token_url",
+                "server_url": "server_url",
+                "allowed_scopes": "allowed_scopes",
+                "exchange_idps": "exchange_idps",
+                "host": "host",
+                "port": "port",
+            }
+            for py_key, cfg_key in mapping.items():
+                val = self._config_dict.get(py_key)
+                if val is not None:
+                    pairs[cfg_key] = str(val)
+            self._config = GopherAuthConfig.load_from_pairs(pairs)
+        else:
+            raise ConfigurationError("Either config_path or config must be provided")
+
+        # Create auth client
+        jwks_uri = self._config.get_string("jwks_uri")
+        issuer = self._config.get_string("issuer")
+        if jwks_uri and issuer:
+            self._auth_client = GopherAuthClient(jwks_uri, issuer)
+            cache_dur = self._config.get_string("jwks_cache_duration")
+            if cache_dur:
+                self._auth_client.set_option("cache_duration", cache_dur)
+
+        # Create OAuth client
+        token_endpoint = self._config.get_string("token_endpoint")
+        client_id = self._config.get_string("client_id")
+        client_secret = self._config.get_string("client_secret")
+        if token_endpoint and client_id:
+            self._oauth_client = GopherOAuthClient(
+                token_endpoint, client_id, client_secret or None, 30
+            )
+
+        self._session_manager = GopherSessionManager(300)
+        self._initialized = True
+
+    def shutdown(self) -> None:
+        """Shutdown and release all native resources."""
+        if self._session_manager:
+            self._session_manager.destroy()
+        if self._oauth_client:
+            self._oauth_client.destroy()
+        if self._auth_client:
+            self._auth_client.destroy()
+        if self._config:
+            self._config.destroy()
+        self._session_manager = None
+        self._oauth_client = None
+        self._auth_client = None
+        self._config = None
+        if self._initialized and not self._auth_disabled:
+            gopher_shutdown_auth_library()
+        self._initialized = False
+
+    def validate_token(
+        self,
+        token: str,
+        required_scopes: Optional[List[str]] = None,
+    ) -> TokenPayload:
+        """Validate a JWT token. Raises on failure."""
+        self._ensure_initialized()
+        if not self._auth_client:
+            raise TokenValidationError("Auth client not initialized")
+
+        result = self._auth_client.validate_token(token)
+        if not result or not result.valid:
+            raise TokenValidationError(
+                result.error_message if result else "Token validation failed",
+                result.error_code if result else 0,
+            )
+
+        payload = self._auth_client.extract_payload(token)
+        if not payload:
+            raise TokenValidationError("Failed to extract payload")
+
+        if required_scopes:
+            token_scopes = [s for s in payload.scopes.split(" ") if s]
+            missing = [s for s in required_scopes if s not in token_scopes]
+            if missing:
+                raise InsufficientScopesError(required_scopes, token_scopes)
+
+        return payload
+
+    def has_scope(self, payload: TokenPayload, scope: str) -> bool:
+        ctx = GopherAuthContext(
+            user_id=payload.subject,
+            scopes=payload.scopes,
+            audience=payload.audience or "",
+            token_expiry=payload.expiration or 0,
+            authenticated=True,
+        )
+        return has_scope(ctx, scope)
+
+    def has_all_scopes(self, payload: TokenPayload, scopes: List[str]) -> bool:
+        ctx = GopherAuthContext(
+            user_id=payload.subject,
+            scopes=payload.scopes,
+            audience=payload.audience or "",
+            token_expiry=payload.expiration or 0,
+            authenticated=True,
+        )
+        return has_all_scopes(ctx, scopes)
+
+    def has_any_scope(self, payload: TokenPayload, scopes: List[str]) -> bool:
+        ctx = GopherAuthContext(
+            user_id=payload.subject,
+            scopes=payload.scopes,
+            audience=payload.audience or "",
+            token_expiry=payload.expiration or 0,
+            authenticated=True,
+        )
+        return has_any_scope(ctx, scopes)
+
+    def exchange_token(
+        self,
+        subject_token: str,
+        requested_issuer: str,
+        audience: Optional[str] = None,
+        scope: Optional[str] = None,
+    ) -> TokenResponse:
+        """Exchange a token (RFC 8693). Raises on failure."""
+        self._ensure_initialized()
+        if not self._oauth_client:
+            raise TokenExchangeError("OAuth client not initialized")
+        result = self._oauth_client.token_exchange(
+            subject_token, requested_issuer, audience, scope
+        )
+        if not result.success:
+            raise TokenExchangeError(
+                result.error or "Token exchange failed",
+                result.error or "",
+            )
+        return result
+
+    def get_protected_resource_metadata(self) -> dict:
+        server_url = self._config.get_string("server_url") if self._config else ""
+        scopes = self._config.get_string("allowed_scopes") if self._config else ""
+        return gopher_auth_build_protected_resource_metadata(
+            f"{server_url}/mcp", server_url, scopes or None
+        )
+
+    def get_www_authenticate_header(
+        self,
+        error: str = "",
+        error_description: str = "",
+    ) -> str:
+        server_url = self._config.get_string("server_url") if self._config else ""
+        resource_metadata = f"{server_url}/.well-known/oauth-protected-resource"
+        return (
+            gopher_generate_www_authenticate_header_v2(
+                server_url, resource_metadata, "", error, error_description
+            )
+            or "Bearer"
+        )
+
+    def get_token_endpoint(self) -> str:
+        return self._config.get_string("token_endpoint") if self._config else ""
+
+    @property
+    def native_config(self) -> Optional[GopherAuthConfig]:
+        return self._config
+
+    @property
+    def is_disabled(self) -> bool:
+        return self._auth_disabled
+
+    def __enter__(self) -> "GopherAuth":
+        self.initialize()
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.shutdown()
+
+    def _ensure_initialized(self) -> None:
+        if not self._initialized:
+            raise ConfigurationError(
+                "GopherAuth not initialized. Call initialize() first."
+            )

gopher_mcp_python-0.1.15/gopher_mcp_python/auth/scope_helpers.py

@@ -0,0 +1,34 @@
+"""Scope validation helpers for per-request usage."""
+
+from typing import List, Optional
+
+from gopher_mcp_python.ffi.auth.types import GopherAuthContext
+from gopher_mcp_python.ffi.auth.loader import (
+    gopher_auth_validate_all_scopes,
+    gopher_auth_validate_any_scopes,
+)
+
+
+def has_scope(context: Optional[GopherAuthContext], scope: str) -> bool:
+    """Check if context has a specific scope."""
+    if not context or not context.scopes:
+        return False
+    return gopher_auth_validate_all_scopes(context.scopes, scope)
+
+
+def has_all_scopes(context: Optional[GopherAuthContext], scopes: List[str]) -> bool:
+    """Check if context has ALL required scopes (AND logic)."""
+    if not context or not context.scopes:
+        return len(scopes) == 0
+    if not scopes:
+        return True
+    return gopher_auth_validate_all_scopes(context.scopes, " ".join(scopes))
+
+
+def has_any_scope(context: Optional[GopherAuthContext], scopes: List[str]) -> bool:
+    """Check if context has ANY of the required scopes (OR logic)."""
+    if not context or not context.scopes:
+        return len(scopes) == 0
+    if not scopes:
+        return True
+    return gopher_auth_validate_any_scopes(context.scopes, " ".join(scopes))

{gopher_mcp_python-0.1.2.1 → gopher_mcp_python-0.1.15}/gopher_mcp_python/ffi/auth/__init__.py

@@ -33,6 +33,16 @@ from gopher_mcp_python.ffi.auth.validation_options import (
     gopher_create_validation_options,
 )
 
+from gopher_mcp_python.ffi.auth.config_loader import (
+    GopherAuthConfig,
+)
+
+from gopher_mcp_python.ffi.auth.oauth_client import (
+    GopherOAuthClient,
+    TokenResponse,
+    RegistrationResponse,
+)
+
 from gopher_mcp_python.ffi.auth.auth_client import (
     GopherAuthClient,
     gopher_init_auth_library,
@@ -71,6 +81,8 @@ __all__ = [
     # Validation options
     "GopherValidationOptions",
     "gopher_create_validation_options",
+    # Config loader
+    "GopherAuthConfig",
     # Auth client
     "GopherAuthClient",
     "gopher_init_auth_library",

{gopher_mcp_python-0.1.2.1 → gopher_mcp_python-0.1.15}/gopher_mcp_python/ffi/auth/auth_client.py

@@ -423,12 +423,22 @@ class GopherAuthClient:
                 if get_exp(payload_handle, byref(exp_value)) == GopherAuthError.SUCCESS:
                     expiration = exp_value.value
 
+            # Extract extended claims via payload_get_claim
+            email = self._get_payload_claim(payload_handle, "email")
+            name_val = self._get_payload_claim(payload_handle, "name")
+            organization_id = self._get_payload_claim(payload_handle, "organization_id")
+            server_id = self._get_payload_claim(payload_handle, "server_id")
+
             return TokenPayload(
                 subject=subject or "",
                 scopes=scopes or "",
                 audience=audience,
                 expiration=expiration,
                 issuer=issuer,
+                email=email,
+                name=name_val,
+                organization_id=organization_id,
+                server_id=server_id,
             )
         finally:
             # Clean up payload handle
@@ -472,6 +482,45 @@ class GopherAuthClient:
 
         return None
 
+    def _get_payload_claim(
+        self,
+        payload_handle: c_void_p,
+        claim_name: str,
+    ) -> Optional[str]:
+        """
+        Get a custom claim from payload by name.
+
+        Args:
+            payload_handle: The payload handle.
+            claim_name: The claim name to extract.
+
+        Returns:
+            The claim value, or None if not present.
+        """
+        funcs = get_auth_functions()
+        get_claim = funcs.get("payload_get_claim")
+        if get_claim is None:
+            return None
+
+        value_out = c_char_p()
+        result = get_claim(
+            payload_handle,
+            claim_name.encode("utf-8"),
+            byref(value_out),
+        )
+
+        if result != GopherAuthError.SUCCESS:
+            return None
+
+        if value_out.value:
+            value = value_out.value.decode("utf-8")
+            free_string = funcs.get("free_string")
+            if free_string:
+                free_string(value_out)
+            return value
+
+        return None
+
     def validate_and_extract(
         self,
         token: str,
@@ -515,6 +564,11 @@ class GopherAuthClient:
         self._handle = None
         self._destroyed = True
 
+    def get_handle(self) -> c_void_p:
+        """Get the native handle (for internal use by auto-refresh)."""
+        self._ensure_not_destroyed()
+        return self._handle
+
     def is_destroyed(self) -> bool:
         """
         Check if this client has been destroyed.

gopher_mcp_python-0.1.15/gopher_mcp_python/ffi/auth/auto_refresh.py

@@ -0,0 +1,89 @@
+"""
+Auto-Refresh - Combines session lookup, token refresh, and re-validation.
+"""
+
+from ctypes import POINTER, byref, c_char_p
+from dataclasses import dataclass
+from typing import Optional
+
+from gopher_mcp_python.ffi.auth.loader import (
+    GopherAuthValidationResult,
+    get_auth_functions,
+)
+from gopher_mcp_python.ffi.auth.auth_client import GopherAuthClient
+from gopher_mcp_python.ffi.auth.oauth_client import GopherOAuthClient
+from gopher_mcp_python.ffi.auth.session_manager import GopherSessionManager
+from gopher_mcp_python.ffi.auth.types import GopherAuthError
+
+
+@dataclass
+class AutoRefreshResult:
+    """Result of auto-refresh operation."""
+
+    valid: bool
+    new_access_token: Optional[str] = None
+    error_code: int = 0
+    error_message: Optional[str] = None
+
+
+def gopher_auth_auto_refresh(
+    auth_client: GopherAuthClient,
+    oauth_client: GopherOAuthClient,
+    session_manager: GopherSessionManager,
+    session_id: str,
+) -> AutoRefreshResult:
+    """
+    Auto-refresh: validate token, refresh if expired, re-validate.
+
+    If the token is still valid, new_access_token is None.
+    If refreshed, new_access_token contains the new token.
+    """
+    funcs = get_auth_functions()
+    fn = funcs.get("auto_refresh")
+    if not fn:
+        return AutoRefreshResult(
+            valid=False,
+            error_code=GopherAuthError.NOT_INITIALIZED,
+            error_message="Auto-refresh function not available",
+        )
+
+    token_out = c_char_p()
+    result_out = GopherAuthValidationResult()
+
+    err = fn(
+        auth_client.get_handle(),
+        oauth_client.get_handle(),
+        session_manager.get_handle(),
+        session_id.encode("utf-8"),
+        byref(token_out),
+        byref(result_out),
+    )
+
+    if err != GopherAuthError.SUCCESS:
+        return AutoRefreshResult(
+            valid=False,
+            error_code=err,
+            error_message=(
+                result_out.error_message.decode("utf-8")
+                if result_out.error_message
+                else f"Error code {err}"
+            ),
+        )
+
+    new_token = None
+    if token_out.value:
+        new_token = token_out.value.decode("utf-8")
+        free = funcs.get("free_string")
+        if free:
+            free(token_out)
+
+    return AutoRefreshResult(
+        valid=result_out.valid,
+        new_access_token=new_token,
+        error_code=result_out.error_code,
+        error_message=(
+            result_out.error_message.decode("utf-8")
+            if result_out.error_message
+            else None
+        ),
+    )