devtorch-core 3.0.1__py3-none-any.whl

devtorch_core/gateway/sso.py

@@ -0,0 +1,233 @@
+"""
+devtorch_core.gateway.sso
+==========================
+SSO / JWT token validation for the enterprise gateway.
+
+Supports:
+    "none"      — pass-through; returns an anonymous identity.
+    "okta"      — validates a signed JWT from Okta.
+    "azure-ad"  — validates a signed JWT from Azure Active Directory.
+    "google"    — validates a signed JWT from Google Workspace.
+
+PyJWT is an optional dependency.  If it is not installed the module falls back
+to a base64 payload decode (no signature verification) and logs a clear
+security warning.  This fallback is only intended for integration testing in
+environments where PyJWT cannot be installed.
+
+SECURITY NOTE: The "none" provider is safe for development only.  In
+production, always configure a real SSO provider with JWKS validation.
+
+Design decisions:
+- Returns None for any invalid/expired/malformed token so callers always get
+  a typed result and never see an exception.
+- extract_identity() is pure (no network I/O) and is always safe to call
+  on the dict returned by validate_token().
+"""
+from __future__ import annotations
+
+import base64
+import json
+import logging
+from typing import Optional
+from urllib.parse import urlparse
+
+logger = logging.getLogger("devtorch.gateway.sso")
+
+# Supported providers (besides "none")
+_JWT_PROVIDERS = {"okta", "azure-ad", "google"}
+
+
+class SSOValidator:
+    """
+    Validate SSO/JWT tokens and extract developer identity.
+
+    Parameters
+    ----------
+    provider:
+        One of "none", "okta", "azure-ad", "google".
+    jwks_url:
+        URL to the JWKS endpoint for the provider.
+        Required when provider != "none" and signature validation is needed.
+    audience:
+        Expected JWT audience claim ("aud").
+    token_issuer:
+        Optional expected JWT issuer ("iss"). Enforced only when provided.
+    """
+
+    def __init__(
+        self,
+        provider: str = "none",
+        jwks_url: str = "",
+        audience: str = "",
+        token_issuer: str = "",
+    ) -> None:
+        self._provider = provider.lower()
+        self._jwks_url = jwks_url
+        self._audience = audience
+        self._token_issuer = token_issuer
+
+        if self._provider not in {"none"} | _JWT_PROVIDERS:
+            logger.warning(
+                "SSOValidator: unknown provider '%s'; treating as 'none'",
+                provider,
+            )
+            self._provider = "none"
+
+    def __repr__(self) -> str:
+        return (
+            f"{self.__class__.__name__}("
+            f"provider={self._provider!r}, "
+            f"jwks_url={self.jwks_url!r}, "
+            f"audience={self._audience!r}, "
+            f"token_issuer={self._token_issuer!r})"
+        )
+
+    @property
+    def jwks_url(self) -> str:
+        """Return the JWKS URL with any query-string / path secret-ish tail masked."""
+        return self._mask_url(self._jwks_url)
+
+    @staticmethod
+    def _mask_url(url: str) -> str:
+        if not url:
+            return ""
+        parsed = urlparse(url)
+        if parsed.username or parsed.password:
+            # Mask credentials in the netloc
+            host = parsed.hostname or ""
+            port = parsed.port
+            port_part = f":{port}" if port else ""
+            netloc = f"{parsed.username or ''}:***@{host}{port_part}" if parsed.password else f"***@{host}{port_part}"
+            return parsed._replace(netloc=netloc).geturl()
+        # Mask last path/query component if it looks like a secret
+        if "?" in url:
+            base, _ = url.split("?", 1)
+            return f"{base}?***"
+        return url
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def validate_token(self, token: str) -> Optional[dict]:
+        """
+        Validate *token* and return the decoded JWT claims dict.
+
+        Returns:
+            dict  — decoded claims on success
+            None  — invalid / expired / malformed token
+        """
+        if self._provider == "none":
+            # Development / no-auth mode — always succeeds.
+            return {
+                "sub": "anonymous",
+                "email": "anonymous@local",
+                "name": "Anonymous",
+                "provider": "none",
+            }
+
+        if not token:
+            return None
+
+        # Real SSO providers — attempt JWT validation.
+        try:
+            return self._validate_jwt(token)
+        except Exception as exc:
+            logger.debug("SSOValidator: token validation error — %s", exc)
+            return None
+
+    def extract_identity(self, claims: dict) -> dict:
+        """
+        Extract a normalised identity dict from raw JWT claims.
+
+        Returns:
+            {
+                "user_id":      str,   # JWT 'sub' claim (or 'upn' for Azure AD)
+                "email":        str,   # JWT 'email' claim (or 'preferred_username' for Azure AD)
+                "display_name": str,   # JWT 'name' claim
+            }
+        """
+        user_id = str(claims.get("sub", ""))
+        email = str(claims.get("email", ""))
+        display_name = str(claims.get("name", ""))
+
+        if self._provider == "azure-ad":
+            if not user_id:
+                user_id = str(claims.get("upn", ""))
+            if not email:
+                email = str(claims.get("preferred_username", ""))
+
+        if not user_id:
+            user_id = "unknown"
+        if not email:
+            email = ""
+        if not display_name:
+            display_name = email or user_id or "unknown"
+
+        return {
+            "user_id": user_id,
+            "email": email,
+            "display_name": display_name,
+        }
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _validate_jwt(self, token: str) -> Optional[dict]:
+        """
+        Attempt JWT validation using PyJWT.
+
+        Real SSO providers *always* require a configured ``jwks_url`` and a
+        valid signature. If PyJWT is missing or the JWKS URL is absent, the
+        token is rejected rather than accepted via an insecure fallback.
+        """
+        try:
+            import jwt  # type: ignore[import]
+        except ImportError:
+            logger.warning(
+                "SSOValidator: PyJWT not installed; cannot validate JWT for "
+                "provider '%s'. Install PyJWT: pip install PyJWT",
+                self._provider,
+            )
+            return None
+
+        return self._validate_with_pyjwt(jwt, token)
+
+    def _validate_with_pyjwt(self, jwt_module: object, token: str) -> Optional[dict]:
+        """
+        Decode and verify a JWT using PyJWT.
+
+        A ``jwks_url`` is mandatory for real providers. If it is missing, the
+        token is rejected instead of being decoded without signature
+        verification.
+        """
+        try:
+            import jwt  # type: ignore[import]
+
+            if not self._jwks_url:
+                logger.warning(
+                    "SSOValidator: no jwks_url configured for provider '%s'; "
+                    "rejecting JWT.",
+                    self._provider,
+                )
+                return None
+
+            jwks_client = jwt.PyJWKClient(self._jwks_url)
+            signing_key = jwks_client.get_signing_key_from_jwt(token)
+            decode_kwargs: dict = {
+                "algorithms": ["RS256"],
+                "options": {"verify_exp": True},
+            }
+            if self._audience:
+                decode_kwargs["audience"] = self._audience
+            if self._token_issuer:
+                decode_kwargs["issuer"] = self._token_issuer
+            return jwt.decode(
+                token,
+                signing_key.key,
+                **decode_kwargs,
+            )  # type: ignore[return-value]
+        except Exception as exc:
+            logger.debug("PyJWT decode failed: %s", exc)
+            return None