feat: give the identity an ordered role instead of a single is_admin boolean

Add `UserRole`, an ordered `StrEnum` (none < viewer < editor < admin <
super_admin) whose members compare by rank rather than alphabetically, and a
required `role` field on `BaseUser`. `is_admin` becomes a computed property
equal to `role >= UserRole.ADMIN`, so every consumer keeps reading the same
boolean and admits the same identities.

Each of the five construction paths sets `role` explicitly: the two Grafana
record mappings flatten org memberships by rank (server-admin flag outranking
them), the Casdoor payload derives it from the admin flag, and the service
principal takes `VIEWER`. Both inbound legacy-claim paths reconstruct the role
through one shared helper that validates the flag with Pydantic's boolean
semantics, so a payload spelling the flag "false" or "0" still means non-admin.

The minted assertion is unchanged, so tokens issued before this change keep
decoding; Editor and Viewer therefore stay indistinguishable on bearer
requests until the assertion carries a real role claim.

`role` is required with no default so a construction path that forgets it fails
loudly instead of silently yielding the lowest role. This breaks out-of-tree
`CUSTOM` providers that build identities from `is_admin` alone, which ships as
a breaking changelog fragment.

Author: yyyyyyyan

.github/instructions/tests.instructions.md

@@ -12,7 +12,7 @@ Tests mirror app structure exactly. `app/sep/snippets/config.py` → `tests/app/
 
 ## Factories — never manual dicts
 
-Test data MUST come from a factory, never a hand-rolled `dict`. Core, cross-app factories live in `tests/app/factories.py` (`SchemaWriteFactory`, `TableWriteFactory`, `TaskFactory` / `GeneratedTaskFactory`, `PeriodicTaskFactory`, …). Build with `.build()`, customise inline: `CasdoorUserFactory.build(is_admin=True)`. Use mock ID constants from `tests/app/factories.py`.
+Test data MUST come from a factory, never a hand-rolled `dict`. Core, cross-app factories live in `tests/app/factories.py` (`SchemaWriteFactory`, `TableWriteFactory`, `TaskFactory` / `GeneratedTaskFactory`, `PeriodicTaskFactory`, …). Build with `.build()`, customise inline: `CasdoorUserFactory.build(role=UserRole.ADMIN)`. Use mock ID constants from `tests/app/factories.py`.
 
 **A factory for an app's model belongs in `tests/app/sep/apps/<app>/factories.py`, not the shared file.** `tests/app/factories.py` sits at the root of the test tree, so every subtree imports it — an app-specific factory there couples the shared file to that app and has to be found and deleted by hand when the app goes. Adding an app means adding `tests/app/sep/apps/<app>/factories.py`, never editing the shared module; the app test packages already have `__init__.py`, so `tests.app.sep.apps.<app>.factories` resolves as-is. `tests/app/test_factories_boundary.py` enforces this: any module directly under `tests/app/` that imports `app.sep.apps.*` (or re-exports from `tests.app.sep.apps.*`) fails.
 

app/api/deps.py

@@ -30,6 +30,7 @@
     HTTPUnauthorizedException,
     InactiveUserException,
 )
+from app.core.auth.models import UserRole
 from app.core.auth.utils import get_user_model
 from app.core.config import settings
 from app.core.log import set_log_context
@@ -53,6 +54,7 @@
     username="sep-service",
     first_name="SEP",
     last_name="Service",
+    role=UserRole.VIEWER,
 )
 
 
@@ -166,8 +168,9 @@ async def require_admin_for_unsafe_methods(request: Request) -> None:
 
     ``SEP_INTERNAL_TOKEN``'s service principal is admitted by identity so
     scheduled inventory sync and scheduled execution keep working. The bypass is
-    scoped to this gate: the principal keeps ``is_admin=False`` and every
-    pre-existing ``IsApiAdmin`` / ``IsAdminDep`` check refuses it as before.
+    scoped to this gate: the principal holds ``UserRole.VIEWER``, so it keeps
+    ``is_admin=False`` and every pre-existing ``IsApiAdmin`` / ``IsAdminDep``
+    check refuses it as before.
 
     :param request: The incoming HTTP request.
     :raises HTTPUnauthorizedException: When the method is unsafe and the request

app/core/auth/models.py

@@ -18,20 +18,28 @@
 from abc import ABC, abstractmethod
 from collections.abc import Sequence
 from datetime import datetime
+from enum import StrEnum
 from functools import cached_property
-from typing import Any, Self
+from typing import Any, Final, Self
 
 from pydantic import (
     BaseModel,
     computed_field,
     Field,
     FutureDatetime,
     PastDatetime,
+    TypeAdapter,
     UUID4,
+    ValidationError,
 )
 
 from app.core.utils.date_time import utc_now
-from app.core.utils.fields import EmptyStrToNone, NonEmptyStr, TimedeltaSeconds
+from app.core.utils.fields import (
+    EmptyStrToNone,
+    EnumFieldMixin,
+    NonEmptyStr,
+    TimedeltaSeconds,
+)
 
 
 class OAuthToken(BaseModel):
@@ -125,6 +133,62 @@ async def from_jwt(cls, token: str) -> Self:
         """
 
 
+class UserRole(EnumFieldMixin, StrEnum):
+    """Enumerate an identity's access level, lowest to highest.
+
+    Members and ordering mirror PMM's own authorization vocabulary so the two
+    products stay semantically aligned; ``SUPER_ADMIN`` is SEP's
+    provider-neutral name for the rank PMM calls ``grafanaAdmin``.
+
+    Members compare by rank rather than by name: ``EDITOR < ADMIN`` even
+    though ``"editor" > "admin"`` lexicographically. All four comparisons are
+    spelled out, and each refuses a non-member, because ``str`` supplies its own
+    alphabetical implementations. Whatever this class leaves to ``str`` — an
+    operator it does not override, or an operand it declines — silently ranks
+    ``EDITOR`` above ``ADMIN``. Equality is untouched, so ``ADMIN == "admin"``
+    still holds.
+    """
+
+    NONE = "none"
+    VIEWER = "viewer"
+    EDITOR = "editor"
+    ADMIN = "admin"
+    SUPER_ADMIN = "super_admin"
+
+    def __lt__(self, other: object) -> bool:
+        return _rank(self) < _rank(other)
+
+    def __le__(self, other: object) -> bool:
+        return _rank(self) <= _rank(other)
+
+    def __gt__(self, other: object) -> bool:
+        return _rank(self) > _rank(other)
+
+    def __ge__(self, other: object) -> bool:
+        return _rank(self) >= _rank(other)
+
+
+_USER_ROLE_ORDER: Final = tuple(UserRole)
+
+
+def _rank(role: object) -> int:
+    """Return a role's position in the declared order, lowest first.
+
+    :param role: The value to rank.
+    :return: The role's rank.
+    :raises TypeError: If ``role`` is not a :class:`UserRole`. Returning
+        ``NotImplemented`` instead would hand the comparison back to ``str``,
+        which answers it alphabetically, making ``UserRole.EDITOR >= "admin"``
+        True.
+    """
+    if not isinstance(role, UserRole):
+        raise TypeError(f"cannot order UserRole against {type(role).__name__}")
+    return _USER_ROLE_ORDER.index(role)
+
+
+_ADMIN_FLAG_ADAPTER: Final = TypeAdapter(bool)
+
+
 class BaseUser(BaseModel, ABC):
     """Represent the abstract base for a user.
 
@@ -133,8 +197,7 @@ class BaseUser(BaseModel, ABC):
     :param email: The email address of the user.
     :param first_name: The first name of the user.
     :param last_name: The last name of the user.
-    :param is_admin: Whether the user has administrative privileges. Defaults
-        to False.
+    :param role: The user's access level. ``is_admin`` is derived from it.
     :param created_time: The datetime when the user was created. Defaults to
         current datetime.
     :param updated_time: The datetime when the user was last updated. Defaults
@@ -146,7 +209,7 @@ class BaseUser(BaseModel, ABC):
     email: str = ""
     first_name: str = ""
     last_name: str = ""
-    is_admin: bool = False
+    role: UserRole
     created_time: datetime | EmptyStrToNone = Field(default_factory=utc_now)
     updated_time: datetime | EmptyStrToNone = Field(default_factory=utc_now)
     _access_token: str = ""
@@ -171,6 +234,38 @@ def is_active(self) -> bool:
         """
         return True
 
+    @computed_field
+    @property
+    def is_admin(self) -> bool:
+        """Indicate whether the user holds administrative privileges.
+
+        :return: True from ``ADMIN`` upwards, False below it.
+        """
+        return self.role >= UserRole.ADMIN
+
+    @staticmethod
+    def _role_from_admin_flag(flag: Any) -> UserRole:
+        """Map a legacy admin flag onto the ordered role.
+
+        The flag carries one bit, so it resolves only to the two roles the
+        admin gates already distinguish: ``ADMIN`` preserves the access the flag
+        granted, ``VIEWER`` the reads a non-admin has today.
+
+        The flag is validated rather than tested for truthiness, so a payload
+        spelling the boolean as ``"false"`` or ``"0"`` keeps the meaning the
+        removed ``is_admin`` field gave it instead of resolving to ``ADMIN``.
+
+        :param flag: The raw admin flag carried by a provider payload.
+        :return: The role the flag maps to.
+        :raises ValueError: If the flag is not a value Pydantic accepts as a
+            boolean, matching the error the removed field raised.
+        """
+        try:
+            is_admin = _ADMIN_FLAG_ADAPTER.validate_python(flag)
+        except ValidationError as exc:
+            raise ValueError(f"invalid admin flag: {flag!r}") from exc
+        return UserRole.ADMIN if is_admin else UserRole.VIEWER
+
     @property
     def access_token(self) -> str:
         """Get the user's access token.
@@ -195,10 +290,10 @@ def build_service_principal(
         *,
         user_id: UUID4,
         username: NonEmptyStr,
+        role: UserRole,
         email: str = "",
         first_name: str = "",
         last_name: str = "",
-        is_admin: bool = False,
         **provider_fields: Any,
     ) -> Self:
         """Build the synthetic service-principal user for SEP-internal auth.
@@ -209,11 +304,10 @@ def build_service_principal(
 
         :param user_id: The service principal's stable unique identifier.
         :param username: The service principal's username.
+        :param role: The service principal's access level.
         :param email: The service principal's email address; empty by default.
         :param first_name: The service principal's first name; empty by default.
         :param last_name: The service principal's last name; empty by default.
-        :param is_admin: Whether the principal has administrative privileges;
-            ``False`` by default.
         :return: A user instance representing the service principal.
         """
         return cls(
@@ -222,7 +316,7 @@ def build_service_principal(
             email=email,
             first_name=first_name,
             last_name=last_name,
-            is_admin=is_admin,
+            role=role,
             **provider_fields,
         )
 

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

@@ -18,10 +18,17 @@
 from collections.abc import Sequence
 from typing import Annotated, Any, cast, Literal, Self
 
-from pydantic import AliasChoices, computed_field, ConfigDict, Field, field_validator
+from pydantic import (
+    AliasChoices,
+    computed_field,
+    ConfigDict,
+    Field,
+    field_validator,
+    model_validator,
+)
 from pydantic.alias_generators import to_camel
 
-from app.core.auth.models import BaseTokenPayload, BaseUser, OAuthToken
+from app.core.auth.models import BaseTokenPayload, BaseUser, OAuthToken, UserRole
 from app.core.auth.providers.casdoor.sdk import CasdoorSDK
 
 CasdoorUsernameField = Annotated[
@@ -107,7 +114,8 @@ class CasdoorUser(BaseUser):
     :param email: The email address of the user.
     :param first_name: The first name of the user.
     :param last_name: The last name of the user.
-    :param is_admin: Whether the user has administrative privileges. Defaults to False.
+    :param role: The user's access level, derived from Casdoor's admin flag when
+        the payload carries no role of its own.
     :param created_time: The datetime when the user was created. Defaults to current
         datetime.
     :param updated_time: The datetime when the user was last updated. Defaults to
@@ -126,6 +134,32 @@ class CasdoorUser(BaseUser):
     is_forbidden: bool = False
     is_deleted: bool = False
 
+    @model_validator(mode="before")
+    @classmethod
+    def _derive_role(cls, data: Any) -> Any:
+        """Derive the ordered role from Casdoor's admin flag.
+
+        Casdoor exposes no role concept, so the payload's admin boolean is the
+        only signal. An unset flag resolves to ``VIEWER`` rather than the lowest
+        role, keeping the read access a non-admin Casdoor user has today; a flag
+        that is present keeps the boolean semantics it had as a model field,
+        including its rejection of a non-boolean.
+
+        Both wire spellings are read because ``model_config`` accepts either:
+        Casdoor's API sends ``isAdmin``, SEP's own fixtures ``is_admin``.
+
+        :param data: The raw model input.
+        :return: The input with a ``role`` filled in, or ``data`` unchanged.
+        :raises ValueError: If the admin flag is not a value Pydantic accepts as
+            a boolean.
+        """
+        if not isinstance(data, dict) or "role" in data:
+            return data
+        for key in ("isAdmin", "is_admin"):
+            if key in data:
+                return {**data, "role": cls._role_from_admin_flag(data[key])}
+        return {**data, "role": UserRole.VIEWER}
+
     @computed_field
     @property
     def is_active(self) -> bool: