fix: make Clerk JWKS fetching async to prevent event loop blocking

Author: alimkhann

commitly-backend/app/core/auth.py

@@ -55,7 +55,22 @@ def __init__(self, jwks_url: str, ttl_seconds: int) -> None:
         self._expires_at: float = 0.0
         self._lock = RLock()
 
+    async def _fetch_async(self) -> Dict[str, Any]:
+        """Fetch JWKS using async HTTP client."""
+        try:
+            async with httpx.AsyncClient(timeout=5.0) as client:
+                response = await client.get(str(self.jwks_url))
+                response.raise_for_status()
+                payload = response.json()
+        except httpx.HTTPError as exc:  # pragma: no cover - network failure
+            raise InvalidClerkToken("Failed to download Clerk JWKS") from exc
+
+        if not isinstance(payload, dict) or "keys" not in payload:
+            raise InvalidClerkToken("JWKS payload is missing keys")
+        return payload
+
     def _fetch(self) -> Dict[str, Any]:
+        """Sync fetch for backwards compatibility."""
         try:
             with httpx.Client(timeout=5.0) as client:
                 response = client.get(str(self.jwks_url))
@@ -68,6 +83,21 @@ def _fetch(self) -> Dict[str, Any]:
             raise InvalidClerkToken("JWKS payload is missing keys")
         return payload
 
+    async def _current_jwks_async(self) -> Dict[str, Any]:
+        """Async version that fetches JWKS if needed."""
+        with self._lock:
+            now = time.monotonic()
+            if self._jwks and now < self._expires_at:
+                return self._jwks
+        
+        # Fetch outside the lock to avoid blocking
+        fresh_jwks = await self._fetch_async()
+        
+        with self._lock:
+            self._jwks = fresh_jwks
+            self._expires_at = time.monotonic() + max(self.ttl_seconds, 60)
+            return self._jwks
+
     def _current_jwks(self) -> Dict[str, Any]:
         with self._lock:
             now = time.monotonic()
@@ -77,6 +107,14 @@ def _current_jwks(self) -> Dict[str, Any]:
             self._expires_at = now + max(self.ttl_seconds, 60)
             return self._jwks
 
+    async def get_key_async(self, kid: str) -> Dict[str, Any]:
+        """Async version of get_key."""
+        jwks = await self._current_jwks_async()
+        for key in jwks.get("keys", []):
+            if key.get("kid") == kid:
+                return cast(Dict[str, Any], key)
+        raise InvalidClerkToken("No matching JWK for supplied token")
+
     def get_key(self, kid: str) -> Dict[str, Any]:
         jwks = self._current_jwks()
         for key in jwks.get("keys", []):
@@ -180,6 +218,71 @@ def verify_clerk_token(token: str) -> ClerkClaims:
     return cast(ClerkClaims, claims)
 
 
+async def verify_clerk_token_async(token: str) -> ClerkClaims:
+    """Async version of verify_clerk_token that doesn't block the event loop."""
+    try:
+        header = jwt.get_unverified_header(token)
+    except JWTError as exc:
+        raise InvalidClerkToken("Malformed token header") from exc
+
+    kid = header.get("kid")
+    if not isinstance(kid, str):
+        raise InvalidClerkToken("Missing key identifier")
+
+    # Use async version to avoid blocking
+    jwk_data = await jwks_cache.get_key_async(kid)
+    public_key = jwk.construct(jwk_data)
+
+    try:
+        message, encoded_signature = token.rsplit(".", 1)
+    except ValueError as exc:
+        raise InvalidClerkToken("Token structure is invalid") from exc
+
+    decoded_signature = base64url_decode(encoded_signature.encode("utf-8"))
+    if not public_key.verify(message.encode("utf-8"), decoded_signature):
+        raise InvalidClerkToken("Signature verification failed")
+
+    claims = jwt.get_unverified_claims(token)
+    now = int(time.time())
+
+    exp = claims.get("exp")
+    if exp is not None and int(exp) <= now:
+        raise InvalidClerkToken("Token has expired")
+
+    nbf = claims.get("nbf")
+    if nbf is not None and now < int(nbf):
+        raise InvalidClerkToken("Token is not yet valid")
+
+    issuer = claims.get("iss")
+    if issuer != settings.clerk_issuer:
+        raise InvalidClerkToken("Invalid issuer")
+
+    audience_values = _select_audience(claims.get("aud"))
+    allowed_audiences = Settings._coerce_list(settings.clerk_audience) or [
+        settings.clerk_audience
+    ]
+    if audience_values:
+        if not any(audience in audience_values for audience in allowed_audiences):
+            raise InvalidClerkToken("Invalid audience")
+
+    if settings.clerk_authorized_parties:
+        azp = claims.get("azp")
+        if isinstance(azp, str):
+            normalized_azp = _normalize_party(azp)
+            allowed = {
+                _normalize_party(party) for party in settings.clerk_authorized_parties
+            }
+            if "*" not in allowed and normalized_azp not in allowed:
+                raise InvalidClerkToken("Token not issued for this application")
+        else:
+            raise InvalidClerkToken("Token missing authorized party")
+
+    if "sub" not in claims:
+        raise InvalidClerkToken("Token is missing subject claim")
+
+    return cast(ClerkClaims, claims)
+
+
 def _unauthorized(detail: str) -> HTTPException:
     return HTTPException(
         status_code=status.HTTP_401_UNAUTHORIZED,
@@ -254,7 +357,8 @@ async def dispatch(
 
         if token:
             try:
-                request.state.clerk_claims = verify_clerk_token(token)
+                # Use async version to avoid blocking the event loop
+                request.state.clerk_claims = await verify_clerk_token_async(token)
             except InvalidClerkToken as exc:
                 request.state.clerk_auth_error = exc