feat: add oauth api

app/api/server.py

@@ -105,6 +105,8 @@ async def lifespan(app: FastAPI):
     await close_redis(redis)
     await _vector_store_service.close_all()
     await pool_manager.close_all()
+    from app.api.v1.google_oauth import close_oauth_service
+    await close_oauth_service()
     from app.services.supabase import get_supabase_client
     client = get_supabase_client()
     if client:

app/api/v1/google_oauth.py

@@ -0,0 +1,193 @@
+from __future__ import annotations
+
+import time
+from typing import Optional
+
+from fastapi import APIRouter, Depends, HTTPException, status
+
+from app.core.logger import get_logger
+from app.models.schemas import (
+    GoogleOAuthAuthUrlRequest,
+    GoogleOAuthAuthUrlResponse,
+    GoogleOAuthCallbackRequest,
+    GoogleOAuthRefreshRequest,
+    GoogleOAuthTokenResponse,
+    GoogleOAuthVerifyRequest,
+    GoogleOAuthVerifyResponse,
+)
+from app.services.google_oauth_service import GoogleOAuthError, GoogleOAuthService
+from app.services.jwt_service import JWTService
+from app.config import get_settings
+
+router = APIRouter(prefix="/google/oauth", tags=["Google OAuth"])
+_logger = get_logger(__name__)
+_settings = get_settings()
+_jwt_service = JWTService()
+
+
+_oauth_service = GoogleOAuthService()
+
+
+def get_oauth_service() -> GoogleOAuthService:
+    return _oauth_service
+
+
+async def close_oauth_service() -> None:
+    await _oauth_service.close()
+
+
+def _generate_state() -> str:
+    result = _jwt_service.generate(
+        subject="google-oauth-state",
+        secret=_settings.jwt_secret_key,
+        expiry_minutes=_settings.google_oauth_state_ttl_minutes,
+    )
+    return result["token"]
+
+
+def _verify_state(state: str) -> bool:
+    return _jwt_service.validate(
+        state, secret=_settings.jwt_secret_key
+    )["valid"]
+
+
+def _http_error(exc: GoogleOAuthError) -> HTTPException:
+    return HTTPException(status_code=exc.status_code, detail=exc.message)
+
+
+@router.post("/auth-url", response_model=GoogleOAuthAuthUrlResponse,
+             summary="Generate a Google OAuth authorization URL (Step 1)")
+async def create_auth_url(
+    body: GoogleOAuthAuthUrlRequest,
+    service: GoogleOAuthService = Depends(get_oauth_service),
+):
+    start = time.perf_counter()
+    state = _generate_state()
+    auth_url = service.build_auth_url(
+        client_id=body.client_id,
+        redirect_uri=body.redirect_uri,
+        state=state,
+        scope=body.scope,
+        prompt=body.prompt,
+        access_type=body.access_type,
+        login_hint=body.login_hint,
+        include_granted_scopes=body.include_granted_scopes,
+    )
+    _logger.info(
+        "Generated Google OAuth auth URL for client '%s...' (%.2fms)",
+        body.client_id[:8],
+        (time.perf_counter() - start) * 1000,
+    )
+    return GoogleOAuthAuthUrlResponse(success=True, auth_url=auth_url, state=state)
+
+
+@router.post("/callback", response_model=GoogleOAuthTokenResponse,
+             summary="Exchange the authorization code for tokens (Step 2)")
+async def oauth_callback(
+    body: GoogleOAuthCallbackRequest,
+    service: GoogleOAuthService = Depends(get_oauth_service),
+):
+    start = time.perf_counter()
+
+    if not _verify_state(body.state):
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Invalid or expired state token. Possible CSRF attack.",
+        )
+
+    try:
+        tokens = await service.exchange_code(
+            client_id=body.client_id,
+            client_secret=body.client_secret,
+            code=body.code,
+            redirect_uri=body.redirect_uri,
+        )
+    except GoogleOAuthError as exc:
+        raise _http_error(exc) from exc
+
+    id_token_raw: Optional[str] = tokens.get("id_token")
+    user = None
+    if id_token_raw:
+        try:
+            user = await service.verify_id_token(id_token_raw, body.client_id)
+        except GoogleOAuthError as exc:
+            raise _http_error(exc) from exc
+
+    _logger.info(
+        "Google OAuth callback completed for client '%s...' (%.2fms)",
+        body.client_id[:8],
+        (time.perf_counter() - start) * 1000,
+    )
+    return GoogleOAuthTokenResponse(
+        success=True,
+        access_token=tokens["access_token"],
+        expires_in=int(tokens.get("expires_in", 0)),
+        refresh_token=tokens.get("refresh_token"),
+        id_token=id_token_raw,
+        token_type=tokens.get("token_type", "Bearer"),
+        scope=tokens.get("scope"),
+        user=user,
+    )
+
+
+@router.post("/refresh", response_model=GoogleOAuthTokenResponse,
+             summary="Refresh an expired access token (Step 3)")
+async def refresh_token(
+    body: GoogleOAuthRefreshRequest,
+    service: GoogleOAuthService = Depends(get_oauth_service),
+):
+    start = time.perf_counter()
+
+    try:
+        tokens = await service.refresh_access_token(
+            client_id=body.client_id,
+            client_secret=body.client_secret,
+            refresh_token=body.refresh_token,
+        )
+    except GoogleOAuthError as exc:
+        raise _http_error(exc) from exc
+
+    id_token_raw: Optional[str] = tokens.get("id_token")
+    user = None
+    if id_token_raw:
+        try:
+            user = await service.verify_id_token(id_token_raw, body.client_id)
+        except GoogleOAuthError as exc:
+            raise _http_error(exc) from exc
+
+    _logger.info(
+        "Google OAuth token refresh completed for client '%s...' (%.2fms)",
+        body.client_id[:8],
+        (time.perf_counter() - start) * 1000,
+    )
+    return GoogleOAuthTokenResponse(
+        success=True,
+        access_token=tokens["access_token"],
+        expires_in=int(tokens.get("expires_in", 0)),
+        refresh_token=body.refresh_token,
+        id_token=id_token_raw,
+        token_type=tokens.get("token_type", "Bearer"),
+        scope=tokens.get("scope"),
+        user=user,
+    )
+
+
+@router.post("/verify", response_model=GoogleOAuthVerifyResponse,
+             summary="Verify a Google ID token and return the user profile")
+async def verify_id_token(
+    body: GoogleOAuthVerifyRequest,
+    service: GoogleOAuthService = Depends(get_oauth_service),
+):
+    start = time.perf_counter()
+
+    try:
+        user = await service.verify_id_token(body.id_token, body.client_id)
+    except GoogleOAuthError as exc:
+        raise _http_error(exc) from exc
+
+    _logger.info(
+        "Google OAuth ID token verified for client '%s...' (%.2fms)",
+        body.client_id[:8],
+        (time.perf_counter() - start) * 1000,
+    )
+    return GoogleOAuthVerifyResponse(success=True, valid=True, user=user)

app/api/v1/router.py

@@ -12,6 +12,7 @@ from app.api.v1 import (
     database,
     embeddings,
     google_maps,
+    google_oauth,
     json_extract,
     keys_extract,
     qr_decoder,
@@ -53,6 +54,7 @@ api_v1_router.include_router(vector_stores.router, tags=["Vector Stores"])
 api_v1_router.include_router(webhook_socket.router, tags=["Webhook / Socket"])
 api_v1_router.include_router(csv_analysis.router, tags=["CSV Analysis"])
 api_v1_router.include_router(google_maps.router, tags=["Google Maps"])
+api_v1_router.include_router(google_oauth.router, tags=["Google OAuth"])
 api_v1_router.include_router(json_extract.router, tags=["JSON Extractor"])
 api_v1_router.include_router(keys_extract.router, prefix="/json", tags=["Keys Extractor"])
 api_v1_router.include_router(qr_decoder.router, tags=["QR Decoder"])

app/config.py

@@ -102,6 +102,17 @@ class Settings(BaseSettings):
     google_maps_timeout: int = 15
     google_maps_max_retries: int = 2
 
+    # Google OAuth 2.0 (OpenID Connect) Sign-In settings
+    google_oauth_auth_url: str = "https://accounts.google.com/o/oauth2/v2/auth"
+    google_oauth_token_url: str = "https://oauth2.googleapis.com/token"
+    google_oauth_userinfo_url: str = "https://openidconnect.googleapis.com/v1/userinfo"
+    google_oauth_jwks_url: str = "https://www.googleapis.com/oauth2/v3/certs"
+    google_oauth_default_scope: str = "openid email profile"
+    google_oauth_timeout: float = 15.0
+    google_oauth_max_retries: int = 2
+    google_oauth_state_ttl_minutes: int = 10
+    google_oauth_jwks_ttl_seconds: int = 3600
+
     # Scheduler settings
     max_http_timeout: float = 300.0
     default_scheduler_timezone: str = "UTC"

app/models/schemas.py

@@ -883,3 +883,73 @@ class GoogleQueryAutocompleteResponse(BaseModel):
     predictions: List[GoogleAutocompletePrediction] = []
     count: int = 0
     error: Optional[str] = None
+
+
+# ---------------------------------------------------------------------------
+# Google OAuth 2.0 / OpenID Connect Sign-In
+# ---------------------------------------------------------------------------
+
+class GoogleOAuthUserInfo(BaseModel):
+    sub: str = Field(..., description="Google user ID (subject)")
+    email: str = Field(default="", description="User email address")
+    email_verified: bool = Field(default=False, description="Whether the email has been verified by Google")
+    name: Optional[str] = Field(None, description="Full display name")
+    given_name: Optional[str] = Field(None, description="Given name")
+    family_name: Optional[str] = Field(None, description="Family name")
+    picture: Optional[str] = Field(None, description="Profile picture URL")
+    locale: Optional[str] = Field(None, description="Locale (e.g. 'en', 'en-US')")
+
+
+class GoogleOAuthAuthUrlRequest(BaseModel):
+    client_id: str = Field(..., min_length=1, max_length=500, description="Google OAuth Client ID")
+    redirect_uri: str = Field(..., min_length=1, max_length=1000, description="Registered callback URL")
+    scope: str = Field(default="openid email profile", min_length=1, max_length=2000, description="Space-separated OAuth scopes")
+    prompt: Optional[str] = Field(None, pattern="^(none|consent|select_account)$", description="Google prompt parameter")
+    access_type: Optional[str] = Field(None, pattern="^(online|offline)$", description="Whether to return a refresh token (offline)")
+    login_hint: Optional[str] = Field(None, max_length=500, description="Prefilled user email to sign in as")
+    include_granted_scopes: bool = Field(default=False, description="Append previously granted scopes")
+
+
+class GoogleOAuthAuthUrlResponse(BaseModel):
+    success: bool
+    auth_url: str
+    state: str
+    error: Optional[str] = None
+
+
+class GoogleOAuthCallbackRequest(BaseModel):
+    client_id: str = Field(..., min_length=1, max_length=500, description="Google OAuth Client ID")
+    client_secret: str = Field(..., min_length=1, max_length=500, description="Google OAuth Client Secret")
+    code: str = Field(..., min_length=1, description="The authorization code returned by Google")
+    redirect_uri: str = Field(..., min_length=1, max_length=1000, description="Must match the URI used to build the auth URL")
+    state: str = Field(..., min_length=1, description="The CSRF state token returned from the auth URL step")
+
+
+class GoogleOAuthRefreshRequest(BaseModel):
+    client_id: str = Field(..., min_length=1, max_length=500, description="Google OAuth Client ID")
+    client_secret: str = Field(..., min_length=1, max_length=500, description="Google OAuth Client Secret")
+    refresh_token: str = Field(..., min_length=1, description="The refresh token obtained during the callback step")
+
+
+class GoogleOAuthVerifyRequest(BaseModel):
+    client_id: str = Field(..., min_length=1, max_length=500, description="Google OAuth Client ID (the audience of the ID token)")
+    id_token: str = Field(..., min_length=1, description="The Google ID token to verify")
+
+
+class GoogleOAuthTokenResponse(BaseModel):
+    success: bool
+    access_token: str
+    expires_in: int
+    refresh_token: Optional[str] = None
+    id_token: Optional[str] = None
+    token_type: str = "Bearer"
+    scope: Optional[str] = None
+    user: Optional[GoogleOAuthUserInfo] = None
+    error: Optional[str] = None
+
+
+class GoogleOAuthVerifyResponse(BaseModel):
+    success: bool
+    valid: bool
+    user: Optional[GoogleOAuthUserInfo] = None
+    error: Optional[str] = None

app/services/google_oauth_service.py

@@ -0,0 +1,400 @@
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Any, Dict, Optional
+from urllib.parse import urlencode
+
+import httpx
+import jwt
+
+from app.config import get_settings
+from app.core.logger import get_logger
+from app.models.schemas import GoogleOAuthUserInfo
+
+_logger = get_logger(__name__)
+_settings = get_settings()
+
+# Retryable transient HTTP status codes when talking to Google.
+_RETRYABLE_STATUS = frozenset({429, 500, 502, 503, 504})
+
+
+class GoogleOAuthError(Exception):
+    """Raised for upstream Google OAuth failures that map to a client-facing error."""
+
+    def __init__(self, message: str, status_code: int = 400) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+
+
+class GoogleJWKSCache:
+    """Asynchronously fetches and caches Google's public JWKS keys.
+
+    Keys are cached for a short TTL to avoid hammering Google's cert endpoint,
+    and re-fetched on demand if the requested ``kid`` is missing (key rotation).
+    """
+
+    def __init__(self) -> None:
+        self._keys: Dict[str, Dict[str, Any]] = {}
+        self._last_fetched: float = 0.0
+        self._lock = asyncio.Lock()
+
+    def _is_expired(self) -> bool:
+        return (
+            not self._keys
+            or time.time() - self._last_fetched >= _settings.google_oauth_jwks_ttl_seconds
+        )
+
+    async def get_public_key(self, client: httpx.AsyncClient, kid: str) -> Any:
+        """Return the RSA public key for the given key id (``kid``)."""
+        if self._is_expired():
+            await self._refresh(client)
+
+        jwk = self._keys.get(kid)
+        if jwk is None:
+            # Key may have rotated; force a refresh before giving up.
+            await self._refresh(client)
+            jwk = self._keys.get(kid)
+
+        if jwk is None:
+            raise GoogleOAuthError(
+                f"Google signing key not found for kid '{kid}'", status_code=401
+            )
+
+        return jwt.algorithms.RSAAlgorithm.from_jwk(jwk)
+
+    async def _refresh(self, client: httpx.AsyncClient) -> None:
+        async with self._lock:
+            if not self._is_expired():
+                return
+            try:
+                response = await client.get(
+                    _settings.google_oauth_jwks_url, timeout=10.0
+                )
+                response.raise_for_status()
+                data = response.json()
+                self._keys = {
+                    key["kid"]: key
+                    for key in data.get("keys", [])
+                    if isinstance(key, dict) and "kid" in key
+                }
+                self._last_fetched = time.time()
+                _logger.info("Google JWKS refreshed (%d keys)", len(self._keys))
+            except httpx.HTTPError as exc:
+                _logger.error("Failed to refresh Google JWKS: %s", exc)
+                raise GoogleOAuthError(
+                    "Unable to fetch Google signing keys", status_code=502
+                ) from exc
+
+
+class GoogleOAuthService:
+    """Abstraction over the Google OAuth 2.0 / OpenID Connect flow."""
+
+    def __init__(self) -> None:
+        self._client: Optional[httpx.AsyncClient] = None
+        self._client_lock = asyncio.Lock()
+        self._jwks = GoogleJWKSCache()
+
+    # ------------------------------------------------------------------
+    # HTTP client management
+    # ------------------------------------------------------------------
+
+    async def _get_client(self) -> httpx.AsyncClient:
+        if self._client is None or self._client.is_closed:
+            async with self._client_lock:
+                if self._client is None or self._client.is_closed:
+                    self._client = httpx.AsyncClient(
+                        timeout=httpx.Timeout(_settings.google_oauth_timeout),
+                        limits=httpx.Limits(
+                            max_connections=100,
+                            max_keepalive_connections=20,
+                            keepalive_expiry=30,
+                        ),
+                    )
+        return self._client
+
+    async def close(self) -> None:
+        async with self._client_lock:
+            if self._client is not None and not self._client.is_closed:
+                await self._client.aclose()
+            self._client = None
+
+    # ------------------------------------------------------------------
+    # Authorization URL (Step 1)
+    # ------------------------------------------------------------------
+
+    def build_auth_url(
+        self,
+        *,
+        client_id: str,
+        redirect_uri: str,
+        state: str,
+        scope: str,
+        prompt: Optional[str] = None,
+        access_type: Optional[str] = None,
+        login_hint: Optional[str] = None,
+        include_granted_scopes: bool = False,
+    ) -> str:
+        params: Dict[str, Any] = {
+            "client_id": client_id,
+            "redirect_uri": redirect_uri,
+            "response_type": "code",
+            "scope": scope,
+            "state": state,
+        }
+        if prompt:
+            params["prompt"] = prompt
+        if access_type:
+            params["access_type"] = access_type
+        if login_hint:
+            params["login_hint"] = login_hint
+        if include_granted_scopes:
+            params["include_granted_scopes"] = "true"
+
+        return f"{_settings.google_oauth_auth_url}?{urlencode(params)}"
+
+    # ------------------------------------------------------------------
+    # Token endpoint helpers
+    # ------------------------------------------------------------------
+
+    async def _post_token(
+        self, data: Dict[str, str], *, context: str
+    ) -> Dict[str, Any]:
+        client = await self._get_client()
+        last_error: Optional[str] = None
+
+        for attempt in range(1 + _settings.google_oauth_max_retries):
+            try:
+                response = await client.post(_settings.google_oauth_token_url, data=data)
+                if response.status_code == 200:
+                    return response.json()
+
+                if response.status_code in _RETRYABLE_STATUS:
+                    last_error = (
+                        f"Google OAuth upstream error HTTP {response.status_code}"
+                    )
+                    _logger.warning(
+                        "%s: transient HTTP %s (attempt %d/%d)",
+                        context,
+                        response.status_code,
+                        attempt + 1,
+                        1 + _settings.google_oauth_max_retries,
+                    )
+                else:
+                    return self._parse_token_error(response, context=context)
+
+            except httpx.TimeoutException:
+                last_error = "Google OAuth request timed out"
+                _logger.warning(
+                    "%s: timeout (attempt %d/%d)",
+                    context,
+                    attempt + 1,
+                    1 + _settings.google_oauth_max_retries,
+                )
+            except httpx.RequestError as exc:
+                last_error = f"Google OAuth request failed: {exc}"
+                _logger.warning(
+                    "%s: %s (attempt %d/%d)",
+                    context,
+                    last_error,
+                    attempt + 1,
+                    1 + _settings.google_oauth_max_retries,
+                )
+
+            if attempt < _settings.google_oauth_max_retries:
+                await asyncio.sleep(2 ** attempt)
+
+        raise GoogleOAuthError(last_error or "Unknown Google OAuth error", status_code=502)
+
+    @staticmethod
+    def _parse_token_error(
+        response: httpx.Response, *, context: str
+    ) -> Dict[str, Any]:
+        try:
+            body = response.json()
+            error: str = body.get("error", "") or ""
+            error_description: str = body.get("error_description", "") or ""
+        except Exception:
+            error = ""
+            error_description = ""
+            body = {}
+
+        _logger.warning("%s: Google token error '%s': %s", context, error, error_description)
+
+        if error == "invalid_grant":
+            message = error_description or (
+                "The provided code or refresh token is invalid, expired, or has been revoked."
+            )
+            raise GoogleOAuthError(message, status_code=401)
+        if error == "invalid_client":
+            raise GoogleOAuthError(
+                error_description or "Invalid client_id or client_secret.", status_code=401
+            )
+        if error == "invalid_request":
+            raise GoogleOAuthError(
+                error_description or "Malformed OAuth request.", status_code=400
+            )
+        if error == "access_denied":
+            raise GoogleOAuthError(
+                error_description or "Access denied by the user.", status_code=403
+            )
+
+        # Google does not return a structured error body for some failures.
+        if response.status_code >= 500:
+            raise GoogleOAuthError(
+                "Google OAuth service is temporarily unavailable.", status_code=502
+            )
+        if response.status_code == 429:
+            raise GoogleOAuthError(
+                "Google OAuth rate limit exceeded. Please retry later.", status_code=429
+            )
+
+        message = error_description or f"Google OAuth error (HTTP {response.status_code})."
+        return {"error": True, "message": message, "raw": body}
+
+    # ------------------------------------------------------------------
+    # Code exchange (Step 2)
+    # ------------------------------------------------------------------
+
+    async def exchange_code(
+        self,
+        *,
+        client_id: str,
+        client_secret: str,
+        code: str,
+        redirect_uri: str,
+    ) -> Dict[str, Any]:
+        data = {
+            "client_id": client_id,
+            "client_secret": client_secret,
+            "code": code,
+            "grant_type": "authorization_code",
+            "redirect_uri": redirect_uri,
+        }
+        tokens = await self._post_token(data, context="authorization code exchange")
+        self._raise_for_token_error(tokens)
+        return tokens
+
+    async def refresh_access_token(
+        self,
+        *,
+        client_id: str,
+        client_secret: str,
+        refresh_token: str,
+    ) -> Dict[str, Any]:
+        data = {
+            "client_id": client_id,
+            "client_secret": client_secret,
+            "refresh_token": refresh_token,
+            "grant_type": "refresh_token",
+        }
+        tokens = await self._post_token(data, context="refresh token exchange")
+        self._raise_for_token_error(tokens)
+        return tokens
+
+    @staticmethod
+    def _raise_for_token_error(tokens: Dict[str, Any]) -> None:
+        if tokens.get("error"):
+            raise GoogleOAuthError(tokens.get("message", "Unknown OAuth error"), status_code=400)
+        if not tokens.get("access_token"):
+            raise GoogleOAuthError(
+                "Google did not return an access token.", status_code=502
+            )
+
+    # ------------------------------------------------------------------
+    # ID token verification
+    # ------------------------------------------------------------------
+
+    async def verify_id_token(
+        self, id_token: str, client_id: str
+    ) -> GoogleOAuthUserInfo:
+        client = await self._get_client()
+
+        try:
+            unverified = jwt.get_unverified_header(id_token)
+            kid = unverified.get("kid")
+            alg = unverified.get("alg")
+        except jwt.DecodeError as exc:
+            raise GoogleOAuthError("Malformed ID token.", status_code=400) from exc
+
+        if not kid or alg != "RS256":
+            raise GoogleOAuthError(
+                "ID token does not use an RS256 signature.", status_code=401
+            )
+
+        try:
+            public_key = await self._jwks.get_public_key(client, kid)
+        except GoogleOAuthError:
+            raise
+
+        try:
+            payload = jwt.decode(
+                id_token,
+                key=public_key,
+                algorithms=["RS256"],
+                audience=client_id,
+                issuer=["accounts.google.com", "https://accounts.google.com"],
+                options={
+                    "verify_exp": True,
+                    "verify_iat": True,
+                    "verify_aud": True,
+                    "verify_iss": True,
+                    "require": ["exp", "iat", "sub", "email"],
+                },
+            )
+        except jwt.ExpiredSignatureError as exc:
+            raise GoogleOAuthError("ID token has expired.", status_code=401) from exc
+        except jwt.InvalidAudienceError as exc:
+            raise GoogleOAuthError(
+                "ID token audience does not match the provided client_id.", status_code=401
+            ) from exc
+        except jwt.InvalidIssuerError as exc:
+            raise GoogleOAuthError(
+                "ID token issuer is not Google.", status_code=401
+            ) from exc
+        except jwt.PyJWTError as exc:
+            _logger.warning("ID token verification failed: %s", exc)
+            raise GoogleOAuthError("Invalid ID token.", status_code=401) from exc
+
+        return self._user_info_from_claims(payload)
+
+    # ------------------------------------------------------------------
+    # Userinfo (fallback profile source)
+    # ------------------------------------------------------------------
+
+    async def fetch_userinfo(self, access_token: str) -> GoogleOAuthUserInfo:
+        client = await self._get_client()
+        try:
+            response = await client.get(
+                _settings.google_oauth_userinfo_url,
+                headers={"Authorization": f"Bearer {access_token}"},
+            )
+            response.raise_for_status()
+        except httpx.HTTPStatusError as exc:
+            if exc.response.status_code in (401, 403):
+                raise GoogleOAuthError(
+                    "Access token is invalid or has expired.", status_code=401
+                ) from exc
+            raise GoogleOAuthError(
+                "Failed to fetch Google user profile.", status_code=502
+            ) from exc
+        except httpx.RequestError as exc:
+            raise GoogleOAuthError(
+                "Failed to reach Google userinfo endpoint.", status_code=502
+            ) from exc
+
+        return self._user_info_from_claims(response.json())
+
+    @staticmethod
+    def _user_info_from_claims(payload: Dict[str, Any]) -> GoogleOAuthUserInfo:
+        return GoogleOAuthUserInfo(
+            sub=payload.get("sub", ""),
+            email=payload.get("email", ""),
+            email_verified=bool(payload.get("email_verified", False)),
+            name=payload.get("name"),
+            given_name=payload.get("given_name"),
+            family_name=payload.get("family_name"),
+            picture=payload.get("picture"),
+            locale=payload.get("locale"),
+        )

requirements.txt

@@ -33,6 +33,7 @@ phonenumbers>=8.13.0
 sqlglot>=20.0.0
 tiktoken>=0.9.0
 PyJWT>=2.9.0
+cryptography>=42.0.0
 
 # Authentication
 argon2-cffi>=23.1.0