openapi-mcp-gateway 0.1.0__py3-none-any.whl

openapi_mcp_gateway/__init__.py

@@ -0,0 +1,15 @@
+from .gateway import Gateway
+from .settings import CORSConfig, GatewayConfig, LoggingConfig, ServerConfig, StoreConfig
+from .stores import MemoryTokenStore, TokenStore
+
+
+__all__ = [
+    'CORSConfig',
+    'Gateway',
+    'GatewayConfig',
+    'LoggingConfig',
+    'MemoryTokenStore',
+    'ServerConfig',
+    'StoreConfig',
+    'TokenStore',
+]

openapi_mcp_gateway/auth/__init__.py

@@ -0,0 +1,15 @@
+from .detector import DetectedOAuthFlow, detect_oauth_flows, detect_primary_oauth_flow
+from .provider import GatewayOAuthProvider
+from .resolver import AuthResolver, NullAuthResolver, OAuthAuthResolver, StaticAuthResolver
+
+
+__all__ = [
+    'AuthResolver',
+    'DetectedOAuthFlow',
+    'GatewayOAuthProvider',
+    'NullAuthResolver',
+    'OAuthAuthResolver',
+    'StaticAuthResolver',
+    'detect_oauth_flows',
+    'detect_primary_oauth_flow',
+]

openapi_mcp_gateway/auth/detector.py

@@ -0,0 +1,64 @@
+import typing
+
+import pydantic
+
+from ..openapi import OpenAPISpec
+
+
+class DetectedOAuthFlow(pydantic.BaseModel):
+    """Minimal OAuth2 flow metadata extracted from ``components.securitySchemes``."""
+
+    flow_type: typing.Literal['authorization_code', 'client_credentials']
+    authorization_url: str | None = None
+    token_url: str
+    scopes: dict[str, str] = pydantic.Field(default_factory=dict)
+
+
+def detect_oauth_flows(spec: OpenAPISpec) -> list[DetectedOAuthFlow]:
+    """Return every OAuth2 flow advertised under ``securitySchemes``."""
+    flows: list[DetectedOAuthFlow] = []
+
+    for _scheme_name, scheme in spec.security_schemes.items():
+        if scheme.get('type') != 'oauth2':
+            continue
+
+        oauth_flows = scheme.get('flows', {})
+
+        if 'authorizationCode' in oauth_flows:
+            flow_data = oauth_flows['authorizationCode']
+            flows.append(
+                DetectedOAuthFlow(
+                    flow_type='authorization_code',
+                    authorization_url=flow_data.get('authorizationUrl'),
+                    token_url=flow_data['tokenUrl'],
+                    scopes=flow_data.get('scopes', {}),
+                )
+            )
+
+        if 'clientCredentials' in oauth_flows:
+            flow_data = oauth_flows['clientCredentials']
+            flows.append(
+                DetectedOAuthFlow(
+                    flow_type='client_credentials',
+                    token_url=flow_data['tokenUrl'],
+                    scopes=flow_data.get('scopes', {}),
+                )
+            )
+
+    return flows
+
+
+def detect_primary_oauth_flow(spec: OpenAPISpec) -> DetectedOAuthFlow | None:
+    """Pick a single OAuth2 flow, favouring ``authorization_code``.
+
+    Returns ``None`` when the document defines no OAuth2 flows.
+    """
+    flows = detect_oauth_flows(spec)
+    if not flows:
+        return None
+
+    # Prefer authorization_code
+    for flow in flows:
+        if flow.flow_type == 'authorization_code':
+            return flow
+    return flows[0]

openapi_mcp_gateway/auth/provider.py

