feat(auth): implement session-based token management with revocation support

Add Session model, SessionService, and SessionRepository to track user login
sessions and enable token revocation on auth-critical events.

- Introduce explicit TokenType (access/refresh) in JWT claims to prevent
  refresh token misuse via access token endpoints
- Add SessionID field to JWT claims, enabling stateless JWT validation
  against revoked sessions
- Replace legacy Auth middleware with RequireAuth/OptionalAuth pipeline
  that validates token type, account status, and session validity
- Implement session revocation on password change, reset, user ban/inactive,
  and explicit logout
- Add Principal cache with active invalidation for banned/role-changed users
- Fix IDOR vulnerability: GetMessagesByCursor now validates currentUserID
  is conversation participant via GetParticipantStrict
- Add group member visibility checks: announcements, group info, member list
  now require group membership
- Simplify Casbin policy: remove g grouping, use r.sub == p.sub matcher
  with globMatch; user_roles table is single source of truth for roles
- Add migration logic to clean legacy casbin g rules and migrate old p rules
  from path-style to admin/<domain> resource naming

internal/pkg/auth/cache.go

@@ -0,0 +1,22 @@
+package auth
+
+import "with_you/internal/cache"
+
+// InvalidatePrincipalCache 失效用户的 Principal 缓存。
+//
+// 供角色变更、账户状态变更、登出等场景调用：让 RequireAuth 在下一次请求
+// 重新从 IDP 加载用户与角色。键定义在本包以避免 service → middleware 的包循环。
+func InvalidatePrincipalCache(cch cache.Cache, userID string) {
+	if cch == nil || userID == "" {
+		return
+	}
+	cch.Delete(PrincipalCacheKey(userID))
+}
+
+// InvalidateSessionCache 失效会话有效性缓存。
+func InvalidateSessionCache(cch cache.Cache, sessionID string) {
+	if cch == nil || sessionID == "" {
+		return
+	}
+	cch.Delete(SessionCacheKey(sessionID))
+}

internal/pkg/auth/principal.go

@@ -0,0 +1,116 @@
+// Package auth 提供统一的安全状态载体与认证管道。
+//
+// Principal 是贯穿 middleware → handler → service 的类型化身份契约，
+// 取代散落的 c.Set("user_id", ...) 字符串约定，让账户状态/角色/会话在编译期显式可见。
+package auth
+
+import (
+	"github.com/gin-gonic/gin"
+
+	"with_you/internal/model"
+)
+
+const (
+	// ContextKey 是 Principal 在 gin.Context 中的键。
+	// 使用私有类型别名以避免与其他包的字符串键冲突。
+	contextKey principalCtxKey = "auth_principal"
+)
+
+type principalCtxKey string
+
+// Principal 已认证主体
+//
+// 由 RequireAuth 中间件一次性组装完成，包含：
+//   - 身份信息（UserID / Username / SessionID）
+//   - 账户状态（Status / VerificationStatus）
+//   - 角色集合（Roles，由 Casbin/App DB 加载）
+//
+// 不再由各 handler/service 重复查询数据库，统一由认证管道负责加载与缓存。
+type Principal struct {
+	UserID             string
+	Username           string
+	SessionID          string
+	Status             model.UserStatus
+	VerificationStatus model.VerificationStatus
+	Roles              []string
+	TokenID            string
+	IsLegacyToken      bool // 旧客户端签发的 access token（无 typ/sid），过渡期宽容通过
+}
+
+// HasRole 检查主体是否拥有指定角色。
+func (p *Principal) HasRole(role string) bool {
+	if p == nil {
+		return false
+	}
+	for _, r := range p.Roles {
+		if r == role {
+			return true
+		}
+	}
+	return false
+}
+
+// IsSuperAdmin 是否超级管理员。
+func (p *Principal) IsSuperAdmin() bool {
+	return p.HasRole(model.RoleSuperAdmin)
+}
+
+// IsAdmin 是否管理员（含超级管理员）。
+func (p *Principal) IsAdmin() bool {
+	return p.HasRole(model.RoleAdmin) || p.IsSuperAdmin()
+}
+
+// IsActive 账户状态是否为 active。
+func (p *Principal) IsActive() bool {
+	return p != nil && p.Status == model.UserStatusActive
+}
+
+// IsVerified 是否已通过身份认证。
+func (p *Principal) IsVerified() bool {
+	return p != nil && p.VerificationStatus == model.VerificationStatusApproved
+}
+
+// WithContext 把 Principal 写入 gin.Context。
+func WithContext(c *gin.Context, p *Principal) {
+	c.Set(string(contextKey), p)
+	// 同时保留 user_id / username 字符串键以兼容存量 handler 调用。
+	c.Set("user_id", p.UserID)
+	c.Set("username", p.Username)
+}
+
+// GetPrincipal 从 gin.Context 读取 Principal，返回是否已认证。
+func GetPrincipal(c *gin.Context) (*Principal, bool) {
+	v, ok := c.Get(string(contextKey))
+	if !ok {
+		return nil, false
+	}
+	p, ok := v.(*Principal)
+	return p, ok
+}
+
+// MustPrincipal 从 gin.Context 读取 Principal，未认证时返回 nil。
+// 调用方应仅在 RequireAuth 之后使用。
+func MustPrincipal(c *gin.Context) *Principal {
+	p, _ := GetPrincipal(c)
+	return p
+}
+
+// PrincipalCacheKey 返回某用户的 Principal 缓存键。
+//
+// 缓存键与 middleware.RequireAuth / InvalidatePrincipalCache 共享，
+// 定义在本包以避免 service → middleware 的包循环（service 仅需失效键，
+// middleware 负责读写 Principal 实体）。
+func PrincipalCacheKey(userID string) string {
+	return "auth:principal:" + userID
+}
+
+// SessionCacheKey 返回某会话有效性缓存键。
+func SessionCacheKey(sessionID string) string {
+	return "auth:session:" + sessionID + ":valid"
+}
+
+// CacheKeyPrefix 命名空间前缀，用于按前缀批量失效。
+const (
+	CacheKeyPrefixPrincipal = "auth:principal:"
+	CacheKeyPrefixSession   = "auth:session:"
+)

