mcp-hangar 0.2.0__py3-none-any.whl

mcp_hangar/infrastructure/auth/jwt_authenticator.py

@@ -0,0 +1,360 @@
+"""JWT/OIDC authentication implementation.
+
+Provides authenticator and token validator for JWT-based authentication
+with OIDC support (JWKS validation, standard claims).
+"""
+
+from dataclasses import dataclass
+from typing import Any
+
+import structlog
+
+from ...domain.contracts.authentication import AuthRequest, IAuthenticator, ITokenValidator
+from ...domain.exceptions import ExpiredCredentialsError, InvalidCredentialsError
+from ...domain.value_objects import Principal, PrincipalId, PrincipalType
+
+logger = structlog.get_logger(__name__)
+
+
+@dataclass
+class OIDCConfig:
+    """OIDC provider configuration.
+
+    Attributes:
+        issuer: OIDC issuer URL (e.g., https://auth.company.com).
+        audience: Expected audience claim value.
+        jwks_uri: JWKS endpoint URL (auto-discovered if None).
+        client_id: Optional client ID for additional validation.
+        subject_claim: JWT claim for subject (default: sub).
+        groups_claim: JWT claim for groups (default: groups).
+        tenant_claim: JWT claim for tenant ID (default: tenant_id).
+        email_claim: JWT claim for email (default: email).
+    """
+
+    issuer: str
+    audience: str
+    jwks_uri: str | None = None
+    client_id: str | None = None
+
+    # Claim mappings
+    subject_claim: str = "sub"
+    groups_claim: str = "groups"
+    tenant_claim: str = "tenant_id"
+    email_claim: str = "email"
+
+
+class JWTAuthenticator(IAuthenticator):
+    """Authenticates requests using JWT tokens (Bearer auth).
+
+    Expects JWT in the Authorization header with 'Bearer' scheme.
+    Validates signature, expiration, issuer, and audience.
+    """
+
+    def __init__(self, config: OIDCConfig, token_validator: ITokenValidator):
+        """Initialize the JWT authenticator.
+
+        Args:
+            config: OIDC configuration with issuer, audience, and claim mappings.
+            token_validator: Validator for JWT signature and structure.
+        """
+        self._config = config
+        self._validator = token_validator
+
+    def supports(self, request: AuthRequest) -> bool:
+        """Check if request has Bearer token."""
+        auth_header = request.headers.get("Authorization", "")
+        return auth_header.startswith("Bearer ")
+
+    def authenticate(self, request: AuthRequest) -> Principal:
+        """Authenticate using JWT token.
+
+        Args:
+            request: The authentication request with headers.
+
+        Returns:
+            Authenticated Principal extracted from JWT claims.
+
+        Raises:
+            InvalidCredentialsError: If token is invalid or malformed.
+            ExpiredCredentialsError: If token has expired.
+        """
+        auth_header = request.headers.get("Authorization", "")
+
+        if not auth_header.startswith("Bearer "):
+            raise InvalidCredentialsError(
+                message="Missing Bearer token",
+                auth_method="jwt",
+            )
+
+        token = auth_header[7:]  # Remove "Bearer " prefix
+
+        if not token:
+            raise InvalidCredentialsError(
+                message="Empty Bearer token",
+                auth_method="jwt",
+            )
+
+        claims = self._validator.validate(token)
+
+        principal = self._claims_to_principal(claims)
+
+        logger.info(
+            "jwt_authenticated",
+            principal_id=principal.id.value,
+            principal_type=principal.type.value,
+            issuer=claims.get("iss"),
+            source_ip=request.source_ip,
+        )
+
+        return principal
+
+    def _claims_to_principal(self, claims: dict[str, Any]) -> Principal:
+        """Convert JWT claims to Principal.
+
+        Args:
+            claims: Validated JWT claims.
+
+        Returns:
+            Principal constructed from claims.
+
+        Raises:
+            InvalidCredentialsError: If required claims are missing.
+        """
+        subject = claims.get(self._config.subject_claim)
+        if not subject:
+            raise InvalidCredentialsError(
+                message=f"Missing {self._config.subject_claim} claim in JWT",
+                auth_method="jwt",
+            )
+
+        groups = claims.get(self._config.groups_claim, [])
+        if isinstance(groups, str):
+            groups = [groups]
+
+        tenant_id = claims.get(self._config.tenant_claim)
+        email = claims.get(self._config.email_claim)
+
+        return Principal(
+            id=PrincipalId(subject),
+            type=PrincipalType.USER,
+            tenant_id=tenant_id,
+            groups=frozenset(groups) if groups else frozenset(),
+            metadata={
+                "email": email,
+                "issuer": claims.get("iss"),
+                "issued_at": claims.get("iat"),
+                "expires_at": claims.get("exp"),
+            },
+        )
+
+
+class JWKSTokenValidator(ITokenValidator):
+    """Validates JWT tokens using JWKS (JSON Web Key Set).
+
+    Lazily initializes the JWKS client on first validation.
+    Supports RS256 and ES256 algorithms.
+
+    Note: Requires PyJWT library to be installed.
+    """
+
+    def __init__(self, config: OIDCConfig):
+        """Initialize the JWKS validator.
+
+        Args:
+            config: OIDC configuration with issuer and optional JWKS URI.
+        """
+        self._config = config
+        self._jwks_client = None
+        self._jwks_uri: str | None = None
+
+    def validate(self, token: str) -> dict:
+        """Validate JWT and return claims.
+
+        Args:
+            token: The JWT string to validate.
+
+        Returns:
+            Dictionary of validated claims.
+
+        Raises:
+            InvalidCredentialsError: If token is invalid or malformed.
+            ExpiredCredentialsError: If token has expired.
+        """
+        try:
+            import jwt
+        except ImportError:
+            raise InvalidCredentialsError(
+                message="JWT validation requires PyJWT library. Install with: pip install pyjwt[crypto]",
+                auth_method="jwt",
+            )
+
+        try:
+            # Lazy init JWKS client
+            if self._jwks_client is None:
+                self._init_jwks_client()
+
+            signing_key = self._jwks_client.get_signing_key_from_jwt(token)
+
+            claims = jwt.decode(
+                token,
+                signing_key.key,
+                algorithms=["RS256", "ES256"],
+                audience=self._config.audience,
+                issuer=self._config.issuer,
+                options={
+                    "verify_exp": True,
+                    "verify_iat": True,
+                    "verify_aud": True,
+                    "verify_iss": True,
+                    "verify_nbf": True,  # Verify 'not before' claim
+                },
+            )
+
+            return claims
+
+        except jwt.ExpiredSignatureError:
+            raise ExpiredCredentialsError(
+                message="JWT token has expired",
+                auth_method="jwt",
+            )
+        except jwt.InvalidAudienceError:
+            raise InvalidCredentialsError(
+                message="Invalid JWT audience",
+                auth_method="jwt",
+            )
+        except jwt.InvalidIssuerError:
+            raise InvalidCredentialsError(
+                message="Invalid JWT issuer",
+                auth_method="jwt",
+            )
+        except jwt.InvalidTokenError as e:
+            raise InvalidCredentialsError(
+                message=f"Invalid JWT token: {e}",
+                auth_method="jwt",
+            )
+
+    def _init_jwks_client(self) -> None:
+        """Initialize JWKS client, discovering URI if needed."""
+        try:
+            import httpx
+            import jwt
+        except ImportError as e:
+            raise InvalidCredentialsError(
+                message=f"JWT validation requires additional libraries: {e}",
+                auth_method="jwt",
+            )
+
+        # Security check: OIDC issuer should use HTTPS in production
+        if not self._config.issuer.startswith("https://"):
+            logger.warning(
+                "oidc_issuer_not_https",
+                issuer=self._config.issuer,
+                warning="OIDC issuer should use HTTPS to prevent MITM attacks",
+            )
+
+        jwks_uri = self._config.jwks_uri
+
+        if not jwks_uri:
+            # Discover from OIDC well-known endpoint
+            discovery_url = f"{self._config.issuer.rstrip('/')}/.well-known/openid-configuration"
+            try:
+                response = httpx.get(discovery_url, timeout=10)
+                response.raise_for_status()
+                oidc_config = response.json()
+                jwks_uri = oidc_config.get("jwks_uri")
+
+                if not jwks_uri:
+                    raise InvalidCredentialsError(
+                        message="OIDC discovery did not return jwks_uri",
+                        auth_method="jwt",
+                    )
+
+                # Security check: JWKS URI should also use HTTPS
+                if not jwks_uri.startswith("https://"):
+                    logger.warning(
+                        "jwks_uri_not_https",
+                        jwks_uri=jwks_uri,
+                        warning="JWKS URI should use HTTPS to prevent key tampering",
+                    )
+
+                logger.info(
+                    "oidc_discovery_complete",
+                    issuer=self._config.issuer,
+                    jwks_uri=jwks_uri,
+                )
+            except httpx.HTTPError as e:
+                raise InvalidCredentialsError(
+                    message=f"Failed to discover OIDC configuration: {e}",
+                    auth_method="jwt",
+                )
+
+        self._jwks_uri = jwks_uri
+        self._jwks_client = jwt.PyJWKClient(jwks_uri)
+
+
+class StaticSecretTokenValidator(ITokenValidator):
+    """Simple JWT validator using a static secret (HS256).
+
+    WARNING: Only for development/testing. Use JWKS in production.
+    """
+
+    def __init__(self, secret: str, issuer: str | None = None, audience: str | None = None):
+        """Initialize with a static secret.
+
+        Args:
+            secret: The HMAC secret for HS256 validation.
+            issuer: Optional expected issuer.
+            audience: Optional expected audience.
+        """
+        self._secret = secret
+        self._issuer = issuer
+        self._audience = audience
+
+    def validate(self, token: str) -> dict:
+        """Validate JWT using static secret.
+
+        Args:
+            token: The JWT string to validate.
+
+        Returns:
+            Dictionary of validated claims.
+
+        Raises:
+            InvalidCredentialsError: If token is invalid.
+            ExpiredCredentialsError: If token has expired.
+        """
+        try:
+            import jwt
+        except ImportError:
+            raise InvalidCredentialsError(
+                message="JWT validation requires PyJWT library",
+                auth_method="jwt",
+            )
+
+        options = {
+            "verify_exp": True,
+            "verify_iat": True,
+            "verify_aud": self._audience is not None,
+            "verify_iss": self._issuer is not None,
+        }
+
+        try:
+            claims = jwt.decode(
+                token,
+                self._secret,
+                algorithms=["HS256"],
+                audience=self._audience,
+                issuer=self._issuer,
+                options=options,
+            )
+            return claims
+        except jwt.ExpiredSignatureError:
+            raise ExpiredCredentialsError(
+                message="JWT token has expired",
+                auth_method="jwt",
+            )
+        except jwt.InvalidTokenError as e:
+            raise InvalidCredentialsError(
+                message=f"Invalid JWT token: {e}",
+                auth_method="jwt",
+            )

