04 session security and kickout

会话安全与踢出（强制下线）

LIMIS 使用 JWT 访问接口，并通过 会话版本号 session_version 与 Token 中的声明 sv 对齐，实现「单点踢出」与「登录后旧 Token 作废」。

1. 机制说明

组件	路径	作用
用户字段	User.session_version	backend/apps/system/models.py
Access Token	SessionVersionAccessToken，claim sv	backend/apps/system/tokens.py
认证	校验 sv 与数据库一致	backend/apps/system/authentication.py → SessionVersionJWTAuthentication
刷新	SessionVersionTokenRefreshSerializer	backend/apps/system/jwt_serializers.py（如存在）
登录递增	bump_session_version	backend/apps/system/services.py → authenticate_user

成功登录时：会对 session_version 自增（bump_session_version），使该用户此前签发的 access/refresh 在校验 sv 时失败（InvalidToken 会话已失效）。

管理员踢出：POST /api/v1/system/users/{id}/kickout-sessions/ 对 session_version 做 F('session_version') + 1（backend/apps/system/views.py → kickout_sessions）。

2. 文字流程图：请求鉴权

客户端携带 Authorization: Bearer <access>
    ↓
SessionVersionJWTAuthentication 解析 JWT
    ↓
取出 claim sv
    ↓
与 User.session_version 比较
    ├─ 一致 → 通过
    └─ 不一致 → InvalidToken「会话已失效，请重新登录」

3. 文字流程图：踢出用户

[管理员] 用户管理 → 选择用户 → 踢出会话（kickout-sessions）
    ↓
DB: session_version += 1
    ↓
该用户所有设备上旧 JWT 立即失效
    ↓
用户需重新登录（新 Token 带新 sv）

4. 配置项（JWT）

配置	位置	默认值（参考）
ACCESS_TOKEN_LIFETIME	backend/limis/settings/base.py → SIMPLE_JWT	2 小时
REFRESH_TOKEN_LIFETIME	同上	7 天
ROTATE_REFRESH_TOKENS / BLACKLIST_AFTER_ROTATION	同上	True

刷新端点：POST /api/v1/system/token/refresh/（backend/apps/system/urls.py）。

5. 前端行为

• Token 存于 localStorage（frontend/src/utils/auth.ts）。
• 401/刷新失败时 userStore.resetState() 清空并跳转登录（见 stores/user.ts）。

6. 风险与回滚

风险	说明	建议
误踢大量用户	若脚本错误批量 session_version++	从备份恢复 users 表该字段；或通知全员重登
sv 缺失	旧 Token 无 sv	认证层会抛「缺少会话版本信息」→ 用户重新登录
时钟不同步	一般不影响 sv；影响 JWT exp	NTP 同步

回滚：通常不需要回滚代码；数据层可将某用户 session_version 设回旧值（仅当仍持有对应旧 JWT 且需紧急恢复会话时，安全风险高，一般禁止）。

7. 与审计的关系

踢出、登录、改密等操作应结合 AuditLog 与业务日志查看（06-audit-log-operations.md）。

8. 相关代码路径

• backend/apps/system/authentication.py
• backend/apps/system/tokens.py
• backend/apps/system/services.py（authenticate_user、bump_session_version）
• backend/apps/system/views.py（kickout_sessions、LoginView）