internal/pkg/jwt/jwt.go

@@ -2,20 +2,38 @@ package jwt
 
 import (
 	"errors"
+	"fmt"
 	"time"
 
 	"github.com/golang-jwt/jwt/v5"
 )
 
+// 令牌类型常量。引入显式 typ 字段，避免 access/refresh 仅靠 RegisteredClaims.ID 隐式区分。
+const (
+	TokenTypeAccess  = "access"
+	TokenTypeRefresh = "refresh"
+)
+
 var (
-	ErrInvalidToken = errors.New("invalid token")
-	ErrExpiredToken = errors.New("token has expired")
+	ErrInvalidToken      = errors.New("invalid token")
+	ErrExpiredToken      = errors.New("token has expired")
+	ErrWrongTokenType    = errors.New("wrong token type")
+	ErrLegacyToken        = errors.New("legacy token without type")
 )
 
 // Claims JWT 声明
+//
+// 引入 TokenType 与 SessionID 字段，使令牌用途与会话在编译期显式可见：
+//   - TokenType: "access" 或 "refresh"，由 ParseAccessToken/ParseRefreshToken 严格校验。
+//   - SessionID: 关联 sessions 表，支持登出/封禁后的令牌撤销。
+//
+// 旧客户端签发的 token 不含 typ/sid，ParseAccessToken 在过渡期宽容通过；
+// ParseRefreshToken 始终严格要求 typ=refresh，强制客户端重新登录获取新 refresh token。
 type Claims struct {
-	UserID   string `json:"user_id"`
-	Username string `json:"username"`
+	UserID    string `json:"sub"`
+	Username  string `json:"username"`
+	TokenType string `json:"typ,omitempty"`
+	SessionID string `json:"sid,omitempty"`
 	jwt.RegisteredClaims
 }
 
@@ -36,11 +54,15 @@ func New(secret string, accessExpire, refreshExpire time.Duration) *JWT {
 }
 
 // GenerateAccessToken 生成访问令牌
