feat(auth): support trusted device (#52)

New API to maintain sessions and devices:

- GET /api/private/admin/sessions
- DELETE /api/private/admin/sessions/{session_id}
- GET /api/private/admin/trusted-devices
- DELETE /api/private/admin/trusted-devices/{device_id}

Auth:

web clients request `/oauth/token` and `/api/v2/session/verify` with `X-UUID` header to save the client as trusted device.

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

app/database/__init__.py

@@ -68,7 +68,7 @@ from .user_account_history import (
     UserAccountHistoryType,
 )
 from .user_login_log import UserLoginLog
-from .verification import EmailVerification, LoginSession
+from .verification import EmailVerification, LoginSession, LoginSessionResp, TrustedDevice, TrustedDeviceResp
 
 __all__ = [
     "APIUploadedRoom",
@@ -96,6 +96,7 @@ __all__ = [
     "ItemAttemptsCount",
     "ItemAttemptsResp",
     "LoginSession",
+    "LoginSessionResp",
     "MeResp",
     "MonthlyPlaycounts",
     "MultiplayerEvent",
@@ -131,6 +132,8 @@ __all__ = [
     "TeamMember",
     "TeamRequest",
     "TotpKeys",
+    "TrustedDevice",
+    "TrustedDeviceResp",
     "User",
     "UserAccountHistory",
     "UserAccountHistoryResp",

app/database/auth.py

@@ -32,7 +32,8 @@ class OAuthToken(UTCBaseModel, SQLModel, table=True):
     refresh_token: str = Field(max_length=500, unique=True)
     token_type: str = Field(default="Bearer", max_length=20)
     scope: str = Field(default="*", max_length=100)
-    expires_at: datetime = Field(sa_column=Column(DateTime))
+    expires_at: datetime = Field(sa_column=Column(DateTime, index=True))
+    refresh_token_expires_at: datetime = Field(sa_column=Column(DateTime, index=True))
     created_at: datetime = Field(default_factory=utcnow, sa_column=Column(DateTime))
 
     user: "User" = Relationship()

app/database/lazer_user.py

@@ -243,7 +243,6 @@ class UserResp(UserBase):
     user_achievements: list[UserAchievementResp] = Field(default_factory=list)
     cover_url: str = ""  # deprecated
     team: Team | None = None
-    session_verified: bool = True
     daily_challenge_user_stats: DailyChallengeStatsResp | None = None
     default_group: str = ""
     is_deleted: bool = False  # TODO
@@ -425,27 +424,18 @@ class UserResp(UserBase):
             )
         ).one()
 
-        if "session_verified" in include:
-            from app.service.verification_service import LoginSessionService
-
-            u.session_verified = (
-                not await LoginSessionService.check_is_need_verification(session, user_id=obj.id, token_id=token_id)
-                if token_id
-                else True
-            )
-
         return u
 
 
 class MeResp(UserResp):
     session_verification_method: Literal["totp", "mail"] | None = None
+    session_verified: bool = True
 
     @classmethod
     async def from_db(
         cls,
         obj: User,
         session: AsyncSession,
-        include: list[str] = [],
         ruleset: GameMode | None = None,
         *,
         token_id: int | None = None,
@@ -453,7 +443,12 @@ class MeResp(UserResp):
         from app.dependencies.database import get_redis
         from app.service.verification_service import LoginSessionService
 
-        u = await super().from_db(obj, session, ["session_verified", *include], ruleset, token_id=token_id)
+        u = await super().from_db(obj, session, ALL_INCLUDED, ruleset, token_id=token_id)
+        u.session_verified = (
+            not await LoginSessionService.check_is_need_verification(session, user_id=obj.id, token_id=token_id)
+            if token_id
+            else True
+        )
         u = cls.model_validate(u.model_dump())
         if (settings.enable_totp_verification or settings.enable_email_verification) and token_id:
             redis = get_redis()

app/database/verification.py

@@ -3,17 +3,26 @@
 """
 
 from datetime import datetime
-from typing import TYPE_CHECKING, Optional
+from typing import TYPE_CHECKING, Literal, Optional
 
-from app.utils import utcnow
+from app.helpers.geoip_helper import GeoIPHelper
+from app.models.model import UserAgentInfo, UTCBaseModel
+from app.utils import extract_user_agent, utcnow
 
+from pydantic import BaseModel
 from sqlalchemy import BigInteger, Column, ForeignKey
-from sqlmodel import Field, Integer, Relationship, SQLModel
+from sqlmodel import VARCHAR, DateTime, Field, Integer, Relationship, SQLModel, Text
 
 if TYPE_CHECKING:
     from .auth import OAuthToken
 
 
+class Location(BaseModel):
+    country: str = ""
+    city: str = ""
+    country_code: str = ""
+
+
 class EmailVerification(SQLModel, table=True):
     """邮件验证记录"""
 
@@ -31,25 +40,90 @@ class EmailVerification(SQLModel, table=True):
     user_agent: str | None = Field(default=None)  # 用户代理
 
 
-class LoginSession(SQLModel, table=True):
+class LoginSessionBase(SQLModel):
     """登录会话记录"""
 
-    __tablename__: str = "login_sessions"
-
-    id: int | None = Field(default=None, primary_key=True)
+    id: int = Field(default=None, primary_key=True)
     user_id: int = Field(sa_column=Column(BigInteger, ForeignKey("lazer_users.id"), nullable=False, index=True))
-    token_id: int | None = Field(
-        sa_column=Column(Integer, ForeignKey("oauth_tokens.id", ondelete="SET NULL"), nullable=True, index=True)
-    )
-    ip_address: str = Field()  # 登录IP
-    user_agent: str | None = Field(default=None, max_length=250)
-    country_code: str | None = Field(default=None)
+    ip_address: str = Field(sa_column=Column(VARCHAR(45), nullable=False), default="127.0.0.1", exclude=True)
+    user_agent: str | None = Field(default=None, sa_column=Column(Text))
     is_verified: bool = Field(default=False)  # 是否已验证
     created_at: datetime = Field(default_factory=lambda: utcnow())
     verified_at: datetime | None = Field(default=None)
     expires_at: datetime = Field()  # 会话过期时间
-    is_new_location: bool = Field(default=False)  # 是否新位置登录
-    session_token: str | None = Field(default=None, max_length=64, index=True)  # 会话令牌
-    verification_method: str | None = Field(default=None, max_length=20)  # 验证方法 (totp/mail)
+    device_id: int | None = Field(
+        sa_column=Column(BigInteger, ForeignKey("trusted_devices.id", ondelete="SET NULL"), nullable=True, index=True),
+        default=None,
+    )
 
+
+class LoginSession(LoginSessionBase, table=True):
+    __tablename__: str = "login_sessions"
+    token_id: int | None = Field(
+        sa_column=Column(Integer, ForeignKey("oauth_tokens.id", ondelete="SET NULL"), nullable=True, index=True),
+        exclude=True,
+    )
+    is_new_device: bool = Field(default=False, exclude=True)  # 是否新位置登录
+    web_uuid: str | None = Field(sa_column=Column(VARCHAR(36), nullable=True), default=None, exclude=True)
+    verification_method: str | None = Field(default=None, max_length=20, exclude=True)  # 验证方法 (totp/mail)
+
+    device: Optional["TrustedDevice"] = Relationship(back_populates="sessions")
     token: Optional["OAuthToken"] = Relationship(back_populates="login_session")
+
+
+class LoginSessionResp(UTCBaseModel, LoginSessionBase):
+    user_agent_info: UserAgentInfo | None = None
+    location: Location | None = None
+
+    @classmethod
+    def from_db(cls, obj: LoginSession, get_geoip_helper: GeoIPHelper) -> "LoginSessionResp":
+        session = cls.model_validate(obj.model_dump())
+        session.user_agent_info = extract_user_agent(session.user_agent)
+        if obj.ip_address:
+            loc = get_geoip_helper.lookup(obj.ip_address)
+            session.location = Location(
+                country=loc.get("country_name", ""),
+                city=loc.get("city_name", ""),
+                country_code=loc.get("country_code", ""),
+            )
+        else:
+            session.location = None
+        return session
+
+
+class TrustedDeviceBase(SQLModel):
+    id: int = Field(default=None, primary_key=True)
+    user_id: int = Field(sa_column=Column(BigInteger, ForeignKey("lazer_users.id"), nullable=False, index=True))
+    ip_address: str = Field(sa_column=Column(VARCHAR(45), nullable=False), default="127.0.0.1", exclude=True)
+    user_agent: str = Field(sa_column=Column(Text, nullable=False))
+    client_type: Literal["web", "client"] = Field(sa_column=Column(VARCHAR(10), nullable=False), default="web")
+    created_at: datetime = Field(default_factory=utcnow)
+    last_used_at: datetime = Field(default_factory=utcnow)
+    expires_at: datetime = Field(sa_column=Column(DateTime))
+
+
+class TrustedDevice(TrustedDeviceBase, table=True):
+    __tablename__: str = "trusted_devices"
+    web_uuid: str | None = Field(sa_column=Column(VARCHAR(36), nullable=True), default=None)
+
+    sessions: list["LoginSession"] = Relationship(back_populates="device", passive_deletes=True)
+
+
+class TrustedDeviceResp(UTCBaseModel, TrustedDeviceBase):
+    user_agent_info: UserAgentInfo | None = None
+    location: Location | None = None
+
+    @classmethod
+    def from_db(cls, device: TrustedDevice, get_geoip_helper: GeoIPHelper) -> "TrustedDeviceResp":
+        device_ = cls.model_validate(device.model_dump())
+        device_.user_agent_info = extract_user_agent(device_.user_agent)
+        if device_.ip_address:
+            loc = get_geoip_helper.lookup(device_.ip_address)
+            device_.location = Location(
+                country=loc.get("country_name", ""),
+                city=loc.get("city_name", ""),
+                country_code=loc.get("country_code", ""),
+            )
+        else:
+            device_.location = None
+        return device_