feat(jwt): server-side session table with keyId + obfuscated uid claims

Replace the {user_id, ip} claim pair with {keyId, uid}:
- keyId is a 32-byte random id that points to a row in the new
  jwt_sessions table holding the real user id, bound IP, UA hash,
  TokenVersion and expiry.
- uid is the user id encoded through pkg/idcodec; mismatch between
  claim uid and session.UserID trips WAF block on the caller IP.
- identityHandler now rejects unknown/revoked/expired sessions, IP
  drift and stale TokenVersion. Refresh updates session.ExpiresAt.

User.TokenVersion bumps on password change and revokes outstanding
sessions, so a leaked JWT secret alone is no longer enough to forge
a token. JWTSession rows are GC'd every 10 minutes (expired + grace
or revoked >24h). OAuth2 callback shares the same issue path.

Includes regression tests for happy path, mismatched claim uid,
revoked session, TokenVersion bump, IP drift and unknown keyId.

Co-authored-by: cloudcode <cloudcode@users.noreply.github.com>

cmd/dashboard/controller/jwt.go

@@ -1,6 +1,8 @@
 package controller
 
 import (
+	"crypto/sha256"
+	"encoding/hex"
 	"net/http"
 	"time"
 
@@ -12,10 +14,51 @@ import (
 
 	"github.com/nezhahq/nezha/cmd/dashboard/controller/waf"
 	"github.com/nezhahq/nezha/model"
+	"github.com/nezhahq/nezha/pkg/idcodec"
 	"github.com/nezhahq/nezha/pkg/utils"
 	"github.com/nezhahq/nezha/service/singleton"
 )
 
+const (
+	jwtClaimUserID = "uid"
+	jwtClaimKeyID  = "keyId"
+	jwtKeyIDBytes  = 32
+)
+
+func uaHash(c *gin.Context) string {
+	sum := sha256.Sum256([]byte(c.Request.UserAgent()))
+	return hex.EncodeToString(sum[:])
+}
+
+func issueJWTSession(c *gin.Context, user *model.User, jwtTimeoutHours int) (map[string]interface{}, error) {
+	keyID, err := utils.GenerateRandomString(jwtKeyIDBytes)
+	if err != nil {
+		return nil, err
+	}
+	hashUID, err := idcodec.Encode(user.ID)
+	if err != nil {
+		return nil, err
+	}
+	now := time.Now()
+	sess := model.JWTSession{
+		KeyID:        keyID,
+		UserID:       user.ID,
+		IP:           c.GetString(model.CtxKeyRealIPStr),
+		UAHash:       uaHash(c),
+		TokenVersion: user.TokenVersion,
+		ExpiresAt:    now.Add(time.Hour * time.Duration(jwtTimeoutHours)),
+		CreatedAt:    now,
+		LastUsedAt:   now,
+	}
+	if err := singleton.DB.Create(&sess).Error; err != nil {
+		return nil, err
+	}
+	return map[string]interface{}{
+		jwtClaimUserID: hashUID,
+		jwtClaimKeyID:  keyID,
+	}, nil
+}
+
 func initParams() *jwt.GinJWTMiddleware {
 	return &jwt.GinJWTMiddleware{
 		Realm:       singleton.Conf.SiteName,
@@ -73,28 +116,56 @@ func identityHandler() func(c *gin.Context) any {
 	return func(c *gin.Context) any {
 		claims := jwt.ExtractClaims(c)
 
-		userId, ok := claims["user_id"].(string)
-		if !ok {
+		keyID, ok := claims[jwtClaimKeyID].(string)
+		if !ok || keyID == "" {
+			return nil
+		}
+		hashUID, ok := claims[jwtClaimUserID].(string)
+		if !ok || hashUID == "" {
+			return nil
+		}
+		claimUID, err := idcodec.Decode(hashUID)
+		if err != nil {
+			realIP := c.GetString(model.CtxKeyRealIPStr)
+			model.BlockIP(singleton.DB, realIP, model.WAFBlockReasonTypeBruteForceToken, model.BlockIDToken)
 			return nil
 		}
 
-		tokenIP, ok := claims["ip"].(string)
-		if !ok {
+		var sess model.JWTSession
+		if err := singleton.DB.First(&sess, "key_id = ?", keyID).Error; err != nil {
+			return nil
+		}
+		if sess.RevokedAt != nil {
+			return nil
+		}
+		now := time.Now()
+		if now.After(sess.ExpiresAt) {
+			return nil
+		}
+		if claimUID != sess.UserID {
+			realIP := c.GetString(model.CtxKeyRealIPStr)
+			model.BlockIP(singleton.DB, realIP, model.WAFBlockReasonTypeBruteForceToken, model.BlockIDToken)
 			return nil
 		}
-
 		currentIP := c.GetString(model.CtxKeyRealIPStr)
-
-		if tokenIP != currentIP {
-			// IP地址不匹配，token无效
+		if sess.IP != currentIP {
 			c.Set(model.CtxKeyIsIPMismatch, true)
 			return nil
 		}
 
 		var user model.User
-		if err := singleton.DB.First(&user, userId).Error; err != nil {
+		if err := singleton.DB.First(&user, sess.UserID).Error; err != nil {
 			return nil
 		}
+		if user.TokenVersion != sess.TokenVersion {
+			return nil
+		}
+
+		_ = singleton.DB.Model(&model.JWTSession{}).
+			Where("key_id = ?", keyID).
+			Update("last_used_at", now).Error
+
+		c.Set(jwtClaimKeyID, keyID)
 		return &user
 	}
 }
@@ -118,7 +189,7 @@ func authenticator() func(c *gin.Context) (any, error) {
 		var user model.User
 		realip := c.GetString(model.CtxKeyRealIPStr)
 
-		if err := singleton.DB.Select("id", "password", "reject_password").Where("username = ?", loginVals.Username).First(&user).Error; err != nil {
+		if err := singleton.DB.Select("id", "password", "reject_password", "token_version").Where("username = ?", loginVals.Username).First(&user).Error; err != nil {
 			if err == gorm.ErrRecordNotFound {
 				model.BlockIP(singleton.DB, realip, model.WAFBlockReasonTypeLoginFail, model.BlockIDUnknownUser)
 			}
@@ -138,11 +209,7 @@ func authenticator() func(c *gin.Context) (any, error) {
 		model.UnblockIP(singleton.DB, realip, model.BlockIDUnknownUser)
 		model.UnblockIP(singleton.DB, realip, int64(user.ID))
 
-		// 返回用户ID和IP地址的组合，用于在payloadFunc中设置JWT claims
-		return map[string]interface{}{
-			"user_id": utils.Itoa(user.ID),
-			"ip":      realip,
-		}, nil
+		return issueJWTSession(c, &user, singleton.Conf.JWTTimeout)
 	}
 }
 
@@ -172,6 +239,14 @@ func unauthorized() func(c *gin.Context, code int, message string) {
 // @Success 200 {object} model.CommonResponse[model.LoginResponse]
 // @Router /refresh-token [get]
 func refreshResponse(c *gin.Context, code int, token string, expire time.Time) {
+	if keyID := c.GetString(jwtClaimKeyID); keyID != "" {
+		_ = singleton.DB.Model(&model.JWTSession{}).
+			Where("key_id = ?", keyID).
+			Updates(map[string]interface{}{
+				"expires_at":   expire,
+				"last_used_at": time.Now(),
+			}).Error
+	}
 	c.JSON(http.StatusOK, model.CommonResponse[model.LoginResponse]{
 		Success: true,
 		Data: model.LoginResponse{

cmd/dashboard/controller/jwt_session_test.go

@@ -0,0 +1,246 @@
+package controller
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	jwt "github.com/appleboy/gin-jwt/v2"
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"golang.org/x/crypto/bcrypt"
+	"gorm.io/driver/sqlite"
+	"gorm.io/gorm"
+
+	"github.com/nezhahq/nezha/model"
+	"github.com/nezhahq/nezha/pkg/idcodec"
+	"github.com/nezhahq/nezha/service/singleton"
+)
+
+const jwtSessionTestMasterKey = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+
+func setupJWTSessionTest(t *testing.T) (cleanup func()) {
+	t.Helper()
+	require.NoError(t, idcodec.Init([]byte(jwtSessionTestMasterKey)))
+
+	originalDB := singleton.DB
+	originalConf := singleton.Conf
+	db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
+	require.NoError(t, err)
+	require.NoError(t, db.AutoMigrate(&model.User{}, &model.JWTSession{}, &model.WAF{}))
+	singleton.DB = db
+	singleton.Conf = &singleton.ConfigClass{Config: &model.Config{JWTTimeout: 1}}
+
+	require.NoError(t, db.Create(&model.User{
+		Common:       model.Common{ID: 100},
+		Username:     "victim",
+		Role:         model.RoleMember,
+		TokenVersion: 7,
+	}).Error)
+
+	return func() {
+		singleton.DB = originalDB
+		singleton.Conf = originalConf
+	}
+}
+
+func newCtxForUser(userID uint64, ip, ua string) *gin.Context {
+	gin.SetMode(gin.TestMode)
+	ctx, _ := gin.CreateTestContext(httptest.NewRecorder())
+	ctx.Request = httptest.NewRequest("GET", "/", nil)
+	ctx.Request.Header.Set("User-Agent", ua)
+	ctx.Set(model.CtxKeyRealIPStr, ip)
+	if userID != 0 {
+		ctx.Set(model.CtxKeyAuthorizedUser, &model.User{Common: model.Common{ID: userID}})
+	}
+	return ctx
+}
+
+func TestIssueJWTSessionWritesRow(t *testing.T) {
+	cleanup := setupJWTSessionTest(t)
+	defer cleanup()
+
+	ctx := newCtxForUser(0, "1.2.3.4", "test-ua")
+	user := model.User{Common: model.Common{ID: 100}, TokenVersion: 7}
+	claims, err := issueJWTSession(ctx, &user, 1)
+	require.NoError(t, err)
+
+	hashUID, _ := claims[jwtClaimUserID].(string)
+	keyID, _ := claims[jwtClaimKeyID].(string)
+	assert.NotEqual(t, "100", hashUID, "uid claim must be obfuscated, not raw integer")
+	got, err := idcodec.Decode(hashUID)
+	require.NoError(t, err)
+	assert.Equal(t, uint64(100), got)
+
+	var sess model.JWTSession
+	require.NoError(t, singleton.DB.First(&sess, "key_id = ?", keyID).Error)
+	assert.Equal(t, uint64(100), sess.UserID)
+	assert.Equal(t, "1.2.3.4", sess.IP)
+	assert.Equal(t, uint64(7), sess.TokenVersion)
+	assert.True(t, sess.ExpiresAt.After(time.Now()))
+}
+
+func TestIdentityHandlerHappyPath(t *testing.T) {
+	cleanup := setupJWTSessionTest(t)
+	defer cleanup()
+
+	ctx := newCtxForUser(0, "1.2.3.4", "ua")
+	user := model.User{Common: model.Common{ID: 100}, TokenVersion: 7}
+	claims, err := issueJWTSession(ctx, &user, 1)
+	require.NoError(t, err)
+
+	verify := newCtxForUser(0, "1.2.3.4", "ua")
+	verify.Set("JWT_PAYLOAD", jwt.MapClaims{
+		jwtClaimUserID: claims[jwtClaimUserID],
+		jwtClaimKeyID:  claims[jwtClaimKeyID],
+	})
+
+	identity := identityHandler()(verify)
+	require.NotNil(t, identity, "happy path must return user identity")
+	u := identity.(*model.User)
+	assert.Equal(t, uint64(100), u.ID)
+}
+
+func TestIdentityHandlerRejectsMismatchedClaimUID(t *testing.T) {
+	cleanup := setupJWTSessionTest(t)
+	defer cleanup()
+
+	ctx := newCtxForUser(0, "1.2.3.4", "ua")
+	user := model.User{Common: model.Common{ID: 100}, TokenVersion: 7}
+	claims, err := issueJWTSession(ctx, &user, 1)
+	require.NoError(t, err)
+
+	forgedUID, err := idcodec.Encode(999)
+	require.NoError(t, err)
+
+	verify := newCtxForUser(0, "1.2.3.4", "ua")
+	verify.Set("JWT_PAYLOAD", jwt.MapClaims{
+		jwtClaimUserID: forgedUID,
+		jwtClaimKeyID:  claims[jwtClaimKeyID],
+	})
+
+	identity := identityHandler()(verify)
+	assert.Nil(t, identity, "claim uid not matching session.user_id must reject")
+}
+
+func TestIdentityHandlerRejectsRevokedSession(t *testing.T) {
+	cleanup := setupJWTSessionTest(t)
+	defer cleanup()
+
+	ctx := newCtxForUser(0, "1.2.3.4", "ua")
+	user := model.User{Common: model.Common{ID: 100}, TokenVersion: 7}
+	claims, err := issueJWTSession(ctx, &user, 1)
+	require.NoError(t, err)
+	keyID := claims[jwtClaimKeyID].(string)
+	require.NoError(t, singleton.RevokeJWTSession(keyID))
+
+	verify := newCtxForUser(0, "1.2.3.4", "ua")
+	verify.Set("JWT_PAYLOAD", jwt.MapClaims{
+		jwtClaimUserID: claims[jwtClaimUserID],
+		jwtClaimKeyID:  claims[jwtClaimKeyID],
+	})
+
+	identity := identityHandler()(verify)
+	assert.Nil(t, identity, "revoked session must reject")
+}
+
+func TestIdentityHandlerRejectsTokenVersionBump(t *testing.T) {
+	cleanup := setupJWTSessionTest(t)
+	defer cleanup()
+
+	ctx := newCtxForUser(0, "1.2.3.4", "ua")
+	user := model.User{Common: model.Common{ID: 100}, TokenVersion: 7}
+	claims, err := issueJWTSession(ctx, &user, 1)
+	require.NoError(t, err)
+
+	require.NoError(t, singleton.DB.Model(&model.User{}).
+		Where("id = ?", 100).
+		Update("token_version", 8).Error)
+
+	verify := newCtxForUser(0, "1.2.3.4", "ua")
+	verify.Set("JWT_PAYLOAD", jwt.MapClaims{
+		jwtClaimUserID: claims[jwtClaimUserID],
+		jwtClaimKeyID:  claims[jwtClaimKeyID],
+	})
+
+	identity := identityHandler()(verify)
+	assert.Nil(t, identity, "session whose TokenVersion is stale must reject")
+}
+
+func TestIdentityHandlerFlagsIPMismatch(t *testing.T) {
+	cleanup := setupJWTSessionTest(t)
+	defer cleanup()
+
+	ctx := newCtxForUser(0, "1.2.3.4", "ua")
+	user := model.User{Common: model.Common{ID: 100}, TokenVersion: 7}
+	claims, err := issueJWTSession(ctx, &user, 1)
+	require.NoError(t, err)
+
+	verify := newCtxForUser(0, "9.9.9.9", "ua")
+	verify.Set("JWT_PAYLOAD", jwt.MapClaims{
+		jwtClaimUserID: claims[jwtClaimUserID],
+		jwtClaimKeyID:  claims[jwtClaimKeyID],
+	})
+
+	identity := identityHandler()(verify)
+	assert.Nil(t, identity, "IP mismatch must reject")
+	assert.True(t, verify.GetBool(model.CtxKeyIsIPMismatch))
+}
+
+func TestIdentityHandlerRejectsUnknownKeyID(t *testing.T) {
+	cleanup := setupJWTSessionTest(t)
+	defer cleanup()
+
+	hashUID, err := idcodec.Encode(100)
+	require.NoError(t, err)
+
+	verify := newCtxForUser(0, "1.2.3.4", "ua")
+	verify.Set("JWT_PAYLOAD", jwt.MapClaims{
+		jwtClaimUserID: hashUID,
+		jwtClaimKeyID:  "this-key-id-was-never-issued",
+	})
+
+	identity := identityHandler()(verify)
+	assert.Nil(t, identity, "key id absent from sessions table must reject (no oracle to confirm secret)")
+}
+
+func TestAuthenticatorPersistsCurrentTokenVersion(t *testing.T) {
+	cleanup := setupJWTSessionTest(t)
+	defer cleanup()
+
+	pw, err := bcrypt.GenerateFromPassword([]byte("correct horse"), bcrypt.MinCost)
+	require.NoError(t, err)
+	require.NoError(t, singleton.DB.Model(&model.User{}).
+		Where("id = ?", 100).
+		Update("password", string(pw)).Error)
+
+	ctx := newCtxForUser(0, "1.2.3.4", "ua")
+	body, _ := json.Marshal(model.LoginRequest{Username: "victim", Password: "correct horse"})
+	ctx.Request = httptest.NewRequest("POST", "/api/v1/login", bytes.NewReader(body))
+	ctx.Request.Header.Set("Content-Type", "application/json")
+	ctx.Request.Header.Set("User-Agent", "ua")
+	ctx.Set(model.CtxKeyRealIPStr, "1.2.3.4")
+
+	data, err := authenticator()(ctx)
+	require.NoError(t, err)
+	claims, ok := data.(map[string]interface{})
+	require.True(t, ok, "authenticator must return claims map")
+	keyID, _ := claims[jwtClaimKeyID].(string)
+	require.NotEmpty(t, keyID)
+
+	var sess model.JWTSession
+	require.NoError(t, singleton.DB.First(&sess, "key_id = ?", keyID).Error)
+	assert.Equal(t, uint64(7), sess.TokenVersion,
+		"session must record the user's current token_version, otherwise identityHandler will reject the freshly-issued token")
+
+	verify := newCtxForUser(0, "1.2.3.4", "ua")
+	verify.Set("JWT_PAYLOAD", jwt.MapClaims{
+		jwtClaimUserID: claims[jwtClaimUserID],
+		jwtClaimKeyID:  claims[jwtClaimKeyID],
+	})
+	assert.NotNil(t, identityHandler()(verify),
+		"the very next request with the freshly-issued token must authenticate")
+}

cmd/dashboard/controller/oauth2.go

@@ -187,10 +187,15 @@ func oauth2callback(jwtConfig *jwt.GinJWTMiddleware) func(c *gin.Context) (any,
 			}
 		}
 
-		tokenString, _, err := jwtConfig.TokenGenerator(map[string]interface{}{
-			"user_id": fmt.Sprintf("%d", bind.UserID),
-			"ip":      realip,
-		})
+		var bindUser model.User
+		if err := singleton.DB.First(&bindUser, bind.UserID).Error; err != nil {
+			return nil, newGormError("%v", err)
+		}
+		claims, err := issueJWTSession(c, &bindUser, singleton.Conf.JWTTimeout)
+		if err != nil {
+			return nil, err
+		}
+		tokenString, _, err := jwtConfig.TokenGenerator(claims)
 		if err != nil {
 			return nil, err
 		}

cmd/dashboard/controller/user.go

@@ -85,11 +85,15 @@ func updateProfile(c *gin.Context) (any, error) {
 	user.Username = pf.NewUsername
 	user.Password = string(hash)
 	user.RejectPassword = pf.RejectPassword
+	user.TokenVersion += 1
 	if err := singleton.DB.Save(&user).Error; err != nil {
 		return nil, newGormError("%v", err)
 	}
 
 	singleton.OnUserUpdate(&user)
+	if err := singleton.RevokeJWTSessionsByUser(user.ID); err != nil {
+		return nil, newGormError("%v", err)
+	}
 	return nil, nil
 }