@@ -0,0 +1,412 @@
+import logging
+import secrets
+import time
+import typing
+import urllib.parse
+
+import httpx
+from mcp.server.auth.middleware.auth_context import get_access_token
+from mcp.server.auth.provider import (
+    AccessToken,
+    AuthorizationCode,
+    AuthorizationParams,
+    RefreshToken,
+    TokenError,
+    construct_redirect_uri,
+)
+from mcp.shared.auth import OAuthClientInformationFull, OAuthToken
+from starlette.exceptions import HTTPException
+
+from ..stores.base import TokenStore
+
+
+logger = logging.getLogger(__name__)
+
+MCP_ACCESS_TOKEN_TTL = 3600  # 1 hour
+MCP_REFRESH_TOKEN_TTL = 86400  # 24 hours
+MCP_SCOPES = ['api']
+
+
+class GatewayOAuthProvider:
+    """Implement MCP's OAuth server provider API against an upstream OAuth2 API.
+
+    Registers MCP clients, forwards browser authorization to the upstream IdP,
+    exchanges grants with ``upstream_token_url``, and keeps MCP ↔ upstream token
+    mappings inside ``store``.
+    """
+
+    def __init__(
+        self,
+        store: TokenStore,
+        upstream_auth_url: str,
+        upstream_token_url: str,
+        client_id: str,
+        client_secret: str,
+        callback_url: str,
+        scopes: list[str] | None = None,
+        prefix: str = 'gateway',
+    ) -> None:
+        """Bind token ``store``, upstream endpoints, IdP client credentials, and callback."""
+        self.store = store
+        self.upstream_auth_url = upstream_auth_url
+        self.upstream_token_url = upstream_token_url
+        self.client_id = client_id
+        self.client_secret = client_secret
+        self.callback_url = callback_url
+        self.scopes = scopes or []
+        self._prefix = prefix
+
+    # ── MCP SDK OAuthAuthorizationServerProvider interface ──
+
+    async def get_client(self, client_id: str) -> OAuthClientInformationFull | None:
+        """Load MCP OAuth client registration state by ``client_id``."""
+        data = await self.store.get('mcp_client', client_id)
+        if data:
+            return OAuthClientInformationFull(**data)
+        return None
+
+    async def register_client(self, client_info: OAuthClientInformationFull) -> None:
+        """Persist ``client_info`` for subsequent authorize/token exchanges."""
+        if not client_info.client_id:
+            raise ValueError('client_id is required')
+        await self.store.set(
+            'mcp_client',
+            client_info.client_id,
+            client_info.model_dump(exclude_none=True, mode='json'),
+        )
+        logger.info('Registered MCP client: client_id=%s prefix=%s', client_info.client_id, self._prefix)
+
+    async def authorize(self, client: OAuthClientInformationFull, params: AuthorizationParams) -> str:
+        """Return the upstream authorize URL with PKCE/state payload stored in ``store``."""
+        client_id = self._require_client_id(client)
+        state = params.state or secrets.token_hex(16)
+
+        state_data = {
+            'redirect_uri': str(params.redirect_uri),
+            'code_challenge': params.code_challenge,
+            'redirect_uri_provided_explicitly': params.redirect_uri_provided_explicitly,
+            'client_id': client_id,
+        }
+        await self.store.set('mcp_auth_state', state, state_data, ttl=900)
+
+        query_params = {
+            'client_id': self.client_id,
+            'redirect_uri': self.callback_url,
+            'state': state,
+            'response_type': 'code',
+        }
+        if self.scopes:
+            query_params['scope'] = ' '.join(self.scopes)
+
+        logger.info('Upstream OAuth authorize: scopes=%s', self.scopes)
+        return f'{self.upstream_auth_url}?{urllib.parse.urlencode(query_params)}'
+
+    async def load_authorization_code(
+        self, client: OAuthClientInformationFull, authorization_code: str
+    ) -> AuthorizationCode | None:
+        """Hydrate ``AuthorizationCode`` when it belongs to ``client``."""
+        client_id = self._require_client_id(client)
+        data = await self.store.get('mcp_auth_code', authorization_code)
+        if data and data['client_id'] == client_id:
+            return AuthorizationCode(**data)
+        return None
+
+    async def exchange_authorization_code(
+        self, client: OAuthClientInformationFull, authorization_code: AuthorizationCode
+    ) -> OAuthToken:
+        """Exchange an MCP authorization code for MCP access/refresh tokens."""
+        client_id = self._require_client_id(client)
+        data = await self.store.get('mcp_auth_code', authorization_code.code)
+
+        if not data or data['client_id'] != client_id:
+            logger.warning('OAuth code exchange rejected: reason=invalid_code client_id=%s', client_id)
+            raise TokenError(error='invalid_grant', error_description='Invalid authorization code')
+
+        api_access_token = await self.store.get_mapping(
+            'mcp_auth_code', authorization_code.code, 'api_access_token'
+        ) or await self.store.get_mapping('client', client_id, 'api_access_token')
+
+        if not api_access_token:
+            logger.warning('OAuth code exchange rejected: reason=no_upstream_token client_id=%s', client_id)
+            raise TokenError(error='invalid_grant', error_description='No upstream API token found')
+
+        api_refresh_token = await self.store.get_mapping('mcp_auth_code', authorization_code.code, 'api_refresh_token')
+
+        return await self._issue_mcp_token(
+            client_id=client_id,
+            scopes=authorization_code.scopes,
+            api_access_token=api_access_token,
+            api_refresh_token=api_refresh_token,
+        )
+
+    async def load_access_token(self, token: str) -> AccessToken | None:
+        """Return MCP access token payload when ``token`` is valid."""
+        data = await self.store.get('mcp_access_token', token)
+        if data:
+            return AccessToken(**data)
+        return None
+
+    async def load_refresh_token(self, client: OAuthClientInformationFull, refresh_token: str) -> RefreshToken | None:
+        """Return MCP refresh metadata scoped to ``client``."""
+        client_id = self._require_client_id(client)
+        data = await self.store.get('mcp_refresh_token', refresh_token)
+        if data and data['client_id'] == client_id:
+            return RefreshToken(**data)
+        return None
+
+    async def exchange_refresh_token(
+        self,
+        client: OAuthClientInformationFull,
+        refresh_token: RefreshToken,
+        scopes: list[str],
+    ) -> OAuthToken:
+        """Rotate MCP tokens while preserving upstream refresh semantics."""
+        client_id = self._require_client_id(client)
+        data = await self.store.get('mcp_refresh_token', refresh_token.token)
+
+        if not data or data['client_id'] != client_id:
+            logger.warning('OAuth refresh rejected: reason=invalid_refresh_token client_id=%s', client_id)
+            raise TokenError(error='invalid_grant', error_description='Invalid refresh token')
+
+        api_access_token = await self.store.get_mapping('mcp_refresh_token', refresh_token.token, 'api_access_token')
+        api_refresh_token = await self.store.get_mapping('mcp_refresh_token', refresh_token.token, 'api_refresh_token')
+
+        if not api_access_token:
+            logger.warning('OAuth refresh rejected: reason=mapping_lost client_id=%s', client_id)
+            raise TokenError(error='invalid_grant', error_description='Upstream token mapping lost')
+
+        # Check if upstream access token is still valid
+        if not await self.store.get('api_access_token', api_access_token):
+            if not api_refresh_token:
+                logger.warning('OAuth refresh rejected: reason=upstream_expired_no_refresh client_id=%s', client_id)
+                raise TokenError(
+                    error='invalid_grant',
+                    error_description='Upstream token expired and no refresh token available; re-authenticate',
+                )
+            api_access_token, new_refresh, expires_in = await self._request_upstream_token(
+                {
+                    'client_id': self.client_id,
+                    'client_secret': self.client_secret,
+                    'refresh_token': api_refresh_token,
+                    'grant_type': 'refresh_token',
+                }
+            )
+            api_refresh_token = new_refresh or api_refresh_token
+            await self._store_api_token(client_id, api_access_token, expires_in)
+
+        new_token = await self._issue_mcp_token(
+            client_id=client_id,
+            scopes=scopes or data.get('scopes', []),
+            api_access_token=api_access_token,
+            api_refresh_token=api_refresh_token,
+        )
+
+        # Revoke old tokens
+        old_access = await self.store.get_mapping('mcp_refresh_token', refresh_token.token, 'mcp_access_token')
+        if old_access:
+            await self.store.delete('mcp_access_token', old_access)
+        await self.store.delete('mcp_refresh_token', refresh_token.token)
+
+        return new_token
+
+    async def revoke_token(self, token: AccessToken | RefreshToken) -> None:
+        """Delete MCP tokens plus paired refresh/access mappings from ``store``."""
+        kind = 'access' if isinstance(token, AccessToken) else 'refresh'
+        if isinstance(token, AccessToken):
+            paired = await self.store.get_mapping('mcp_access_token', token.token, 'mcp_refresh_token')
+            if paired:
+                await self.store.delete('mcp_refresh_token', paired)
+            await self.store.delete('mcp_access_token', token.token)
+        elif isinstance(token, RefreshToken):
+            paired = await self.store.get_mapping('mcp_refresh_token', token.token, 'mcp_access_token')
+            if paired:
+                await self.store.delete('mcp_access_token', paired)
+            await self.store.delete('mcp_refresh_token', token.token)
+        logger.info('Revoked MCP %s token (prefix=%s)', kind, self._prefix)
+
+    # ── Gateway-specific methods ──
+
+    async def handle_upstream_callback(self, code: str, state: str) -> str:
+        """Finish the browser redirect: swap upstream ``code`` for MCP authorization artifacts.
+
+        Validates ``state``, exchanges tokens at ``upstream_token_url``, persists API
+        credentials, builds an MCP authorization code, and returns the client redirect URI.
+        """
+        state_data = await self.store.get('mcp_auth_state', state)
+        if not state_data:
+            logger.warning('OAuth callback rejected: reason=invalid_state state=%s', state)
+            raise HTTPException(400, 'Invalid state parameter')
+
+        redirect_uri = state_data['redirect_uri']
+        code_challenge = state_data['code_challenge']
+        redirect_uri_provided_explicitly = state_data['redirect_uri_provided_explicitly']
+        client_id = state_data['client_id']
+
+        # Exchange upstream code for tokens
+        api_access_token, api_refresh_token, expires_in = await self._request_upstream_token(
+            {
+                'client_id': self.client_id,
+                'client_secret': self.client_secret,
+                'code': code,
+                'redirect_uri': self.callback_url,
+                'grant_type': 'authorization_code',
+            }
+        )
+
+        # Create MCP auth code
+        mcp_auth_code = f'mcp_{secrets.token_hex(16)}'
+        await self.store.set(
+            'mcp_auth_code',
+            mcp_auth_code,
+            {
+                'code': mcp_auth_code,
+                'client_id': client_id,
+                'redirect_uri': redirect_uri,
+                'redirect_uri_provided_explicitly': redirect_uri_provided_explicitly,
+                'expires_at': time.time() + 300,
+                'scopes': MCP_SCOPES,
+                'code_challenge': code_challenge,
+            },
+            ttl=300,
+        )
+
+        # Store upstream tokens
+        await self._store_api_token(client_id, api_access_token, expires_in)
+
+        # Create mappings
+        await self.store.set_mapping('mcp_auth_code', mcp_auth_code, 'api_access_token', api_access_token, ttl=300)
+        if api_refresh_token:
+            await self.store.set_mapping(
+                'mcp_auth_code', mcp_auth_code, 'api_refresh_token', api_refresh_token, ttl=300
+            )
+        await self.store.set_mapping('client', client_id, 'api_access_token', api_access_token)
+
+        # Clean up state
+        await self.store.delete('mcp_auth_state', state)
+
+        logger.info(
+            'Upstream OAuth callback handled: client_id=%s expires_in=%s refresh=%s',
+            client_id,
+            expires_in,
+            bool(api_refresh_token),
+        )
+        return construct_redirect_uri(redirect_uri, code=mcp_auth_code, state=state)
+
+    async def get_api_access_token(self) -> str | None:
+        """Map the active MCP access token (request context) to the upstream bearer secret."""
+        mcp_access_token = get_access_token()
+        if not mcp_access_token:
+            return None
+        return await self.store.get_mapping('mcp_access_token', mcp_access_token.token, 'api_access_token')
+
+    # ── Private helpers ──
+
+    @staticmethod
+    def _require_client_id(client: OAuthClientInformationFull) -> str:
+        """Return ``client.client_id`` or raise ``ValueError``."""
+        if not client.client_id:
+            raise ValueError('client_id is required')
+        return client.client_id
+
+    async def _issue_mcp_token(
+        self,
+        client_id: str,
+        scopes: list[str],
+        api_access_token: str,
+        api_refresh_token: str | None,
+    ) -> OAuthToken:
+        """Mint MCP access/refresh tokens and map them to upstream API tokens."""
+        mcp_access = f'mcp_{secrets.token_hex(32)}'
+        mcp_refresh = f'mcp_refresh_{secrets.token_hex(32)}'
+        now = int(time.time())
+
+        await self.store.set(
+            'mcp_access_token',
+            mcp_access,
+            {
+                'token': mcp_access,
+                'client_id': client_id,
+                'scopes': scopes,
+                'expires_at': now + MCP_ACCESS_TOKEN_TTL,
+            },
+            ttl=MCP_ACCESS_TOKEN_TTL,
+        )
+
+        await self.store.set(
+            'mcp_refresh_token',
+            mcp_refresh,
+            {
+                'token': mcp_refresh,
+                'client_id': client_id,
+                'scopes': scopes,
+                'expires_at': now + MCP_REFRESH_TOKEN_TTL,
+            },
+            ttl=MCP_REFRESH_TOKEN_TTL,
+        )
+
+        # mcp_access → api_access (for tool calls)
+        await self.store.set_mapping(
+            'mcp_access_token', mcp_access, 'api_access_token', api_access_token, ttl=MCP_ACCESS_TOKEN_TTL
+        )
+        # mcp_refresh → api_access (for refresh chain)
+        await self.store.set_mapping(
+            'mcp_refresh_token', mcp_refresh, 'api_access_token', api_access_token, ttl=MCP_REFRESH_TOKEN_TTL
+        )
+        if api_refresh_token:
+            await self.store.set_mapping(
+                'mcp_refresh_token', mcp_refresh, 'api_refresh_token', api_refresh_token, ttl=MCP_REFRESH_TOKEN_TTL
+            )
+        # Pair access ↔ refresh for revoke lookup
+        await self.store.set_mapping(
+            'mcp_access_token', mcp_access, 'mcp_refresh_token', mcp_refresh, ttl=MCP_ACCESS_TOKEN_TTL
+        )
+        await self.store.set_mapping(
+            'mcp_refresh_token', mcp_refresh, 'mcp_access_token', mcp_access, ttl=MCP_REFRESH_TOKEN_TTL
+        )
+
+        return OAuthToken(
+            access_token=mcp_access,
+            refresh_token=mcp_refresh,
+            expires_in=MCP_ACCESS_TOKEN_TTL,
+        )
+
+    async def _store_api_token(self, client_id: str, token: str, expires_in: int) -> None:
+        """Persist upstream access token metadata under ``api_access_token`` with TTL."""
+        await self.store.set(
+            'api_access_token',
+            token,
+            {
+                'token': token,
+                'client_id': client_id,
+                'expires_at': int(time.time()) + expires_in,
+            },
+            ttl=expires_in,
+        )
+
+    async def _request_upstream_token(self, request_data: dict[str, typing.Any]) -> tuple[str, str | None, int]:
+        """POST ``request_data`` to upstream token URL; return ``(access, refresh | None, expires_in)``."""
+        async with httpx.AsyncClient() as client:
+            response = await client.post(
+                self.upstream_token_url,
+                data=request_data,
+                headers={'Accept': 'application/json'},
+            )
+
+            if response.status_code != 200:
+                logger.warning(
+                    'Upstream token exchange failed: status=%d url=%s',
+                    response.status_code,
+                    self.upstream_token_url,
+                )
+                raise HTTPException(400, f'Upstream token exchange failed: {response.text}')
+
+            data = response.json()
+            access_token = data.get('access_token')
+            if not access_token:
+                logger.warning('Upstream token exchange returned no access_token: url=%s', self.upstream_token_url)
+                raise HTTPException(400, 'Upstream returned no access_token')
+
+            logger.info(
+                'Upstream token response: granted_scope=%r expires_in=%s', data.get('scope'), data.get('expires_in')
+            )
+            return access_token, data.get('refresh_token'), data.get('expires_in', 3600)

