mcp-eregistrations-bpa 0.8.5__py3-none-any.whl

mcp_eregistrations_bpa/auth/permissions.py

@@ -0,0 +1,162 @@
+"""Permission enforcement for MCP tools.
+
+This module provides guards and utility functions to enforce
+BPA permissions before tool execution. All permission checks
+are server-side and based on JWT token claims.
+
+Usage in MCP tools:
+    @mcp.tool()
+    async def service_create(name: str) -> dict[str, object]:
+        # Ensure write permission before proceeding
+        access_token = await ensure_write_permission()
+        # ... use access_token for BPA API call
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from mcp.server.fastmcp.exceptions import ToolError
+
+logger = logging.getLogger(__name__)
+
+if TYPE_CHECKING:
+    from mcp_eregistrations_bpa.auth.token_manager import TokenManager
+
+__all__ = [
+    "PERMISSION_VIEWER",
+    "PERMISSION_SERVICE_DESIGNER",
+    "WRITE_PERMISSIONS",
+    "ensure_authenticated",
+    "ensure_write_permission",
+    "check_permission",
+]
+
+# Permission constants
+PERMISSION_VIEWER = "viewer"
+PERMISSION_SERVICE_DESIGNER = "service_designer"
+
+# Roles that allow write operations
+WRITE_PERMISSIONS: list[str] = [PERMISSION_SERVICE_DESIGNER]
+
+
+def get_token_manager() -> TokenManager:
+    """Get the global token manager instance.
+
+    Uses late import to avoid circular dependency with server.py.
+
+    Returns:
+        The global TokenManager instance.
+    """
+    from mcp_eregistrations_bpa.server import get_token_manager as _get_tm
+
+    return _get_tm()
+
+
+async def ensure_authenticated() -> str:
+    """Ensure user is authenticated and return access token.
+
+    Automatically triggers browser-based login if not authenticated.
+    Checks authentication status and token expiry. Calls
+    token_manager.get_access_token() which handles automatic
+    refresh if the token is near expiry.
+
+    Returns:
+        Valid access token for BPA API calls.
+
+    Raises:
+        ToolError: If authentication fails or token expired and cannot refresh.
+    """
+    token_manager = get_token_manager()
+    logger.debug("Checking authentication status...")
+
+    # Auto-trigger login if not authenticated
+    if not token_manager.is_authenticated():
+        logger.info("Not authenticated - initiating browser login flow")
+        from mcp_eregistrations_bpa.config import AuthProvider, load_config
+        from mcp_eregistrations_bpa.exceptions import AuthenticationError
+
+        try:
+            config = load_config()
+            if config.auth_provider == AuthProvider.CAS:
+                from mcp_eregistrations_bpa.auth.cas import perform_cas_browser_login
+
+                result = await perform_cas_browser_login()
+            else:
+                from mcp_eregistrations_bpa.auth.oidc import perform_browser_login
+
+                result = await perform_browser_login()
+
+            if result.get("error"):
+                logger.error("Authentication failed: %s", result.get("message"))
+                raise ToolError(str(result.get("message", "Authentication failed")))
+            logger.info("Authentication successful for user: %s", result.get("user"))
+        except AuthenticationError as e:
+            logger.error("Authentication error: %s", e)
+            raise ToolError(str(e))
+
+    # Check for expired token (shouldn't happen right after login, but handle it)
+    if token_manager.is_token_expired():
+        logger.warning("Token expired - user needs to re-authenticate")
+        raise ToolError("Session expired. Please run auth_login again.")
+
+    logger.debug("User authenticated: %s", token_manager.user_email)
+    # This will auto-refresh if within 5 minutes of expiry
+    return await token_manager.get_access_token()
+
+
+async def ensure_write_permission() -> str:
+    """Ensure user has write permission and return access token.
+
+    Combines authentication check with write permission verification.
+    Checks if user has any role in WRITE_PERMISSIONS.
+
+    Returns:
+        Valid access token for BPA API calls.
+
+    Raises:
+        ToolError: If not authenticated or lacks write permission.
+    """
+    # First ensure authenticated (raises if not)
+    token = await ensure_authenticated()
+
+    # Check for write permission
+    token_manager = get_token_manager()
+    user_permissions = set(token_manager.permissions)
+
+    if not user_permissions.intersection(WRITE_PERMISSIONS):
+        raise ToolError(
+            "Permission denied: You don't have write access. "
+            "Contact your administrator."
+        )
+
+    return token
+
+
+def check_permission(required_permission: str) -> None:
+    """Check if user has a specific permission.
+
+    This is a synchronous check that also validates authentication status.
+    Raises ToolError if not authenticated or if permission is missing.
+
+    Args:
+        required_permission: The permission role required.
+
+    Raises:
+        ToolError: If not authenticated or user lacks the required permission.
+    """
+    token_manager = get_token_manager()
+
+    # Verify authentication first (sync check - doesn't refresh)
+    if not token_manager.is_authenticated():
+        raise ToolError("Not authenticated. Run auth_login first.")
+
+    if token_manager.is_token_expired():
+        raise ToolError("Session expired. Please run auth_login again.")
+
+    if required_permission not in token_manager.permissions:
+        raise ToolError(
+            f"Permission denied: You need '{required_permission}' permission. "
+            "Contact your administrator."
+        )

mcp_eregistrations_bpa/auth/token_manager.py

@@ -0,0 +1,348 @@
+"""In-memory token storage and automatic refresh.
+
+This module handles token lifecycle management including storage,
+refresh, and expiry checks. Tokens are stored in memory only
+(never persisted to disk) per NFR2 and NFR6.
+"""
+
+import base64
+import json
+from datetime import UTC, datetime, timedelta
+
+import httpx
+from pydantic import BaseModel
+
+from mcp_eregistrations_bpa.exceptions import AuthenticationError
+
+# Refresh tokens 5 minutes before expiry (NFR3)
+REFRESH_THRESHOLD_SECONDS = 300
+
+
+class TokenResponse(BaseModel):
+    """Response from token endpoint."""
+
+    access_token: str
+    refresh_token: str | None = None
+    expires_in: int
+    token_type: str = "Bearer"
+
+
+class TokenManager:
+    """In-memory token storage with automatic refresh.
+
+    Tokens are stored in memory only and never persisted to disk.
+    Automatic refresh is triggered when the access token is within
+    5 minutes of expiry (NFR3).
+    """
+
+    def __init__(self) -> None:
+        """Initialize token manager with empty state."""
+        self._access_token: str | None = None
+        self._refresh_token: str | None = None
+        self._expires_at: datetime | None = None
+        self._token_endpoint: str | None = None
+        self._client_id: str | None = None
+        self._cas_client_secret: str | None = None  # CAS uses Basic Auth, no PKCE
+        self._user_email: str | None = None
+        self._permissions: list[str] = []
+
+    @property
+    def user_email(self) -> str | None:
+        """Get the authenticated user's email."""
+        return self._user_email
+
+    @property
+    def expires_in_minutes(self) -> int:
+        """Get remaining session time in minutes."""
+        if self._expires_at is None:
+            return 0
+        remaining = self._expires_at - datetime.now(UTC)
+        return max(0, int(remaining.total_seconds() / 60))
+
+    @property
+    def permissions(self) -> list[str]:
+        """Get the authenticated user's permissions/roles.
+
+        Returns a copy to prevent external mutation of internal state.
+        """
+        return list(self._permissions)
+
+    def is_token_expired(self) -> bool:
+        """Check if a stored token has already expired (without triggering refresh).
+
+        This method should only be called after verifying is_authenticated() is True.
+        When no token exists (_expires_at is None), returns False because there's
+        nothing to consider "expired" - use is_authenticated() to check presence.
+
+        Returns:
+            True if token exists AND is expired, False otherwise.
+        """
+        if self._expires_at is None:
+            return False
+        return datetime.now(UTC) >= self._expires_at
+
+    def is_authenticated(self) -> bool:
+        """Check if we have valid tokens.
+
+        Returns:
+            True if we have tokens (may need refresh), False if not authenticated.
+        """
+        return self._access_token is not None
+
+    def store_tokens(
+        self,
+        access_token: str,
+        refresh_token: str | None,
+        expires_in: int,
+        token_endpoint: str | None = None,
+        client_id: str | None = None,
+    ) -> None:
+        """Store tokens in memory.
+
+        Args:
+            access_token: The access token from Keycloak.
+            refresh_token: The refresh token from Keycloak.
+            expires_in: Token lifetime in seconds.
+            token_endpoint: The token endpoint for refresh (optional).
+            client_id: The client ID for refresh (optional).
+        """
+        self._access_token = access_token
+        self._refresh_token = refresh_token
+        self._expires_at = datetime.now(UTC) + timedelta(seconds=expires_in)
+
+        if token_endpoint:
+            self._token_endpoint = token_endpoint
+        if client_id:
+            self._client_id = client_id
+
+        # Extract user email and permissions from access token
+        self._user_email = self._extract_email_from_token(access_token)
+        self._permissions = self._extract_permissions_from_token(access_token)
+
+    def clear_tokens(self) -> None:
+        """Clear all stored tokens (logout)."""
+        self._access_token = None
+        self._refresh_token = None
+        self._expires_at = None
+        self._user_email = None
+        self._permissions = []
+
+    def _needs_refresh(self) -> bool:
+        """Check if token needs refresh (within 5 minutes of expiry).
+
+        Returns:
+            True if token should be refreshed, False otherwise.
+        """
+        if self._expires_at is None:
+            return False
+        threshold = datetime.now(UTC) + timedelta(seconds=REFRESH_THRESHOLD_SECONDS)
+        return self._expires_at <= threshold
+
+    async def get_access_token(self) -> str:
+        """Get valid access token, refreshing if needed.
+
+        Returns:
+            A valid access token.
+
+        Raises:
+            AuthenticationError: If not authenticated or refresh fails.
+        """
+        if self._access_token is None:
+            raise AuthenticationError("Not authenticated. Run auth_login first.")
+
+        if self._needs_refresh():
+            await self._refresh()
+
+        if self._access_token is None:
+            raise AuthenticationError("Session expired. Please run auth_login again.")
+
+        return self._access_token
+
+    async def _refresh(self) -> None:
+        """Refresh the access token using refresh token.
+
+        Raises:
+            AuthenticationError: If refresh fails.
+        """
+        if self._refresh_token is None:
+            raise AuthenticationError("Session expired. Please run auth_login again.")
+
+        if self._token_endpoint is None or self._client_id is None:
+            raise AuthenticationError("Session expired. Please run auth_login again.")
+
+        async with httpx.AsyncClient() as client:
+            try:
+                response = await client.post(
+                    self._token_endpoint,
+                    data={
+                        "grant_type": "refresh_token",
+                        "refresh_token": self._refresh_token,
+                        "client_id": self._client_id,
+                    },
+                    timeout=10.0,
+                )
+                response.raise_for_status()
+            except httpx.HTTPStatusError as e:
+                # Refresh token is invalid/expired
+                self.clear_tokens()
+                raise AuthenticationError(
+                    "Session expired. Please run auth_login again."
+                ) from e
+            except httpx.RequestError as e:
+                raise AuthenticationError(
+                    f"Cannot refresh session: {e}. Please try again."
+                ) from e
+
+            data = response.json()
+            self.store_tokens(
+                access_token=data["access_token"],
+                refresh_token=data.get("refresh_token", self._refresh_token),
+                expires_in=data["expires_in"],
+            )
+
+    def _decode_jwt_payload(self, token: str) -> dict[str, object] | None:
+        """Decode and return JWT payload claims.
+
+        Args:
+            token: The JWT access token.
+
+        Returns:
+            Decoded claims dict, or None if decoding fails.
+        """
+        try:
+            # JWT is three base64-encoded parts separated by dots
+            parts = token.split(".")
+            if len(parts) != 3:
+                return None
+
+            # Decode the payload (second part)
+            payload = parts[1]
+            # Add padding if needed
+            padding = 4 - len(payload) % 4
+            if padding != 4:
+                payload += "=" * padding
+
+            decoded = base64.urlsafe_b64decode(payload)
+            claims: dict[str, object] = json.loads(decoded)
+            return claims
+        except Exception:
+            return None
+
+    def _extract_email_from_token(self, token: str) -> str | None:
+        """Extract user email from JWT access token.
+
+        Args:
+            token: The JWT access token.
+
+        Returns:
+            The user email if found, None otherwise.
+        """
+        claims = self._decode_jwt_payload(token)
+        if claims is None:
+            return None
+
+        # Try common email claim names
+        email = claims.get("email") or claims.get("preferred_username")
+        return str(email) if email else None
+
+    def _extract_permissions_from_token(self, token: str) -> list[str]:
+        """Extract permissions/roles from JWT access token.
+
+        Parses Keycloak standard claims for realm and resource access roles.
+
+        Args:
+            token: The JWT access token.
+
+        Returns:
+            List of role names from realm_access and resource_access claims.
+        """
+        claims = self._decode_jwt_payload(token)
+        if claims is None:
+            return []
+
+        roles: list[str] = []
+
+        # Extract realm roles (Keycloak standard)
+        realm_access = claims.get("realm_access")
+        if isinstance(realm_access, dict) and "roles" in realm_access:
+            roles.extend(realm_access["roles"])
+
+        # Extract client-specific roles (Keycloak resource_access)
+        resource_access = claims.get("resource_access")
+        if isinstance(resource_access, dict):
+            for _client, access in resource_access.items():
+                if isinstance(access, dict) and "roles" in access:
+                    roles.extend(access["roles"])
+
+        # Deduplicate while preserving order
+        seen: set[str] = set()
+        unique_roles: list[str] = []
+        for role in roles:
+            if role not in seen:
+                seen.add(role)
+                unique_roles.append(role)
+
+        return unique_roles
+
+
+async def exchange_code_for_tokens(
+    token_endpoint: str,
+    code: str,
+    code_verifier: str,
+    redirect_uri: str,
+    client_id: str,
+) -> TokenResponse:
+    """Exchange authorization code for tokens.
+
+    Args:
+        token_endpoint: The Keycloak token endpoint.
+        code: The authorization code from callback.
+        code_verifier: The PKCE code verifier.
+        redirect_uri: The redirect URI used in authorization.
+        client_id: The OIDC client ID.
+
+    Returns:
+        TokenResponse with access and refresh tokens.
+
+    Raises:
+        AuthenticationError: If token exchange fails.
+    """
+    async with httpx.AsyncClient() as client:
+        try:
+            response = await client.post(
+                token_endpoint,
+                data={
+                    "grant_type": "authorization_code",
+                    "code": code,
+                    "redirect_uri": redirect_uri,
+                    "client_id": client_id,
+                    "code_verifier": code_verifier,
+                },
+                timeout=10.0,
+            )
+            response.raise_for_status()
+        except httpx.HTTPStatusError as e:
+            error_detail = ""
+            try:
+                error_data = e.response.json()
+                error_detail = error_data.get(
+                    "error_description", error_data.get("error", "")
+                )
+            except Exception:
+                pass
+            raise AuthenticationError(
+                f"Authentication failed: {error_detail or 'Token exchange failed'}. "
+                "Please try again."
+            ) from e
+        except httpx.RequestError as e:
+            raise AuthenticationError(
+                f"Authentication failed: {e}. Please try again."
+            ) from e
+
+        data = response.json()
+        return TokenResponse(
+            access_token=data["access_token"],
+            refresh_token=data.get("refresh_token"),
+            expires_in=data["expires_in"],
+            token_type=data.get("token_type", "Bearer"),
+        )

