SEP-1908: Drive ty's error-severity diagnostics to zero so make typecheck exits 0

app/api/deps.py

@@ -31,14 +31,18 @@
     HTTPUnauthorizedException,
     InactiveUserException,
 )
-from app.core.auth.models import UserRole
+from app.core.auth.models import BaseUser, UserRole
 from app.core.auth.utils import get_user_model
 from app.core.config import settings
 from app.core.log import set_log_context
 from app.core.security import is_bearer_authenticated, SAFE_HTTP_METHODS
 from app.sep.config import sep_settings
 
 logger = logging.getLogger(__name__)
+#: The provider-selected concrete user class, resolved from configuration at
+#: import time. Annotations below name ``BaseUser`` instead, which is the
+#: strongest type that is statically knowable here; nothing reads those
+#: annotations at runtime.
 User = get_user_model()
 
 oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/api/oauth/token")
@@ -59,7 +63,7 @@
 )
 
 
-def _build_service_principal(secret: str) -> User:
+def _build_service_principal(secret: str) -> BaseUser:
     """Return a per-request copy of the service principal with ``access_token`` set.
 
     ``access_token`` is a property-backed private attribute on ``BaseUser``;
@@ -76,7 +80,7 @@ def _build_service_principal(secret: str) -> User:
     return user
 
 
-async def authenticate_bearer_token(token: str) -> User:
+async def authenticate_bearer_token(token: str) -> BaseUser:
     """Return the authenticated user from an OAuth2 token.
 
     When ``settings.SEP_INTERNAL_TOKEN`` is configured and the incoming Bearer
@@ -124,7 +128,7 @@ async def authenticate_bearer_token(token: str) -> User:
 _RESOLVED_USERS_KEY: Final = "app.api.deps.resolved_users"
 
 
-async def get_current_user(request: Request, token: AuthToken) -> User:
+async def get_current_user(request: Request, token: AuthToken) -> BaseUser:
     """Return the authenticated user, resolving each credential once per request.
 
     The cache is keyed on a digest of the credential, so a resolution is never
@@ -146,7 +150,7 @@ async def get_current_user(request: Request, token: AuthToken) -> User:
     :raises BaseAuthProviderException: If the auth provider errors while
         validating the credential.
     """
-    resolved: dict[bytes, User] = request.scope.setdefault(_RESOLVED_USERS_KEY, {})
+    resolved: dict[bytes, BaseUser] = request.scope.setdefault(_RESOLVED_USERS_KEY, {})
     key = sha256(token.encode()).digest()
     if (user := resolved.get(key)) is not None:
         set_log_context(user=user.username)
@@ -156,10 +160,10 @@ async def get_current_user(request: Request, token: AuthToken) -> User:
 
 
 IsAuthenticatedDep = Depends(get_current_user)
-CurrentUser = Annotated[User, IsAuthenticatedDep]
+CurrentUser = Annotated[BaseUser, IsAuthenticatedDep]
 
 
-async def get_current_admin(current_user: CurrentUser) -> User:
+async def get_current_admin(current_user: CurrentUser) -> BaseUser:
     """Return the authenticated admin from an OAuth2 token.
 
     :param current_user: The current logged-in user.
@@ -176,7 +180,7 @@ async def get_current_admin(current_user: CurrentUser) -> User:
 IsAdminDep = Depends(get_current_admin)
 
 
-async def get_current_service_principal(current_user: CurrentUser) -> User:
+async def get_current_service_principal(current_user: CurrentUser) -> BaseUser:
     """Return the authenticated caller only when it is the service principal.
 
     Gates writes whose rows a syncer owns: those writes authenticate with

app/api/routes/users.py

@@ -16,11 +16,13 @@
 """Define the API routes for User actions."""
 
 import logging
+from collections.abc import Sequence
 
 from fastapi import APIRouter
 
 from app.api.deps import CurrentUser, IsAdminDep
 from app.core.auth.exceptions import HTTPForbiddenException