mcp_hangar/infrastructure/auth/middleware.py

@@ -0,0 +1,340 @@
+"""Authentication and Authorization middleware.
+
+Provides middleware components that can be integrated with HTTP frameworks
+(Starlette, FastAPI) or used directly in application code.
+"""
+
+from dataclasses import dataclass
+from typing import Callable
+
+import structlog
+
+from ...domain.contracts.authentication import AuthRequest, IAuthenticator
+from ...domain.contracts.authorization import AuthorizationRequest, IAuthorizer
+from ...domain.events import AuthenticationFailed, AuthenticationSucceeded, AuthorizationDenied, AuthorizationGranted
+from ...domain.exceptions import AccessDeniedError, AuthenticationError, MissingCredentialsError, RateLimitExceededError
+from ...domain.value_objects import Principal
+from .rate_limiter import AuthRateLimiter
+
+logger = structlog.get_logger(__name__)
+
+
+@dataclass
+class AuthContext:
+    """Authentication context attached to requests.
+
+    Contains the authenticated principal and metadata about how
+    authentication was performed.
+
+    Attributes:
+        principal: The authenticated principal.
+        auth_method: Name of the authenticator that handled the request.
+    """
+
+    principal: Principal
+    auth_method: str
+
+    def is_authenticated(self) -> bool:
+        """Check if request is authenticated (not anonymous)."""
+        return not self.principal.is_anonymous()
+
+
+class AuthenticationMiddleware:
+    """Middleware that authenticates incoming requests.
+
+    Tries each registered authenticator in order until one succeeds.
+    If no authenticator handles the request, returns anonymous principal
+    (if allowed) or raises MissingCredentialsError.
+
+    Usage:
+        authenticators = [
+            ApiKeyAuthenticator(key_store),
+            JWTAuthenticator(oidc_config, token_validator),
+        ]
+        auth_middleware = AuthenticationMiddleware(authenticators)
+
+        # In request handler:
+        auth_context = auth_middleware.authenticate(request)
+        principal = auth_context.principal
+    """
+
+    def __init__(
+        self,
+        authenticators: list[IAuthenticator],
+        allow_anonymous: bool = False,
+        event_publisher: Callable | None = None,
+        rate_limiter: AuthRateLimiter | None = None,
+    ):
+        """Initialize the authentication middleware.
+
+        Args:
+            authenticators: List of authenticators to try in order.
+            allow_anonymous: If True, return anonymous principal when no auth provided.
+            event_publisher: Optional function to publish domain events.
+            rate_limiter: Optional rate limiter for brute-force protection.
+        """
+        self._authenticators = authenticators
+        self._allow_anonymous = allow_anonymous
+        self._event_publisher = event_publisher
+        self._rate_limiter = rate_limiter
+
+    def authenticate(self, request: AuthRequest) -> AuthContext:
+        """Authenticate request and return context.
+
+        Args:
+            request: The normalized authentication request.
+
+        Returns:
+            AuthContext with authenticated principal.
+
+        Raises:
+            AuthenticationError: If authentication fails.
+            MissingCredentialsError: If no credentials and anonymous not allowed.
+            RateLimitExceededError: If rate limit exceeded for this IP.
+        """
+        # Check rate limit before attempting authentication
+        if self._rate_limiter:
+            rate_result = self._rate_limiter.check_rate_limit(request.source_ip)
+            if not rate_result.allowed:
+                logger.warning(
+                    "auth_rate_limit_blocked",
+                    source_ip=request.source_ip,
+                    reason=rate_result.reason,
+                    retry_after=rate_result.retry_after,
+                )
+                raise RateLimitExceededError(
+                    message=f"Too many authentication attempts. Try again in {int(rate_result.retry_after or 0)} seconds.",
+                    retry_after=rate_result.retry_after,
+                )
+
+        # Try each authenticator in order
+        for authenticator in self._authenticators:
+            if authenticator.supports(request):
+                try:
+                    principal = authenticator.authenticate(request)
+                    auth_method = authenticator.__class__.__name__
+
+                    self._publish_event(
+                        AuthenticationSucceeded(
+                            principal_id=principal.id.value,
+                            principal_type=principal.type.value,
+                            auth_method=auth_method,
+                            source_ip=request.source_ip,
+                            tenant_id=principal.tenant_id,
+                        )
+                    )
+
+                    logger.info(
+                        "authentication_succeeded",
+                        principal_id=principal.id.value,
+                        auth_method=auth_method,
+                        source_ip=request.source_ip,
+                    )
+
+                    # Clear rate limit on success
+                    if self._rate_limiter:
+                        self._rate_limiter.record_success(request.source_ip)
+
+                    return AuthContext(principal=principal, auth_method=auth_method)
+
+                except AuthenticationError as e:
+                    # Record failure for rate limiting
+                    if self._rate_limiter:
+                        self._rate_limiter.record_failure(request.source_ip)
+
+                    self._publish_event(
+                        AuthenticationFailed(
+                            auth_method=authenticator.__class__.__name__,
+                            source_ip=request.source_ip,
+                            reason=e.message,
+                        )
+                    )
+                    raise
+
+        # No authenticator matched
+        if self._allow_anonymous:
+            logger.debug(
+                "anonymous_access",
+                source_ip=request.source_ip,
+                path=request.path,
+            )
+            return AuthContext(principal=Principal.anonymous(), auth_method="anonymous")
+
+        # Authentication required but no credentials provided
+        expected_methods = [a.__class__.__name__ for a in self._authenticators]
+        raise MissingCredentialsError(
+            message="No valid credentials provided",
+            expected_methods=expected_methods,
+        )
+
+    def _publish_event(self, event) -> None:
+        """Publish domain event if publisher is configured."""
+        if self._event_publisher:
+            try:
+                self._event_publisher(event)
+            except Exception as e:
+                logger.warning("event_publish_failed", event_type=type(event).__name__, error=str(e))
+
+
+class AuthorizationMiddleware:
+    """Middleware that checks authorization for requests.
+
+    Integrates with an authorizer to check permissions and emits
+    domain events for audit trail.
+
+    Usage:
+        auth_middleware = AuthorizationMiddleware(authorizer)
+
+        # In request handler (after authentication):
+        auth_middleware.authorize(
+            principal=auth_context.principal,
+            action="invoke",
+            resource_type="tool",
+            resource_id="math:add",
+        )
+    """
+
+    def __init__(
+        self,
+        authorizer: IAuthorizer,
+        event_publisher: Callable | None = None,
+    ):
+        """Initialize the authorization middleware.
+
+        Args:
+            authorizer: The authorizer to use for access decisions.
+            event_publisher: Optional function to publish domain events.
+        """
+        self._authorizer = authorizer
+        self._event_publisher = event_publisher
+
+    def authorize(
+        self,
+        principal: Principal,
+        action: str,
+        resource_type: str,
+        resource_id: str,
+        context: dict | None = None,
+    ) -> None:
+        """Check authorization, raise AccessDeniedError if denied.
+
+        Args:
+            principal: The authenticated principal.
+            action: The action being performed.
+            resource_type: Type of resource being accessed.
+            resource_id: Specific resource identifier.
+            context: Optional additional context for policy evaluation.
+
+        Raises:
+            AccessDeniedError: If the principal is not authorized.
+        """
+        request = AuthorizationRequest(
+            principal=principal,
+            action=action,
+            resource_type=resource_type,
+            resource_id=resource_id,
+            context=context or {},
+        )
+
+        result = self._authorizer.authorize(request)
+
+        if result.allowed:
+            self._publish_event(
+                AuthorizationGranted(
+                    principal_id=principal.id.value,
+                    action=action,
+                    resource_type=resource_type,
+                    resource_id=resource_id,
+                    granted_by_role=result.matched_role or "unknown",
+                )
+            )
+            return
+
+        # Access denied
+        self._publish_event(
+            AuthorizationDenied(
+                principal_id=principal.id.value,
+                action=action,
+                resource_type=resource_type,
+                resource_id=resource_id,
+                reason=result.reason,
+            )
+        )
+
+        raise AccessDeniedError(
+            principal_id=principal.id.value,
+            action=action,
+            resource=f"{resource_type}:{resource_id}",
+            reason=result.reason,
+        )
+
+    def check(
+        self,
+        principal: Principal,
+        action: str,
+        resource_type: str,
+        resource_id: str,
+        context: dict | None = None,
+    ) -> bool:
+        """Check authorization without raising exception.
+
+        Args:
+            principal: The authenticated principal.
+            action: The action being performed.
+            resource_type: Type of resource being accessed.
+            resource_id: Specific resource identifier.
+            context: Optional additional context.
+
+        Returns:
+            True if authorized, False otherwise.
+        """
+        request = AuthorizationRequest(
+            principal=principal,
+            action=action,
+            resource_type=resource_type,
+            resource_id=resource_id,
+            context=context or {},
+        )
+
+        result = self._authorizer.authorize(request)
+        return result.allowed
+
+    def _publish_event(self, event) -> None:
+        """Publish domain event if publisher is configured."""
+        if self._event_publisher:
+            try:
+                self._event_publisher(event)
+            except Exception as e:
+                logger.warning("event_publish_failed", event_type=type(event).__name__, error=str(e))
+
+
+def create_auth_request_from_headers(
+    headers: dict[str, str],
+    source_ip: str = "unknown",
+    method: str = "",
+    path: str = "",
+) -> AuthRequest:
+    """Create AuthRequest from HTTP headers.
+
+    Convenience function for creating AuthRequest from HTTP request data.
+
+    Args:
+        headers: HTTP headers (case-insensitive dict preferred).
+        source_ip: Client IP address.
+        method: HTTP method.
+        path: Request path.
+
+    Returns:
+        AuthRequest ready for authentication.
+    """
+    # Normalize headers to lowercase for consistent lookup
+    normalized_headers = {k.lower(): v for k, v in headers.items()}
+    # Also keep original case for backwards compatibility
+    normalized_headers.update(headers)
+
+    return AuthRequest(
+        headers=normalized_headers,
+        source_ip=source_ip,
+        method=method,
+        path=path,
+    )