feat(user): implement user restrictions

## APIs Restricted for Restricted Users

A restricted user is blocked from performing the following actions, and will typically receive a `403 Forbidden` error:

*   **Chat & Notifications:**
    *   Sending any chat messages (public or private).
    *   Joining or leaving chat channels.
    *   Creating new PM channels.
*   **User Profile & Content:**
    *   Uploading a new avatar.
    *   Uploading a new profile cover image.
    *   Changing their username.
    *   Updating their userpage content.
*   **Scores & Gameplay:**
    *   Submitting scores in multiplayer rooms.
    *   Deleting their own scores (to prevent hiding evidence of cheating).
*   **Beatmaps:**
    *   Rating beatmaps.
    *   Taging beatmaps.
*   **Relationship:**
    *   Adding friends or blocking users.
    *   Removing friends or unblocking users.
*   **Teams:**
    *   Creating, updating, or deleting a team.
    *   Requesting to join a team.
    *   Handling join requests for a team they manage.
    *   Kicking a member from a team they manage.
*   **Multiplayer:**
    *   Creating or deleting multiplayer rooms.
    *   Joining or leaving multiplayer rooms.

## What is Invisible to Normal Users

*   **Leaderboards:**
    *   Beatmap leaderboards.
    *   Multiplayer (playlist) room leaderboards.
*   **User Search/Lists:**
    *   Restricted users will not appear in the results of the `/api/v2/users` endpoint.
    *   They will not appear in the list of a team's members.
*   **Relationship:**
    *   They will not appear in a user's friend list (`/friends`).
*   **Profile & History:**
    *   Attempting to view a restricted user's profile, events, kudosu history, or score history will result in a `404 Not Found` error, effectively making their profile invisible (unless the user viewing the profile is the restricted user themselves).
*   **Chat:**
    *   Normal users cannot start a new PM with a restricted user (they will get a `404 Not Found` error).
*   **Ranking:**
    *   Restricted users are excluded from any rankings.

### How to Restrict a User

Insert into `user_account_history` with `type=restriction`.

```sql
-- length is in seconds
INSERT INTO user_account_history (`description`, `length`, `permanent`, `timestamp`, `type`, `user_id`) VALUE ('some description', 86400, 0, '2025-10-05 01:00:00', 'RESTRICTION', 1);
```

---

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

app/database/score.py