+from app.core.auth.models import BaseUser
 from app.core.auth.utils import get_user_model
 
 logger = logging.getLogger(__name__)
@@ -30,18 +32,24 @@
 User = get_user_model()
 
 
-@router.get("/", dependencies=[IsAdminDep])
-async def list_users() -> list[User]:
+@router.get(
+    "/",
+    dependencies=[IsAdminDep],
+    # pagination-ok: the provider SDK returns the whole organization in one call
+    # (Casdoor /api/get-users, Grafana /api/org/users), so there is no upstream
+    # window to page against; the cardinality is the operator's own user count.
+    response_model=list[User],  # ty: ignore[invalid-type-form]
+)
+async def list_users() -> Sequence[BaseUser]:
     """List users.
 
     :return: The list of users.
-    :rtype: list[User]
     """
     return await User.get_users()
 
 
-@router.get("/me")
-async def retrieve_current_user(current_user: CurrentUser) -> User:
+@router.get("/me", response_model=User)
+async def retrieve_current_user(current_user: CurrentUser) -> BaseUser:
     """Retrieve the current authenticated user.
 
     :param current_user: The current authenticated user.
@@ -52,8 +60,8 @@ async def retrieve_current_user(current_user: CurrentUser) -> User:
     return current_user
 
 
-@router.get("/{username}")
-async def retrieve_user(current_user: CurrentUser, username: str) -> User:
+@router.get("/{username}", response_model=User)
+async def retrieve_user(current_user: CurrentUser, username: str) -> BaseUser:
     """Retrieve a user by username.
 
     :param current_user: The current authenticated user.

app/core/alerts/providers/pagerduty.py

@@ -109,13 +109,23 @@ async def get_api(self) -> RemoteAPI:
         """
         return await settings.get_remote_api(endpoint=self.api_endpoint)
 
-    @validate_call
-    async def send_alert(self, alert: PagerDutyAlert) -> None:
+    async def send_alert(self, alert: Alert) -> None:
         """Send an alert to PagerDuty using the Events API v2.
 
-        :param alert: The alert to be sent.
-        :type alert: PagerDutyAlert
+        The dispatcher hands every provider the base :class:`Alert`, so the
+        PagerDuty-specific fields are resolved here rather than by widening what
+        the base contract promises. Carries no ``validate_call``: that would
+        coerce the argument to :class:`Alert` first, and ``AlertSeverity`` has
+        neither the lowercase values nor the name-or-value lookup that
+        ``PagerDutyAlertSeverity`` accepts, so a mapping naming ``"critical"``
+        would be rejected before reaching the conversion below.
+
+        :param alert: The alert to be sent, as an :class:`Alert`, a
+            :class:`PagerDutyAlert`, or a mapping of either's fields.
+        :raises ValidationError: If ``alert`` carries no PagerDuty severity.
         """
+        if not isinstance(alert, PagerDutyAlert):
+            alert = PagerDutyAlert.model_validate(alert, from_attributes=True)
         pagerduty_api = await self.get_api()
         await pagerduty_api.post(
             "enqueue",

app/core/auth/models.py

@@ -367,14 +367,13 @@ async def get_user(cls, username: NonEmptyStr) -> Self:
 
     @classmethod
     @abstractmethod
-    async def get_users(cls) -> list[Self]:
+    async def get_users(cls) -> Sequence[Self]:
         """Retrieve all users.
 
         This method must be overridden in subclasses to provide specific logic for
         retrieving all users from the data store.
 
-        :return: A list of user instances.
-        :rtype: list[Self]
+        :return: A sequence of user instances.
         """
 
     @classmethod

app/core/auth/providers/casdoor/models.py

@@ -254,12 +254,18 @@ async def get_users(cls) -> list[Self]:
         return [cls(**user_data) for user_data in users_data]
 
     @classmethod
-    async def from_token_payload(cls, token_payload: CasdoorTokenPayload) -> Self:
+    async def from_token_payload(cls, token_payload: BaseTokenPayload) -> Self:
         """Create an instance of ``CasdoorUser`` from a ``CasdoorTokenPayload``.
 
         :param token_payload: The Casdoor token payload containing user information.
         :return: An instance of ``CasdoorUser``.