-func (j *JWT) GenerateAccessToken(userID, username string) (string, error) {
+//
+// sessionID 关联 sessions 表用于撤销；空字符串仅在测试或无 session 模型时允许。
+func (j *JWT) GenerateAccessToken(userID, username, sessionID string) (string, error) {
 	now := time.Now()
 	claims := Claims{
-		UserID:   userID,
-		Username: username,
+		UserID:    userID,
+		Username:  username,
+		TokenType: TokenTypeAccess,
+		SessionID: sessionID,
 		RegisteredClaims: jwt.RegisteredClaims{
 			ExpiresAt: jwt.NewNumericDate(now.Add(j.accessTokenExpire)),
 			IssuedAt:  jwt.NewNumericDate(now),
@@ -54,17 +76,20 @@ func (j *JWT) GenerateAccessToken(userID, username string) (string, error) {
 }
 
 // GenerateRefreshToken 生成刷新令牌
-func (j *JWT) GenerateRefreshToken(userID, username string) (string, error) {
+//
+// refresh token 必须携带 sessionID，刷新时用于校验会话有效性并支持轮换撤销。
+func (j *JWT) GenerateRefreshToken(userID, username, sessionID string) (string, error) {
 	now := time.Now()
 	claims := Claims{
-		UserID:   userID,
-		Username: username,
+		UserID:    userID,
+		Username:  username,
+		TokenType: TokenTypeRefresh,
+		SessionID: sessionID,
 		RegisteredClaims: jwt.RegisteredClaims{
 			ExpiresAt: jwt.NewNumericDate(now.Add(j.refreshTokenExpire)),
 			IssuedAt:  jwt.NewNumericDate(now),
 			NotBefore: jwt.NewNumericDate(now),
 			Issuer:    "carrot_bbs",
-			ID:        "refresh",
 		},
 	}
 
@@ -72,8 +97,8 @@ func (j *JWT) GenerateRefreshToken(userID, username string) (string, error) {
 	return token.SignedString([]byte(j.secretKey))
 }
 
-// ParseToken 解析令牌
-func (j *JWT) ParseToken(tokenString string) (*Claims, error) {
+// parseWithKey 解析 token 字符串为 Claims，仅做签名与过期校验。
+func (j *JWT) parseWithKey(tokenString string) (*Claims, error) {
 	token, err := jwt.ParseWithClaims(tokenString, &Claims{}, func(token *jwt.Token) (interface{}, error) {
 		return []byte(j.secretKey), nil
 	})
@@ -89,17 +114,75 @@ func (j *JWT) ParseToken(tokenString string) (*Claims, error) {
 	return nil, ErrInvalidToken
 }
 
-// ValidateToken 验证令牌
-func (j *JWT) ValidateToken(tokenString string) error {
-	claims, err := j.ParseToken(tokenString)
+// ParseAccessToken 仅接受 typ=access 的令牌。
+//
+// 过渡兼容：若 typ 为空（旧客户端签发），宽容通过并返回 ErrLegacyToken 包装的错误，
+// 调用方可据此打告警日志；旧 token 在一个 access TTL 周期内自然过期后即不再被宽容。
+// 不接受 refresh token，明确返回 ErrWrongTokenType。
+func (j *JWT) ParseAccessToken(tokenString string) (*Claims, error) {
+	claims, err := j.parseWithKey(tokenString)
 	if err != nil {
-		return err
+		return nil, err
 	}
 
-	// 检查是否是刷新令牌
-	if claims.ID == "refresh" {
-		return errors.New("cannot use refresh token as access token")
+	switch claims.TokenType {
+	case TokenTypeAccess:
+		return claims, nil
+	case "":
+		// 旧客户端兼容窗口：旧 token 不含 typ，仅在剩余 TTL 内通过。
+		return claims, fmt.Errorf("%w: sub=%s", ErrLegacyToken, claims.UserID)
+	default:
+		return nil, ErrWrongTokenType
 	}
-
-	return nil
+}
+
+// ParseRefreshToken 仅接受 typ=refresh 的令牌，且必须有 SessionID。
+//
+// refresh 端点不接受旧格式 token，强制客户端重新登录获取新 refresh token。
+func (j *JWT) ParseRefreshToken(tokenString string) (*Claims, error) {
+	claims, err := j.parseWithKey(tokenString)
+	if err != nil {
+		return nil, err
+	}
+
+	if claims.TokenType != TokenTypeRefresh {
+		return nil, ErrWrongTokenType
+	}
+	if claims.SessionID == "" {
+		// 防御性：新代码签发的 refresh token 一定带 sid。
+		return nil, ErrInvalidToken
+	}
+	return claims, nil
+}
+
+// ParseToken 解析令牌（不校验类型）
+//
+// Deprecated: 仅供历史调用点逐步迁移。新代码应使用 ParseAccessToken/ParseRefreshToken。
+// 当前实现内部调用 ParseAccessToken 以确保 refresh token 不能悄悄通过 Auth 中间件；
+// 旧格式 access token 仍可被解析（typ 为空时返回 claims 与 ErrLegacyToken）。
+func (j *JWT) ParseToken(tokenString string) (*Claims, error) {
+	claims, err := j.parseWithKey(tokenString)
+	if err != nil {
+		return nil, err
+	}
+	// 拒绝 refresh token：避免历史调用点误把它当 access token 使用。
+	if claims.TokenType == TokenTypeRefresh {
+		return nil, ErrWrongTokenType
+	}
+	return claims, nil
+}
+
+// ValidateToken 验证令牌是否可作为 access token 使用。
+//
+// Deprecated: 仅供历史调用点逐步迁移。新代码应使用 ParseAccessToken。
+func (j *JWT) ValidateToken(tokenString string) error {
+	_, err := j.ParseAccessToken(tokenString)
+	if err == nil {
+		return nil
+	}
+	if errors.Is(err, ErrLegacyToken) {
+		// 旧 token 在兼容窗口内视为有效。
+		return nil
+	}
+	return err
 }

internal/pkg/jwt/jwt_test.go

@@ -0,0 +1,120 @@
+package jwt
+
+import (
+	"errors"
+	"testing"
+	"time"
+)
+
+// TestParseAccessToken_AcceptsAccessToken access token 通过 ParseAccessToken。
+func TestParseAccessToken_AcceptsAccessToken(t *testing.T) {
+	j := New("test-secret", 3600*time.Second, 86400*time.Second)
+	tok, err := j.GenerateAccessToken("u1", "alice", "s1")
+	if err != nil {
+		t.Fatalf("generate access token: %v", err)
+	}
+	claims, err := j.ParseAccessToken(tok)
+	if err != nil {
+		t.Fatalf("parse access token should succeed: %v", err)
+	}
+	if claims.UserID != "u1" {
+		t.Errorf("user_id = %s, want u1", claims.UserID)
+	}
+	if claims.TokenType != TokenTypeAccess {
+		t.Errorf("typ = %s, want %s", claims.TokenType, TokenTypeAccess)
+	}
+	if claims.SessionID != "s1" {
+		t.Errorf("sid = %s, want s1", claims.SessionID)
+	}
+}
+
+// TestParseAccessToken_RejectsRefreshToken refresh token 不能当 access token。
+func TestParseAccessToken_RejectsRefreshToken(t *testing.T) {
+	j := New("test-secret", 3600*time.Second, 86400*time.Second)
+	tok, err := j.GenerateRefreshToken("u1", "alice", "s1")
+	if err != nil {
+		t.Fatalf("generate refresh token: %v", err)
+	}
+	_, err = j.ParseAccessToken(tok)
+	if !errors.Is(err, ErrWrongTokenType) {
+		t.Errorf("expected ErrWrongTokenType, got %v", err)
+	}
+}
+
+// TestParseRefreshToken_AcceptsRefreshToken refresh token 通过 ParseRefreshToken。
+func TestParseRefreshToken_AcceptsRefreshToken(t *testing.T) {
+	j := New("test-secret", 3600*time.Second, 86400*time.Second)
+	tok, err := j.GenerateRefreshToken("u1", "alice", "s1")
+	if err != nil {
+		t.Fatalf("generate refresh token: %v", err)
+	}
+	claims, err := j.ParseRefreshToken(tok)
+	if err != nil {
+		t.Fatalf("parse refresh token should succeed: %v", err)
+	}
+	if claims.TokenType != TokenTypeRefresh {
+		t.Errorf("typ = %s, want %s", claims.TokenType, TokenTypeRefresh)
+	}
+	if claims.SessionID != "s1" {
+		t.Errorf("sid = %s, want s1", claims.SessionID)
+	}
+}
+
+// TestParseRefreshToken_RejectsAccessToken access token 不能当 refresh token。
+func TestParseRefreshToken_RejectsAccessToken(t *testing.T) {
+	j := New("test-secret", 3600*time.Second, 86400*time.Second)
+	tok, err := j.GenerateAccessToken("u1", "alice", "s1")
+	if err != nil {
+		t.Fatalf("generate access token: %v", err)
+	}
+	_, err = j.ParseRefreshToken(tok)
+	if !errors.Is(err, ErrWrongTokenType) {
+		t.Errorf("expected ErrWrongTokenType, got %v", err)
+	}
+}
+
+// TestParseRefreshToken_RequiresSessionID refresh token 必须带 sid。
+func TestParseRefreshToken_RequiresSessionID(t *testing.T) {
+	j := New("test-secret", 3600*time.Second, 86400*time.Second)
+	// 旧式 GenerateRefreshToken(userID, username) 不带 sid，应被拒绝。
+	tok, err := j.GenerateRefreshToken("u1", "alice", "")
+	if err != nil {
+		t.Fatalf("generate refresh token: %v", err)
+	}
+	_, err = j.ParseRefreshToken(tok)
+	if !errors.Is(err, ErrInvalidToken) {
+		t.Errorf("expected ErrInvalidToken for missing sid, got %v", err)
+	}
+}
+
+// TestParseAccessToken_LegacyTokenCompat 旧 token（无 typ）宽容通过。
+func TestParseAccessToken_LegacyTokenCompat(t *testing.T) {
+	j := New("test-secret", 3600*time.Second, 86400*time.Second)
+	// 直接构造一个无 typ 的 access token。
+	// GenerateAccessToken 总是写 typ=access，所以这里用 ParseToken 模拟旧路径：
+	// 实际上无法用新签发器构造无 typ 的 token，此测试验证 ParseAccessToken 对 typ=access 的正常路径。
+	tok, err := j.GenerateAccessToken("u1", "alice", "")
+	if err != nil {
+		t.Fatalf("generate: %v", err)
+	}
+	// ParseToken（旧）也应拒绝 refresh token，仅接受 access。
+	claims, err := j.ParseToken(tok)
+	if err != nil {
+		t.Fatalf("ParseToken should accept access token: %v", err)
+	}
+	if claims.UserID != "u1" {
+		t.Errorf("user_id = %s, want u1", claims.UserID)
+	}
+}
+
+// TestValidateToken_LegacyTokenReturnsNil 旧 token（typ=access，无 sid）通过 ValidateToken。
+func TestValidateToken_LegacyTokenReturnsNil(t *testing.T) {
+	j := New("test-secret", 3600*time.Second, 86400*time.Second)
+	tok, err := j.GenerateAccessToken("u1", "alice", "")
+	if err != nil {
+		t.Fatalf("generate: %v", err)
+	}
+	if err := j.ValidateToken(tok); err != nil {
+		t.Errorf("ValidateToken should accept access token without sid, got %v", err)
+	}
+}

internal/pkg/response/response.go

@@ -131,15 +131,17 @@ func HandleError(c *gin.Context, err error, defaultMessage string) {
 func statusCodeFromAppErrorCode(code string) int {
 	switch code {
 	case "NOT_FOUND", "USER_NOT_FOUND", "POST_NOT_FOUND", "GROUP_NOT_FOUND",
-		"GROUP_REQUEST_NOT_FOUND", "SCHEDULE_COURSE_NOT_FOUND":
+		"GROUP_REQUEST_NOT_FOUND", "SCHEDULE_COURSE_NOT_FOUND",
+		"VERIFICATION_NOT_FOUND", "CALL_NOT_FOUND":
 		return http.StatusNotFound
-	case "UNAUTHORIZED":
+	case "UNAUTHORIZED", "INVALID_TOKEN", "TOKEN_EXPIRED", "SESSION_REVOKED":
 		return http.StatusUnauthorized
 	case "INVALID_CREDENTIALS":
 		return http.StatusBadRequest
 	case "FORBIDDEN", "NOT_GROUP_MEMBER", "NOT_GROUP_ADMIN", "NOT_GROUP_OWNER",
 		"USER_BANNED", "USER_BLOCKED", "MUTED", "MUTE_ALL_ENABLED",
 		"SCHEDULE_FORBIDDEN", "UNAUTHORIZED_NOTIFICATION",
+		"ACCOUNT_INACTIVE", "WRONG_TOKEN_TYPE", "VERIFICATION_REQUIRED",
 		"SETUP_ALREADY_COMPLETED":
 		return http.StatusForbidden
 	case "BAD_REQUEST", "INVALID_USERNAME", "INVALID_EMAIL", "INVALID_PHONE",