@@ -501,6 +501,7 @@ async def _score_where(
     wheres: list[ColumnElement[bool] | TextClause] = [
         col(TotalScoreBestScore.beatmap_id) == beatmap,
         col(TotalScoreBestScore.gamemode) == mode,
+        ~User.is_restricted_query(col(TotalScoreBestScore.user_id)),
     ]
 
     if type == LeaderboardType.FRIENDS:

app/database/statistics.py

@@ -77,7 +77,7 @@ class UserStatistics(AsyncAttrs, UserStatisticsBase, table=True):
 
     level_current: float = Field(default=1)
 
-    user: "User" = Relationship(back_populates="statistics")  # type: ignore[valid-type]
+    user: "User" = Relationship(back_populates="statistics")
 
 
 class UserStatisticsResp(UserStatisticsBase):

app/database/user.py

@@ -1,6 +1,6 @@
 from datetime import datetime, timedelta
 import json
-from typing import TYPE_CHECKING, Literal, NotRequired, TypedDict
+from typing import TYPE_CHECKING, Literal, NotRequired, TypedDict, overload
 
 from app.config import settings
 from app.database.auth import TotpKeys
@@ -18,10 +18,11 @@ from .events import Event
 from .rank_history import RankHistory, RankHistoryResp, RankTop
 from .statistics import UserStatistics, UserStatisticsResp
 from .team import Team, TeamMember
-from .user_account_history import UserAccountHistory, UserAccountHistoryResp
+from .user_account_history import UserAccountHistory, UserAccountHistoryResp, UserAccountHistoryType
 
 from pydantic import field_validator
 from sqlalchemy.ext.asyncio import AsyncAttrs
+from sqlalchemy.orm import Mapped
 from sqlmodel import (
     JSON,
     BigInteger,
@@ -31,8 +32,10 @@ from sqlmodel import (
     Relationship,
     SQLModel,
     col,
+    exists,
     func,
     select,
+    text,
 )
 from sqlmodel.ext.asyncio.session import AsyncSession
 
@@ -88,7 +91,6 @@ class UserBase(UTCBaseModel, SQLModel):
     badges: list[Badge] = Field(default_factory=list, sa_column=Column(JSON))
 
     # optional
-    is_restricted: bool = False
     # blocks
     cover: UserProfileCover = Field(
         default=UserProfileCover(url=""),
@@ -155,8 +157,8 @@ class User(AsyncAttrs, UserBase, table=True):
         default=None,
         sa_column=Column(BigInteger, primary_key=True, autoincrement=True, index=True),
     )
-    account_history: list[UserAccountHistory] = Relationship()
-    statistics: list[UserStatistics] = Relationship()
+    account_history: list[UserAccountHistory] = Relationship(back_populates="user")
+    statistics: list[UserStatistics] = Relationship(back_populates="user")
     achievement: list[UserAchievement] = Relationship(back_populates="user")
     team_membership: TeamMember | None = Relationship(back_populates="user")
     daily_challenge_stats: DailyChallengeStats | None = Relationship(back_populates="user")
@@ -206,8 +208,43 @@ class User(AsyncAttrs, UserBase, table=True):
             return False, "Target user has blocked you."
         if self.pm_friends_only and (not relationship or relationship.type != RelationshipType.FOLLOW):
             return False, "Target user has disabled non-friend communications"
+        if await self.is_restricted(session):
+            return False, "Target user is restricted"
         return True, ""
 
+    @classmethod
+    @overload
+    def is_restricted_query(cls, user_id: int): ...
+
+    @classmethod
+    @overload
+    def is_restricted_query(cls, user_id: Mapped[int]): ...
+
+    @classmethod
+    def is_restricted_query(cls, user_id: int | Mapped[int]):
+        return exists().where(
+            (col(UserAccountHistory.user_id) == user_id)
+            & (col(UserAccountHistory.type) == UserAccountHistoryType.RESTRICTION)
+            & (
+                (col(UserAccountHistory.permanent).is_(True))
+                | (
+                    (
+                        func.timestampadd(
+                            text("SECOND"),
+                            col(UserAccountHistory.length),
+                            col(UserAccountHistory.timestamp),
+                        )
+                        > func.now()
+                    )
+                    & (func.now() > col(UserAccountHistory.timestamp))
+                )
+            ),
+        )
+
+    async def is_restricted(self, session: AsyncSession) -> bool:
+        active_restrictions = (await session.exec(select(self.is_restricted_query(self.id)))).first()
+        return active_restrictions or False
+
 
 class UserResp(UserBase):
     id: int | None = None
@@ -246,6 +283,7 @@ class UserResp(UserBase):
     daily_challenge_user_stats: DailyChallengeStatsResp | None = None
     default_group: str = ""
     is_deleted: bool = False  # TODO
+    is_restricted: bool = False
 
     # TODO: monthly_playcounts, unread_pm_count， rank_history, user_preferences
 
@@ -370,6 +408,8 @@ class UserResp(UserBase):
                     if rank_top
                     else None
                 )
+        if "is_restricted" in include:
+            u.is_restricted = await obj.is_restricted(session)
 
         u.favourite_beatmapset_count = (
             await session.exec(
@@ -468,6 +508,7 @@ ALL_INCLUDED = [
     "monthly_playcounts",
     "replays_watched_counts",
     "rank_history",
+    "is_restricted",
     "session_verified",
 ]
 

app/database/user_account_history.py

@@ -1,10 +1,14 @@
 from datetime import datetime
 from enum import Enum
+from typing import TYPE_CHECKING
 
 from app.models.model import UTCBaseModel
 from app.utils import utcnow
 
-from sqlmodel import BigInteger, Column, Field, ForeignKey, Integer, SQLModel
+from sqlmodel import BigInteger, Column, Field, ForeignKey, Integer, Relationship, SQLModel
+
+if TYPE_CHECKING:
+    from .user import User
 
 
 class UserAccountHistoryType(str, Enum):
@@ -35,6 +39,8 @@ class UserAccountHistory(UserAccountHistoryBase, table=True):
     )
     user_id: int = Field(sa_column=Column(BigInteger, ForeignKey("lazer_users.id"), index=True))
 
+    user: "User" = Relationship(back_populates="account_history")
+
 
 class UserAccountHistoryResp(UserAccountHistoryBase):
     id: int | None = None