+        :raises TypeError: If the payload is not a ``CasdoorTokenPayload``.
         """
+        if not isinstance(token_payload, CasdoorTokenPayload):
+            raise TypeError(
+                f"CasdoorUser requires a CasdoorTokenPayload, got "
+                f"{type(token_payload).__name__}"
+            )
         return await cls.get_user(token_payload.username)
 
     @classmethod

app/core/auth/providers/casdoor/sdk.py

@@ -30,7 +30,7 @@
     BaseAuthProviderException,
     HTTPUnauthorizedException,
 )
-from app.core.requests import RemoteAPI
+from app.core.requests import as_json_object, JSONBody, RemoteAPI
 from app.core.utils.fields import NonEmptyStr, RelativeFilePathField, StrHttpUrl, URL
 
 
@@ -167,20 +167,21 @@ def get_frontend_url(self, base_url: URL | None = None) -> URL:
             "port": self.front_endpoint.port or base_url.port,
             "path": self.front_endpoint.path or base_url.path,
         }
-        return self.front_endpoint.replace(**url_data)
+        return URL(str(self.front_endpoint.replace(**url_data)))
 
     async def request(
         self,
         method: str,
         path: str,
         **kwargs: Any,
-    ) -> dict[str, Any] | list[dict[str, Any]]:
+    ) -> JSONBody:
         """Perform an HTTP request and return the JSON response.
 
         :param method: The HTTP method to use for the request.
         :param path: The API endpoint path to request.
         :param kwargs: Additional keyword arguments to pass to the request.
-        :return: The JSON response as a Python object.
+        :return: The JSON response as a Python object, or ``None`` when Casdoor
+            answers HTTP 204 with no body.
         :raises HTTPException: If the request returns an error response.
         """
         try:
@@ -213,7 +214,9 @@ async def refresh_token_request(
             "scope": scope,
             "refresh_token": refresh_token,
         }
-        return await self.post("/api/login/oauth/refresh_token", json=data)
+        return as_json_object(
+            await self.post("/api/login/oauth/refresh_token", json=data)
+        )
 
     async def get_access_token(
         self,
@@ -253,7 +256,9 @@ async def get_access_token(
             data["grant_type"] = "password"
             invalid_grant_message = "Invalid username or password."
         try:
-            return await self.post("/api/login/oauth/access_token", json=data)
+            return as_json_object(
+                await self.post("/api/login/oauth/access_token", json=data)
+            )
         except HTTPException as exc:
             if exc.headers and exc.headers.get("X-Error-Code") == "invalid_grant":
                 raise HTTPUnauthorizedException(invalid_grant_message) from None
@@ -264,7 +269,7 @@ async def get_version_info(self) -> dict[str, Any]:
 
         :return: A dictinoary containin Casdoor's version details.
         """