mcp_eregistrations_bpa/bpa_client/__init__.py

@@ -0,0 +1,84 @@
+"""BPA API client module.
+
+This module provides the BPAClient for interacting with the BPA REST API.
+
+Main exports:
+    BPAClient: Async HTTP client with retry logic and auth integration.
+
+Example:
+    from mcp_eregistrations_bpa.bpa_client import BPAClient
+
+    async with BPAClient() as client:
+        services = await client.get("/service")
+        service = await client.get("/service/{id}", path_params={"id": 123})
+"""
+
+from mcp_eregistrations_bpa.bpa_client.client import (
+    BASE_DELAY,
+    DEFAULT_TIMEOUT,
+    MAX_DELAY,
+    MAX_RETRIES,
+    NON_RETRYABLE_STATUS_CODES,
+    RETRYABLE_STATUS_CODES,
+    BPAClient,
+)
+from mcp_eregistrations_bpa.bpa_client.errors import (
+    BPAAuthenticationError,
+    BPAClientError,
+    BPAConnectionError,
+    BPANotFoundError,
+    BPAPermissionError,
+    BPARateLimitError,
+    BPAServerError,
+    BPATimeoutError,
+    BPAValidationError,
+    translate_error,
+)
+from mcp_eregistrations_bpa.bpa_client.models import (
+    Action,
+    BPABaseModel,
+    Cost,
+    Determinant,
+    Document,
+    Form,
+    FormField,
+    PaginatedResponse,
+    Registration,
+    Role,
+    Service,
+)
+
+__all__ = [
+    # Client
+    "BPAClient",
+    # Client constants
+    "MAX_RETRIES",
+    "BASE_DELAY",
+    "MAX_DELAY",
+    "DEFAULT_TIMEOUT",
+    "RETRYABLE_STATUS_CODES",
+    "NON_RETRYABLE_STATUS_CODES",
+    # Errors
+    "BPAClientError",
+    "BPAConnectionError",
+    "BPATimeoutError",
+    "BPAAuthenticationError",
+    "BPAPermissionError",
+    "BPANotFoundError",
+    "BPAValidationError",
+    "BPARateLimitError",
+    "BPAServerError",
+    "translate_error",
+    # Models
+    "BPABaseModel",
+    "Service",
+    "Registration",
+    "FormField",
+    "Determinant",
+    "Role",
+    "Cost",
+    "Document",
+    "Action",
+    "Form",
+    "PaginatedResponse",
+]