openapi_mcp_gateway/auth/resolver.py

@@ -0,0 +1,51 @@
+import abc
+import typing
+
+from mcp.server.fastmcp import Context
+
+
+class AuthResolver(abc.ABC):
+    """Protocol for building the ``Authorization`` header for upstream HTTP calls."""
+
+    @abc.abstractmethod
+    async def resolve(self, ctx: Context) -> str | None:
+        """Return the header value to send upstream, or ``None`` if unauthenticated.
+
+        Implementations typically return a ``Bearer`` string or ``None``.
+        """
+
+
+class NullAuthResolver(AuthResolver):
+    """Resolver that always omits authentication (public upstream APIs)."""
+
+    async def resolve(self, ctx: Context) -> str | None:
+        """Always return ``None``."""
+        return None
+
+
+class StaticAuthResolver(AuthResolver):
+    """Fixed ``Authorization`` (or raw token) configured when the gateway starts."""
+
+    def __init__(self, header_value: str) -> None:
+        """Store the literal header value to attach on each request."""
+        self._header_value = header_value
+
+    async def resolve(self, ctx: Context) -> str | None:
+        """Return the configured header string."""
+        return self._header_value
+
+
+class OAuthAuthResolver(AuthResolver):
+    """Exchange MCP bearer tokens for upstream API bearer tokens via OAuth."""
+
+    def __init__(self, provider: typing.Any) -> None:
+        """Keep a reference to ``GatewayOAuthProvider`` (``Any`` avoids import cycles)."""
+        # provider is GatewayOAuthProvider — use Any to avoid circular import
+        self._provider = provider
+
+    async def resolve(self, ctx: Context) -> str | None:
+        """Lookup upstream token using the current MCP access token context."""
+        api_token = await self._provider.get_api_access_token()
+        if api_token:
+            return f'Bearer {api_token}'
+        return None