-        version = await self.get("/api/get-version-info")
+        version = as_json_object(await self.get("/api/get-version-info"))
         return version["data"]
 
     async def introspect_token(
@@ -292,10 +297,12 @@ async def introspect_token(
             token_type_hint = token_type.replace("-", "_")
         else:
             token_type_hint = token_type
-        return await self.post(
-            "/api/login/oauth/introspect",
-            data={"token": token, "token_type_hint": token_type_hint},
-            headers={"Content-Type": "application/x-www-form-urlencoded"},
+        return as_json_object(
+            await self.post(
+                "/api/login/oauth/introspect",
+                data={"token": token, "token_type_hint": token_type_hint},
+                headers={"Content-Type": "application/x-www-form-urlencoded"},
+            )
         )
 
     async def get_token(self, token_id: str) -> dict[str, Any]:
@@ -306,7 +313,9 @@ async def get_token(self, token_id: str) -> dict[str, Any]:
         :param token_id: The ID of the token to retrieve.
         :return: The token details retrieved from Casdoor.
         """
-        response = await self.get("/api/get-token", params={"id": token_id})
+        response = as_json_object(
+            await self.get("/api/get-token", params={"id": token_id})
+        )
         return response["data"]
 
     async def get_tokens(
@@ -330,14 +339,18 @@ async def get_tokens(
             "pageSize": page_size,
             "p": 1,
         }
-        tokens = await self.get(
-            "/api/get-tokens",
-            params=params,
+        tokens: dict[str, Any] | None = as_json_object(
+            await self.get(
+                "/api/get-tokens",
+                params=params,
+            )
         )
         max_page = ceil((tokens.get("data2") or 0) / page_size)
         while params["p"] <= max_page:
             if tokens is None:
-                tokens = await self.get("/api/get-tokens", params=params)
+                tokens = as_json_object(
+                    await self.get("/api/get-tokens", params=params)
+                )
             for token in tokens["data"]:
                 if username is None or token["user"] == username:
                     yield token
@@ -370,7 +383,7 @@ async def delete_token(self, token: dict[str, Any]) -> bool:
         :param token: The token to delete.
         :return: Whether the token was deleted.
         """
-        response = await self.post("/api/delete-token", json=token)
+        response = as_json_object(await self.post("/api/delete-token", json=token))
         return response["data"].lower() == "affected"
 
     @alru_cache(ttl=300)
@@ -381,8 +394,8 @@ async def get_users(self) -> list[dict[str, Any]]:
 
         :return: A list of user data.
         """
-        users = await self.get(
-            "/api/get-users", params={"owner": self.organization_name}
+        users = as_json_object(
+            await self.get("/api/get-users", params={"owner": self.organization_name})
         )
         return users["data"]
 
@@ -394,9 +407,11 @@ async def get_user(self, username: str) -> dict[str, Any]:
         :param username: The username of the user to retrieve.
         :return: A dictionary containing the user's information.
         """
-        user = await self.get(
-            "/api/get-user",
-            params={"id": f"{self.organization_name}/{username}"},
+        user = as_json_object(
+            await self.get(
+                "/api/get-user",
+                params={"id": f"{self.organization_name}/{username}"},
+            )
         )
         return user["data"]
 
@@ -408,8 +423,10 @@ async def get_user_application(self, username: str) -> dict[str, Any]:
         :param username: The username of the user to retrieve.
         :return: A dictionary containing the user's information.
         """
-        user = await self.get(
-            "/api/get-user-application",
-            params={"id": f"{self.organization_name}/{username}"},
+        user = as_json_object(
+            await self.get(
+                "/api/get-user-application",
+                params={"id": f"{self.organization_name}/{username}"},
+            )
         )
         return user["data"]

app/core/auth/providers/grafana/models.py

@@ -640,7 +640,13 @@ async def from_bearer(cls, token: str) -> Self:
         :raises ValidationError: If the assertion is tampered, malformed, expired
             against the lifetime of every accepted type, or of a type this
             surface does not accept.
+        :raises GrafanaException: If the accepted-type set is empty, so the loop
+            ends with nothing tried and no error to re-raise. Unreachable while
+            ``_BEARER_TOKEN_TYPES`` is a non-empty literal; it is what makes the
+            re-raise below answer for a name that is otherwise only bound inside
+            the loop.
         """
+        last_error: ValidationError | None = None
         for token_type in _BEARER_TOKEN_TYPES:
             try:
                 user = cls.model_validate(token, context={"token_type": token_type})
@@ -649,6 +655,8 @@ async def from_bearer(cls, token: str) -> Self:
                 continue
             user.access_token = token
             return user
+        if last_error is None:
+            raise GrafanaException("No bearer token type is accepted on this surface.")
         raise last_error
 
     @classmethod