feat(auth): 实现 TOTP 双因素认证功能

新增功能：
- 支持 Google Authenticator 等应用进行 TOTP 二次验证
- 用户可在个人设置中启用/禁用 2FA
- 登录时支持 TOTP 验证流程
- 管理后台可全局开关 TOTP 功能

安全增强：
- TOTP 密钥使用 AES-256-GCM 加密存储
- 添加 TOTP_ENCRYPTION_KEY 配置项，必须手动配置才能启用功能
- 防止服务重启导致加密密钥变更使用户无法登录
- 验证失败次数限制，防止暴力破解

配置说明：
- Docker 部署：在 .env 中设置 TOTP_ENCRYPTION_KEY
- 非 Docker 部署：在 config.yaml 中设置 totp.encryption_key
- 生成密钥命令：openssl rand -hex 32

backend/cmd/server/wire_gen.go

@@ -63,7 +63,13 @@ func initializeApplication(buildInfo handler.BuildInfo) (*Application, error) {
 	promoService := service.NewPromoService(promoCodeRepository, userRepository, billingCacheService, client, apiKeyAuthCacheInvalidator)
 	authService := service.NewAuthService(userRepository, configConfig, settingService, emailService, turnstileService, emailQueueService, promoService)
 	userService := service.NewUserService(userRepository, apiKeyAuthCacheInvalidator)
-	authHandler := handler.NewAuthHandler(configConfig, authService, userService, settingService, promoService)
+	secretEncryptor, err := repository.NewAESEncryptor(configConfig)
+	if err != nil {
+		return nil, err
+	}
+	totpCache := repository.NewTotpCache(redisClient)
+	totpService := service.NewTotpService(userRepository, secretEncryptor, totpCache, settingService, emailService, emailQueueService)
+	authHandler := handler.NewAuthHandler(configConfig, authService, userService, settingService, promoService, totpService)
 	userHandler := handler.NewUserHandler(userService)
 	apiKeyHandler := handler.NewAPIKeyHandler(apiKeyService)
 	usageLogRepository := repository.NewUsageLogRepository(client, db)
@@ -165,7 +171,8 @@ func initializeApplication(buildInfo handler.BuildInfo) (*Application, error) {
 	gatewayHandler := handler.NewGatewayHandler(gatewayService, geminiMessagesCompatService, antigravityGatewayService, userService, concurrencyService, billingCacheService, configConfig)
 	openAIGatewayHandler := handler.NewOpenAIGatewayHandler(openAIGatewayService, concurrencyService, billingCacheService, configConfig)
 	handlerSettingHandler := handler.ProvideSettingHandler(settingService, buildInfo)
-	handlers := handler.ProvideHandlers(authHandler, userHandler, apiKeyHandler, usageHandler, redeemHandler, subscriptionHandler, adminHandlers, gatewayHandler, openAIGatewayHandler, handlerSettingHandler)
+	totpHandler := handler.NewTotpHandler(totpService)
+	handlers := handler.ProvideHandlers(authHandler, userHandler, apiKeyHandler, usageHandler, redeemHandler, subscriptionHandler, adminHandlers, gatewayHandler, openAIGatewayHandler, handlerSettingHandler, totpHandler)
 	jwtAuthMiddleware := middleware.NewJWTAuthMiddleware(authService, userService)
 	adminAuthMiddleware := middleware.NewAdminAuthMiddleware(authService, userService, settingService)
 	apiKeyAuthMiddleware := middleware.NewAPIKeyAuthMiddleware(apiKeyService, subscriptionService, configConfig)

backend/ent/migrate/schema.go

@@ -610,6 +610,9 @@ var (
 		{Name: "status", Type: field.TypeString, Size: 20, Default: "active"},
 		{Name: "username", Type: field.TypeString, Size: 100, Default: ""},
 		{Name: "notes", Type: field.TypeString, Default: "", SchemaType: map[string]string{"postgres": "text"}},
+		{Name: "totp_secret_encrypted", Type: field.TypeString, Nullable: true, SchemaType: map[string]string{"postgres": "text"}},
+		{Name: "totp_enabled", Type: field.TypeBool, Default: false},
+		{Name: "totp_enabled_at", Type: field.TypeTime, Nullable: true},
 	}
 	// UsersTable holds the schema information for the "users" table.
 	UsersTable = &schema.Table{

backend/ent/mutation.go

@@ -14360,6 +14360,9 @@ type UserMutation struct {
 	status                        *string
 	username                      *string
 	notes                         *string
+	totp_secret_encrypted         *string
+	totp_enabled                  *bool
+	totp_enabled_at               *time.Time
 	clearedFields                 map[string]struct{}
 	api_keys                      map[int64]struct{}
 	removedapi_keys               map[int64]struct{}
@@ -14937,6 +14940,140 @@ func (m *UserMutation) ResetNotes() {
 	m.notes = nil
 }
 
+// SetTotpSecretEncrypted sets the "totp_secret_encrypted" field.
+func (m *UserMutation) SetTotpSecretEncrypted(s string) {
+	m.totp_secret_encrypted = &s
+}
+
+// TotpSecretEncrypted returns the value of the "totp_secret_encrypted" field in the mutation.
+func (m *UserMutation) TotpSecretEncrypted() (r string, exists bool) {
+	v := m.totp_secret_encrypted
+	if v == nil {
+		return
+	}
+	return *v, true
+}
+
+// OldTotpSecretEncrypted returns the old "totp_secret_encrypted" field's value of the User entity.
+// If the User object wasn't provided to the builder, the object is fetched from the database.
+// An error is returned if the mutation operation is not UpdateOne, or the database query fails.
+func (m *UserMutation) OldTotpSecretEncrypted(ctx context.Context) (v *string, err error) {
+	if !m.op.Is(OpUpdateOne) {
+		return v, errors.New("OldTotpSecretEncrypted is only allowed on UpdateOne operations")
+	}
+	if m.id == nil || m.oldValue == nil {
+		return v, errors.New("OldTotpSecretEncrypted requires an ID field in the mutation")
+	}
+	oldValue, err := m.oldValue(ctx)
+	if err != nil {
+		return v, fmt.Errorf("querying old value for OldTotpSecretEncrypted: %w", err)
+	}
+	return oldValue.TotpSecretEncrypted, nil
+}
+
+// ClearTotpSecretEncrypted clears the value of the "totp_secret_encrypted" field.
+func (m *UserMutation) ClearTotpSecretEncrypted() {
+	m.totp_secret_encrypted = nil
+	m.clearedFields[user.FieldTotpSecretEncrypted] = struct{}{}
+}
+
+// TotpSecretEncryptedCleared returns if the "totp_secret_encrypted" field was cleared in this mutation.
+func (m *UserMutation) TotpSecretEncryptedCleared() bool {
+	_, ok := m.clearedFields[user.FieldTotpSecretEncrypted]
+	return ok
+}
+
+// ResetTotpSecretEncrypted resets all changes to the "totp_secret_encrypted" field.
+func (m *UserMutation) ResetTotpSecretEncrypted() {
+	m.totp_secret_encrypted = nil
+	delete(m.clearedFields, user.FieldTotpSecretEncrypted)
+}
+
+// SetTotpEnabled sets the "totp_enabled" field.
+func (m *UserMutation) SetTotpEnabled(b bool) {
+	m.totp_enabled = &b
+}
+
+// TotpEnabled returns the value of the "totp_enabled" field in the mutation.
+func (m *UserMutation) TotpEnabled() (r bool, exists bool) {
+	v := m.totp_enabled
+	if v == nil {
+		return
+	}
+	return *v, true
+}
+
+// OldTotpEnabled returns the old "totp_enabled" field's value of the User entity.
+// If the User object wasn't provided to the builder, the object is fetched from the database.
+// An error is returned if the mutation operation is not UpdateOne, or the database query fails.
+func (m *UserMutation) OldTotpEnabled(ctx context.Context) (v bool, err error) {
+	if !m.op.Is(OpUpdateOne) {
+		return v, errors.New("OldTotpEnabled is only allowed on UpdateOne operations")
+	}
+	if m.id == nil || m.oldValue == nil {
+		return v, errors.New("OldTotpEnabled requires an ID field in the mutation")
+	}
+	oldValue, err := m.oldValue(ctx)
+	if err != nil {
+		return v, fmt.Errorf("querying old value for OldTotpEnabled: %w", err)
+	}
+	return oldValue.TotpEnabled, nil
+}
+
+// ResetTotpEnabled resets all changes to the "totp_enabled" field.
+func (m *UserMutation) ResetTotpEnabled() {
+	m.totp_enabled = nil
+}
+
+// SetTotpEnabledAt sets the "totp_enabled_at" field.
+func (m *UserMutation) SetTotpEnabledAt(t time.Time) {
+	m.totp_enabled_at = &t
+}
+
+// TotpEnabledAt returns the value of the "totp_enabled_at" field in the mutation.
+func (m *UserMutation) TotpEnabledAt() (r time.Time, exists bool) {
+	v := m.totp_enabled_at
+	if v == nil {
+		return
+	}
+	return *v, true
+}
+
+// OldTotpEnabledAt returns the old "totp_enabled_at" field's value of the User entity.
+// If the User object wasn't provided to the builder, the object is fetched from the database.
+// An error is returned if the mutation operation is not UpdateOne, or the database query fails.
+func (m *UserMutation) OldTotpEnabledAt(ctx context.Context) (v *time.Time, err error) {
+	if !m.op.Is(OpUpdateOne) {
+		return v, errors.New("OldTotpEnabledAt is only allowed on UpdateOne operations")
+	}
+	if m.id == nil || m.oldValue == nil {
+		return v, errors.New("OldTotpEnabledAt requires an ID field in the mutation")
+	}
+	oldValue, err := m.oldValue(ctx)
+	if err != nil {
+		return v, fmt.Errorf("querying old value for OldTotpEnabledAt: %w", err)
+	}
+	return oldValue.TotpEnabledAt, nil
+}
+
+// ClearTotpEnabledAt clears the value of the "totp_enabled_at" field.
+func (m *UserMutation) ClearTotpEnabledAt() {
+	m.totp_enabled_at = nil
+	m.clearedFields[user.FieldTotpEnabledAt] = struct{}{}
+}
+
+// TotpEnabledAtCleared returns if the "totp_enabled_at" field was cleared in this mutation.
+func (m *UserMutation) TotpEnabledAtCleared() bool {
+	_, ok := m.clearedFields[user.FieldTotpEnabledAt]
+	return ok
+}
+
+// ResetTotpEnabledAt resets all changes to the "totp_enabled_at" field.
+func (m *UserMutation) ResetTotpEnabledAt() {
+	m.totp_enabled_at = nil
+	delete(m.clearedFields, user.FieldTotpEnabledAt)
+}
+
 // AddAPIKeyIDs adds the "api_keys" edge to the APIKey entity by ids.
 func (m *UserMutation) AddAPIKeyIDs(ids ...int64) {
 	if m.api_keys == nil {
@@ -15403,7 +15540,7 @@ func (m *UserMutation) Type() string {
 // order to get all numeric fields that were incremented/decremented, call
 // AddedFields().
 func (m *UserMutation) Fields() []string {
-	fields := make([]string, 0, 11)
+	fields := make([]string, 0, 14)
 	if m.created_at != nil {
 		fields = append(fields, user.FieldCreatedAt)
 	}
@@ -15437,6 +15574,15 @@ func (m *UserMutation) Fields() []string {
 	if m.notes != nil {
 		fields = append(fields, user.FieldNotes)
 	}
+	if m.totp_secret_encrypted != nil {
+		fields = append(fields, user.FieldTotpSecretEncrypted)
+	}
+	if m.totp_enabled != nil {
+		fields = append(fields, user.FieldTotpEnabled)
+	}
+	if m.totp_enabled_at != nil {
+		fields = append(fields, user.FieldTotpEnabledAt)
+	}
 	return fields
 }
 
@@ -15467,6 +15613,12 @@ func (m *UserMutation) Field(name string) (ent.Value, bool) {
 		return m.Username()
 	case user.FieldNotes:
 		return m.Notes()
+	case user.FieldTotpSecretEncrypted:
+		return m.TotpSecretEncrypted()
+	case user.FieldTotpEnabled:
+		return m.TotpEnabled()
+	case user.FieldTotpEnabledAt:
+		return m.TotpEnabledAt()
 	}
 	return nil, false
 }
@@ -15498,6 +15650,12 @@ func (m *UserMutation) OldField(ctx context.Context, name string) (ent.Value, er
 		return m.OldUsername(ctx)
 	case user.FieldNotes:
 		return m.OldNotes(ctx)
+	case user.FieldTotpSecretEncrypted:
+		return m.OldTotpSecretEncrypted(ctx)
+	case user.FieldTotpEnabled:
+		return m.OldTotpEnabled(ctx)
+	case user.FieldTotpEnabledAt:
+		return m.OldTotpEnabledAt(ctx)
 	}
 	return nil, fmt.Errorf("unknown User field %s", name)
 }
@@ -15584,6 +15742,27 @@ func (m *UserMutation) SetField(name string, value ent.Value) error {
 		}
 		m.SetNotes(v)
 		return nil
+	case user.FieldTotpSecretEncrypted:
+		v, ok := value.(string)
+		if !ok {
+			return fmt.Errorf("unexpected type %T for field %s", value, name)
+		}
+		m.SetTotpSecretEncrypted(v)
+		return nil
+	case user.FieldTotpEnabled:
+		v, ok := value.(bool)
+		if !ok {
+			return fmt.Errorf("unexpected type %T for field %s", value, name)
+		}
+		m.SetTotpEnabled(v)
+		return nil
+	case user.FieldTotpEnabledAt:
+		v, ok := value.(time.Time)
+		if !ok {
+			return fmt.Errorf("unexpected type %T for field %s", value, name)
+		}
+		m.SetTotpEnabledAt(v)
+		return nil
 	}
 	return fmt.Errorf("unknown User field %s", name)
 }
@@ -15644,6 +15823,12 @@ func (m *UserMutation) ClearedFields() []string {
 	if m.FieldCleared(user.FieldDeletedAt) {
 		fields = append(fields, user.FieldDeletedAt)
 	}
+	if m.FieldCleared(user.FieldTotpSecretEncrypted) {
+		fields = append(fields, user.FieldTotpSecretEncrypted)
+	}
+	if m.FieldCleared(user.FieldTotpEnabledAt) {
+		fields = append(fields, user.FieldTotpEnabledAt)
+	}
 	return fields
 }
 
@@ -15661,6 +15846,12 @@ func (m *UserMutation) ClearField(name string) error {
 	case user.FieldDeletedAt:
 		m.ClearDeletedAt()
 		return nil
+	case user.FieldTotpSecretEncrypted:
+		m.ClearTotpSecretEncrypted()
+		return nil
+	case user.FieldTotpEnabledAt:
+		m.ClearTotpEnabledAt()
+		return nil
 	}
 	return fmt.Errorf("unknown User nullable field %s", name)
 }
@@ -15702,6 +15893,15 @@ func (m *UserMutation) ResetField(name string) error {
 	case user.FieldNotes:
 		m.ResetNotes()
 		return nil
+	case user.FieldTotpSecretEncrypted:
+		m.ResetTotpSecretEncrypted()
+		return nil
+	case user.FieldTotpEnabled:
+		m.ResetTotpEnabled()
+		return nil
+	case user.FieldTotpEnabledAt:
+		m.ResetTotpEnabledAt()
+		return nil
 	}
 	return fmt.Errorf("unknown User field %s", name)
 }

backend/ent/runtime/runtime.go

@@ -736,6 +736,10 @@ func init() {
 	userDescNotes := userFields[7].Descriptor()
 	// user.DefaultNotes holds the default value on creation for the notes field.
 	user.DefaultNotes = userDescNotes.Default.(string)
+	// userDescTotpEnabled is the schema descriptor for totp_enabled field.
+	userDescTotpEnabled := userFields[9].Descriptor()
+	// user.DefaultTotpEnabled holds the default value on creation for the totp_enabled field.
+	user.DefaultTotpEnabled = userDescTotpEnabled.Default.(bool)
 	userallowedgroupFields := schema.UserAllowedGroup{}.Fields()
 	_ = userallowedgroupFields
 	// userallowedgroupDescCreatedAt is the schema descriptor for created_at field.

backend/ent/schema/user.go

@@ -61,6 +61,17 @@ func (User) Fields() []ent.Field {
 		field.String("notes").
 			SchemaType(map[string]string{dialect.Postgres: "text"}).
 			Default(""),
+
+		// TOTP 双因素认证字段
+		field.String("totp_secret_encrypted").
+			SchemaType(map[string]string{dialect.Postgres: "text"}).
+			Optional().
+			Nillable(),
+		field.Bool("totp_enabled").
+			Default(false),
+		field.Time("totp_enabled_at").
+			Optional().
+			Nillable(),
 	}
 }
 

backend/ent/user.go

@@ -39,6 +39,12 @@ type User struct {
 	Username string `json:"username,omitempty"`
 	// Notes holds the value of the "notes" field.
 	Notes string `json:"notes,omitempty"`
+	// TotpSecretEncrypted holds the value of the "totp_secret_encrypted" field.
+	TotpSecretEncrypted *string `json:"totp_secret_encrypted,omitempty"`
+	// TotpEnabled holds the value of the "totp_enabled" field.
+	TotpEnabled bool `json:"totp_enabled,omitempty"`
+	// TotpEnabledAt holds the value of the "totp_enabled_at" field.
+	TotpEnabledAt *time.Time `json:"totp_enabled_at,omitempty"`
 	// Edges holds the relations/edges for other nodes in the graph.
 	// The values are being populated by the UserQuery when eager-loading is set.
 	Edges        UserEdges `json:"edges"`
@@ -156,13 +162,15 @@ func (*User) scanValues(columns []string) ([]any, error) {
 	values := make([]any, len(columns))
 	for i := range columns {
 		switch columns[i] {
+		case user.FieldTotpEnabled:
+			values[i] = new(sql.NullBool)
 		case user.FieldBalance:
 			values[i] = new(sql.NullFloat64)
 		case user.FieldID, user.FieldConcurrency:
 			values[i] = new(sql.NullInt64)
-		case user.FieldEmail, user.FieldPasswordHash, user.FieldRole, user.FieldStatus, user.FieldUsername, user.FieldNotes:
+		case user.FieldEmail, user.FieldPasswordHash, user.FieldRole, user.FieldStatus, user.FieldUsername, user.FieldNotes, user.FieldTotpSecretEncrypted:
 			values[i] = new(sql.NullString)
-		case user.FieldCreatedAt, user.FieldUpdatedAt, user.FieldDeletedAt:
+		case user.FieldCreatedAt, user.FieldUpdatedAt, user.FieldDeletedAt, user.FieldTotpEnabledAt:
 			values[i] = new(sql.NullTime)
 		default:
 			values[i] = new(sql.UnknownType)
@@ -252,6 +260,26 @@ func (_m *User) assignValues(columns []string, values []any) error {
 			} else if value.Valid {
 				_m.Notes = value.String
 			}
+		case user.FieldTotpSecretEncrypted:
+			if value, ok := values[i].(*sql.NullString); !ok {
+				return fmt.Errorf("unexpected type %T for field totp_secret_encrypted", values[i])
+			} else if value.Valid {
+				_m.TotpSecretEncrypted = new(string)
+				*_m.TotpSecretEncrypted = value.String
+			}
+		case user.FieldTotpEnabled:
+			if value, ok := values[i].(*sql.NullBool); !ok {
+				return fmt.Errorf("unexpected type %T for field totp_enabled", values[i])
+			} else if value.Valid {
+				_m.TotpEnabled = value.Bool
+			}
+		case user.FieldTotpEnabledAt:
+			if value, ok := values[i].(*sql.NullTime); !ok {
+				return fmt.Errorf("unexpected type %T for field totp_enabled_at", values[i])
+			} else if value.Valid {
+				_m.TotpEnabledAt = new(time.Time)
+				*_m.TotpEnabledAt = value.Time
+			}
 		default:
 			_m.selectValues.Set(columns[i], values[i])
 		}
@@ -367,6 +395,19 @@ func (_m *User) String() string {
 	builder.WriteString(", ")
 	builder.WriteString("notes=")
 	builder.WriteString(_m.Notes)
+	builder.WriteString(", ")
+	if v := _m.TotpSecretEncrypted; v != nil {
+		builder.WriteString("totp_secret_encrypted=")
+		builder.WriteString(*v)
+	}
+	builder.WriteString(", ")
+	builder.WriteString("totp_enabled=")
+	builder.WriteString(fmt.Sprintf("%v", _m.TotpEnabled))
+	builder.WriteString(", ")
+	if v := _m.TotpEnabledAt; v != nil {
+		builder.WriteString("totp_enabled_at=")
+		builder.WriteString(v.Format(time.ANSIC))
+	}
 	builder.WriteByte(')')
 	return builder.String()
 }

backend/ent/user/user.go

@@ -37,6 +37,12 @@ const (
 	FieldUsername = "username"
 	// FieldNotes holds the string denoting the notes field in the database.
 	FieldNotes = "notes"
+	// FieldTotpSecretEncrypted holds the string denoting the totp_secret_encrypted field in the database.
+	FieldTotpSecretEncrypted = "totp_secret_encrypted"
+	// FieldTotpEnabled holds the string denoting the totp_enabled field in the database.
+	FieldTotpEnabled = "totp_enabled"
+	// FieldTotpEnabledAt holds the string denoting the totp_enabled_at field in the database.
+	FieldTotpEnabledAt = "totp_enabled_at"
 	// EdgeAPIKeys holds the string denoting the api_keys edge name in mutations.
 	EdgeAPIKeys = "api_keys"
 	// EdgeRedeemCodes holds the string denoting the redeem_codes edge name in mutations.
@@ -134,6 +140,9 @@ var Columns = []string{
 	FieldStatus,
 	FieldUsername,
 	FieldNotes,
+	FieldTotpSecretEncrypted,
+	FieldTotpEnabled,
+	FieldTotpEnabledAt,
 }
 
 var (
@@ -188,6 +197,8 @@ var (
 	UsernameValidator func(string) error
 	// DefaultNotes holds the default value on creation for the "notes" field.
 	DefaultNotes string
+	// DefaultTotpEnabled holds the default value on creation for the "totp_enabled" field.
+	DefaultTotpEnabled bool
 )
 
 // OrderOption defines the ordering options for the User queries.
@@ -253,6 +264,21 @@ func ByNotes(opts ...sql.OrderTermOption) OrderOption {
 	return sql.OrderByField(FieldNotes, opts...).ToFunc()
 }
 
+// ByTotpSecretEncrypted orders the results by the totp_secret_encrypted field.
+func ByTotpSecretEncrypted(opts ...sql.OrderTermOption) OrderOption {
+	return sql.OrderByField(FieldTotpSecretEncrypted, opts...).ToFunc()
+}
+
+// ByTotpEnabled orders the results by the totp_enabled field.
+func ByTotpEnabled(opts ...sql.OrderTermOption) OrderOption {
+	return sql.OrderByField(FieldTotpEnabled, opts...).ToFunc()
+}
+
+// ByTotpEnabledAt orders the results by the totp_enabled_at field.
+func ByTotpEnabledAt(opts ...sql.OrderTermOption) OrderOption {
+	return sql.OrderByField(FieldTotpEnabledAt, opts...).ToFunc()
+}
+
 // ByAPIKeysCount orders the results by api_keys count.
 func ByAPIKeysCount(opts ...sql.OrderTermOption) OrderOption {
 	return func(s *sql.Selector) {

backend/ent/user/where.go

@@ -110,6 +110,21 @@ func Notes(v string) predicate.User {
 	return predicate.User(sql.FieldEQ(FieldNotes, v))
 }
 
+// TotpSecretEncrypted applies equality check predicate on the "totp_secret_encrypted" field. It's identical to TotpSecretEncryptedEQ.
+func TotpSecretEncrypted(v string) predicate.User {
+	return predicate.User(sql.FieldEQ(FieldTotpSecretEncrypted, v))
+}
+
+// TotpEnabled applies equality check predicate on the "totp_enabled" field. It's identical to TotpEnabledEQ.
+func TotpEnabled(v bool) predicate.User {
+	return predicate.User(sql.FieldEQ(FieldTotpEnabled, v))
+}
+
+// TotpEnabledAt applies equality check predicate on the "totp_enabled_at" field. It's identical to TotpEnabledAtEQ.
+func TotpEnabledAt(v time.Time) predicate.User {
+	return predicate.User(sql.FieldEQ(FieldTotpEnabledAt, v))
+}
+
 // CreatedAtEQ applies the EQ predicate on the "created_at" field.
 func CreatedAtEQ(v time.Time) predicate.User {
 	return predicate.User(sql.FieldEQ(FieldCreatedAt, v))
@@ -710,6 +725,141 @@ func NotesContainsFold(v string) predicate.User {
 	return predicate.User(sql.FieldContainsFold(FieldNotes, v))
 }
 
+// TotpSecretEncryptedEQ applies the EQ predicate on the "totp_secret_encrypted" field.
+func TotpSecretEncryptedEQ(v string) predicate.User {
+	return predicate.User(sql.FieldEQ(FieldTotpSecretEncrypted, v))
+}
+
+// TotpSecretEncryptedNEQ applies the NEQ predicate on the "totp_secret_encrypted" field.
+func TotpSecretEncryptedNEQ(v string) predicate.User {
+	return predicate.User(sql.FieldNEQ(FieldTotpSecretEncrypted, v))
+}
+
+// TotpSecretEncryptedIn applies the In predicate on the "totp_secret_encrypted" field.
+func TotpSecretEncryptedIn(vs ...string) predicate.User {
+	return predicate.User(sql.FieldIn(FieldTotpSecretEncrypted, vs...))
+}
+
+// TotpSecretEncryptedNotIn applies the NotIn predicate on the "totp_secret_encrypted" field.
+func TotpSecretEncryptedNotIn(vs ...string) predicate.User {
+	return predicate.User(sql.FieldNotIn(FieldTotpSecretEncrypted, vs...))
+}
+
+// TotpSecretEncryptedGT applies the GT predicate on the "totp_secret_encrypted" field.
+func TotpSecretEncryptedGT(v string) predicate.User {
+	return predicate.User(sql.FieldGT(FieldTotpSecretEncrypted, v))
+}
+
+// TotpSecretEncryptedGTE applies the GTE predicate on the "totp_secret_encrypted" field.
+func TotpSecretEncryptedGTE(v string) predicate.User {
+	return predicate.User(sql.FieldGTE(FieldTotpSecretEncrypted, v))
+}
+
+// TotpSecretEncryptedLT applies the LT predicate on the "totp_secret_encrypted" field.
+func TotpSecretEncryptedLT(v string) predicate.User {
+	return predicate.User(sql.FieldLT(FieldTotpSecretEncrypted, v))
+}
+
+// TotpSecretEncryptedLTE applies the LTE predicate on the "totp_secret_encrypted" field.
+func TotpSecretEncryptedLTE(v string) predicate.User {
+	return predicate.User(sql.FieldLTE(FieldTotpSecretEncrypted, v))
+}
+
+// TotpSecretEncryptedContains applies the Contains predicate on the "totp_secret_encrypted" field.
+func TotpSecretEncryptedContains(v string) predicate.User {
+	return predicate.User(sql.FieldContains(FieldTotpSecretEncrypted, v))
+}
+
+// TotpSecretEncryptedHasPrefix applies the HasPrefix predicate on the "totp_secret_encrypted" field.
+func TotpSecretEncryptedHasPrefix(v string) predicate.User {
+	return predicate.User(sql.FieldHasPrefix(FieldTotpSecretEncrypted, v))
+}
+
+// TotpSecretEncryptedHasSuffix applies the HasSuffix predicate on the "totp_secret_encrypted" field.
+func TotpSecretEncryptedHasSuffix(v string) predicate.User {
+	return predicate.User(sql.FieldHasSuffix(FieldTotpSecretEncrypted, v))
+}
+
+// TotpSecretEncryptedIsNil applies the IsNil predicate on the "totp_secret_encrypted" field.
+func TotpSecretEncryptedIsNil() predicate.User {
+	return predicate.User(sql.FieldIsNull(FieldTotpSecretEncrypted))
+}
+
+// TotpSecretEncryptedNotNil applies the NotNil predicate on the "totp_secret_encrypted" field.
+func TotpSecretEncryptedNotNil() predicate.User {
+	return predicate.User(sql.FieldNotNull(FieldTotpSecretEncrypted))
+}
+
+// TotpSecretEncryptedEqualFold applies the EqualFold predicate on the "totp_secret_encrypted" field.
+func TotpSecretEncryptedEqualFold(v string) predicate.User {
+	return predicate.User(sql.FieldEqualFold(FieldTotpSecretEncrypted, v))
+}
+
+// TotpSecretEncryptedContainsFold applies the ContainsFold predicate on the "totp_secret_encrypted" field.
+func TotpSecretEncryptedContainsFold(v string) predicate.User {
+	return predicate.User(sql.FieldContainsFold(FieldTotpSecretEncrypted, v))
+}
+
+// TotpEnabledEQ applies the EQ predicate on the "totp_enabled" field.
+func TotpEnabledEQ(v bool) predicate.User {
+	return predicate.User(sql.FieldEQ(FieldTotpEnabled, v))
+}
+
+// TotpEnabledNEQ applies the NEQ predicate on the "totp_enabled" field.
+func TotpEnabledNEQ(v bool) predicate.User {
+	return predicate.User(sql.FieldNEQ(FieldTotpEnabled, v))
+}
+
+// TotpEnabledAtEQ applies the EQ predicate on the "totp_enabled_at" field.
+func TotpEnabledAtEQ(v time.Time) predicate.User {
+	return predicate.User(sql.FieldEQ(FieldTotpEnabledAt, v))
+}
+
+// TotpEnabledAtNEQ applies the NEQ predicate on the "totp_enabled_at" field.
+func TotpEnabledAtNEQ(v time.Time) predicate.User {
+	return predicate.User(sql.FieldNEQ(FieldTotpEnabledAt, v))
+}
+
+// TotpEnabledAtIn applies the In predicate on the "totp_enabled_at" field.
+func TotpEnabledAtIn(vs ...time.Time) predicate.User {
+	return predicate.User(sql.FieldIn(FieldTotpEnabledAt, vs...))
+}
+
+// TotpEnabledAtNotIn applies the NotIn predicate on the "totp_enabled_at" field.
+func TotpEnabledAtNotIn(vs ...time.Time) predicate.User {
+	return predicate.User(sql.FieldNotIn(FieldTotpEnabledAt, vs...))
+}
+
+// TotpEnabledAtGT applies the GT predicate on the "totp_enabled_at" field.
+func TotpEnabledAtGT(v time.Time) predicate.User {
+	return predicate.User(sql.FieldGT(FieldTotpEnabledAt, v))
+}
+
+// TotpEnabledAtGTE applies the GTE predicate on the "totp_enabled_at" field.
+func TotpEnabledAtGTE(v time.Time) predicate.User {
+	return predicate.User(sql.FieldGTE(FieldTotpEnabledAt, v))
+}
+
+// TotpEnabledAtLT applies the LT predicate on the "totp_enabled_at" field.
+func TotpEnabledAtLT(v time.Time) predicate.User {
+	return predicate.User(sql.FieldLT(FieldTotpEnabledAt, v))
+}
+
+// TotpEnabledAtLTE applies the LTE predicate on the "totp_enabled_at" field.
+func TotpEnabledAtLTE(v time.Time) predicate.User {
+	return predicate.User(sql.FieldLTE(FieldTotpEnabledAt, v))
+}
+
+// TotpEnabledAtIsNil applies the IsNil predicate on the "totp_enabled_at" field.
+func TotpEnabledAtIsNil() predicate.User {
+	return predicate.User(sql.FieldIsNull(FieldTotpEnabledAt))
+}
+
+// TotpEnabledAtNotNil applies the NotNil predicate on the "totp_enabled_at" field.
+func TotpEnabledAtNotNil() predicate.User {
+	return predicate.User(sql.FieldNotNull(FieldTotpEnabledAt))
+}
+
 // HasAPIKeys applies the HasEdge predicate on the "api_keys" edge.
 func HasAPIKeys() predicate.User {
 	return predicate.User(func(s *sql.Selector) {

backend/ent/user_create.go

@@ -167,6 +167,48 @@ func (_c *UserCreate) SetNillableNotes(v *string) *UserCreate {
 	return _c
 }
 
+// SetTotpSecretEncrypted sets the "totp_secret_encrypted" field.
+func (_c *UserCreate) SetTotpSecretEncrypted(v string) *UserCreate {
+	_c.mutation.SetTotpSecretEncrypted(v)
+	return _c
+}
+
+// SetNillableTotpSecretEncrypted sets the "totp_secret_encrypted" field if the given value is not nil.
+func (_c *UserCreate) SetNillableTotpSecretEncrypted(v *string) *UserCreate {
+	if v != nil {
+		_c.SetTotpSecretEncrypted(*v)
+	}
+	return _c
+}
+
+// SetTotpEnabled sets the "totp_enabled" field.
+func (_c *UserCreate) SetTotpEnabled(v bool) *UserCreate {
+	_c.mutation.SetTotpEnabled(v)
+	return _c
+}
+
+// SetNillableTotpEnabled sets the "totp_enabled" field if the given value is not nil.
+func (_c *UserCreate) SetNillableTotpEnabled(v *bool) *UserCreate {
+	if v != nil {
+		_c.SetTotpEnabled(*v)
+	}
+	return _c
+}
+
+// SetTotpEnabledAt sets the "totp_enabled_at" field.
+func (_c *UserCreate) SetTotpEnabledAt(v time.Time) *UserCreate {
+	_c.mutation.SetTotpEnabledAt(v)
+	return _c
+}
+
+// SetNillableTotpEnabledAt sets the "totp_enabled_at" field if the given value is not nil.
+func (_c *UserCreate) SetNillableTotpEnabledAt(v *time.Time) *UserCreate {
+	if v != nil {
+		_c.SetTotpEnabledAt(*v)
+	}
+	return _c
+}
+
 // AddAPIKeyIDs adds the "api_keys" edge to the APIKey entity by IDs.
 func (_c *UserCreate) AddAPIKeyIDs(ids ...int64) *UserCreate {
 	_c.mutation.AddAPIKeyIDs(ids...)
@@ -362,6 +404,10 @@ func (_c *UserCreate) defaults() error {
 		v := user.DefaultNotes
 		_c.mutation.SetNotes(v)
 	}
+	if _, ok := _c.mutation.TotpEnabled(); !ok {
+		v := user.DefaultTotpEnabled
+		_c.mutation.SetTotpEnabled(v)
+	}
 	return nil
 }
 
@@ -422,6 +468,9 @@ func (_c *UserCreate) check() error {
 	if _, ok := _c.mutation.Notes(); !ok {
 		return &ValidationError{Name: "notes", err: errors.New(`ent: missing required field "User.notes"`)}
 	}
+	if _, ok := _c.mutation.TotpEnabled(); !ok {
+		return &ValidationError{Name: "totp_enabled", err: errors.New(`ent: missing required field "User.totp_enabled"`)}
+	}
 	return nil
 }
 
@@ -493,6 +542,18 @@ func (_c *UserCreate) createSpec() (*User, *sqlgraph.CreateSpec) {
 		_spec.SetField(user.FieldNotes, field.TypeString, value)
 		_node.Notes = value
 	}
+	if value, ok := _c.mutation.TotpSecretEncrypted(); ok {
+		_spec.SetField(user.FieldTotpSecretEncrypted, field.TypeString, value)
+		_node.TotpSecretEncrypted = &value
+	}
+	if value, ok := _c.mutation.TotpEnabled(); ok {
+		_spec.SetField(user.FieldTotpEnabled, field.TypeBool, value)
+		_node.TotpEnabled = value
+	}
+	if value, ok := _c.mutation.TotpEnabledAt(); ok {
+		_spec.SetField(user.FieldTotpEnabledAt, field.TypeTime, value)
+		_node.TotpEnabledAt = &value
+	}
 	if nodes := _c.mutation.APIKeysIDs(); len(nodes) > 0 {
 		edge := &sqlgraph.EdgeSpec{
 			Rel:     sqlgraph.O2M,
@@ -815,6 +876,54 @@ func (u *UserUpsert) UpdateNotes() *UserUpsert {
 	return u
 }
 
+// SetTotpSecretEncrypted sets the "totp_secret_encrypted" field.
+func (u *UserUpsert) SetTotpSecretEncrypted(v string) *UserUpsert {
+	u.Set(user.FieldTotpSecretEncrypted, v)
+	return u
+}
+
+// UpdateTotpSecretEncrypted sets the "totp_secret_encrypted" field to the value that was provided on create.
+func (u *UserUpsert) UpdateTotpSecretEncrypted() *UserUpsert {
+	u.SetExcluded(user.FieldTotpSecretEncrypted)
+	return u
+}
+
+// ClearTotpSecretEncrypted clears the value of the "totp_secret_encrypted" field.
+func (u *UserUpsert) ClearTotpSecretEncrypted() *UserUpsert {
+	u.SetNull(user.FieldTotpSecretEncrypted)
+	return u
+}
+
+// SetTotpEnabled sets the "totp_enabled" field.
+func (u *UserUpsert) SetTotpEnabled(v bool) *UserUpsert {
+	u.Set(user.FieldTotpEnabled, v)
+	return u
+}
+
+// UpdateTotpEnabled sets the "totp_enabled" field to the value that was provided on create.
+func (u *UserUpsert) UpdateTotpEnabled() *UserUpsert {
+	u.SetExcluded(user.FieldTotpEnabled)
+	return u
+}
+
+// SetTotpEnabledAt sets the "totp_enabled_at" field.
+func (u *UserUpsert) SetTotpEnabledAt(v time.Time) *UserUpsert {
+	u.Set(user.FieldTotpEnabledAt, v)
+	return u
+}
+
+// UpdateTotpEnabledAt sets the "totp_enabled_at" field to the value that was provided on create.
+func (u *UserUpsert) UpdateTotpEnabledAt() *UserUpsert {
+	u.SetExcluded(user.FieldTotpEnabledAt)
+	return u
+}
+
+// ClearTotpEnabledAt clears the value of the "totp_enabled_at" field.
+func (u *UserUpsert) ClearTotpEnabledAt() *UserUpsert {
+	u.SetNull(user.FieldTotpEnabledAt)
+	return u
+}
+
 // UpdateNewValues updates the mutable fields using the new values that were set on create.
 // Using this option is equivalent to using:
 //
@@ -1021,6 +1130,62 @@ func (u *UserUpsertOne) UpdateNotes() *UserUpsertOne {
 	})
 }
 
+// SetTotpSecretEncrypted sets the "totp_secret_encrypted" field.
+func (u *UserUpsertOne) SetTotpSecretEncrypted(v string) *UserUpsertOne {
+	return u.Update(func(s *UserUpsert) {
+		s.SetTotpSecretEncrypted(v)
+	})
+}
+
+// UpdateTotpSecretEncrypted sets the "totp_secret_encrypted" field to the value that was provided on create.
+func (u *UserUpsertOne) UpdateTotpSecretEncrypted() *UserUpsertOne {
+	return u.Update(func(s *UserUpsert) {
+		s.UpdateTotpSecretEncrypted()
+	})
+}
+
+// ClearTotpSecretEncrypted clears the value of the "totp_secret_encrypted" field.
+func (u *UserUpsertOne) ClearTotpSecretEncrypted() *UserUpsertOne {
+	return u.Update(func(s *UserUpsert) {
+		s.ClearTotpSecretEncrypted()
+	})
+}
+
+// SetTotpEnabled sets the "totp_enabled" field.
+func (u *UserUpsertOne) SetTotpEnabled(v bool) *UserUpsertOne {
+	return u.Update(func(s *UserUpsert) {
+		s.SetTotpEnabled(v)
+	})
+}
+
+// UpdateTotpEnabled sets the "totp_enabled" field to the value that was provided on create.
+func (u *UserUpsertOne) UpdateTotpEnabled() *UserUpsertOne {
+	return u.Update(func(s *UserUpsert) {
+		s.UpdateTotpEnabled()
+	})
+}
+
+// SetTotpEnabledAt sets the "totp_enabled_at" field.
+func (u *UserUpsertOne) SetTotpEnabledAt(v time.Time) *UserUpsertOne {
+	return u.Update(func(s *UserUpsert) {
+		s.SetTotpEnabledAt(v)
+	})
+}
+
+// UpdateTotpEnabledAt sets the "totp_enabled_at" field to the value that was provided on create.
+func (u *UserUpsertOne) UpdateTotpEnabledAt() *UserUpsertOne {
+	return u.Update(func(s *UserUpsert) {
+		s.UpdateTotpEnabledAt()
+	})
+}
+
+// ClearTotpEnabledAt clears the value of the "totp_enabled_at" field.
+func (u *UserUpsertOne) ClearTotpEnabledAt() *UserUpsertOne {
+	return u.Update(func(s *UserUpsert) {
+		s.ClearTotpEnabledAt()
+	})
+}
+
 // Exec executes the query.
 func (u *UserUpsertOne) Exec(ctx context.Context) error {
 	if len(u.create.conflict) == 0 {
@@ -1393,6 +1558,62 @@ func (u *UserUpsertBulk) UpdateNotes() *UserUpsertBulk {
 	})
 }
 
+// SetTotpSecretEncrypted sets the "totp_secret_encrypted" field.
+func (u *UserUpsertBulk) SetTotpSecretEncrypted(v string) *UserUpsertBulk {
+	return u.Update(func(s *UserUpsert) {
+		s.SetTotpSecretEncrypted(v)
+	})
+}
+
+// UpdateTotpSecretEncrypted sets the "totp_secret_encrypted" field to the value that was provided on create.
+func (u *UserUpsertBulk) UpdateTotpSecretEncrypted() *UserUpsertBulk {
+	return u.Update(func(s *UserUpsert) {
+		s.UpdateTotpSecretEncrypted()
+	})
+}
+
+// ClearTotpSecretEncrypted clears the value of the "totp_secret_encrypted" field.
+func (u *UserUpsertBulk) ClearTotpSecretEncrypted() *UserUpsertBulk {
+	return u.Update(func(s *UserUpsert) {
+		s.ClearTotpSecretEncrypted()
+	})
+}
+
+// SetTotpEnabled sets the "totp_enabled" field.
+func (u *UserUpsertBulk) SetTotpEnabled(v bool) *UserUpsertBulk {
+	return u.Update(func(s *UserUpsert) {
+		s.SetTotpEnabled(v)
+	})
+}
+
+// UpdateTotpEnabled sets the "totp_enabled" field to the value that was provided on create.
+func (u *UserUpsertBulk) UpdateTotpEnabled() *UserUpsertBulk {
+	return u.Update(func(s *UserUpsert) {
+		s.UpdateTotpEnabled()
+	})
+}
+
+// SetTotpEnabledAt sets the "totp_enabled_at" field.
+func (u *UserUpsertBulk) SetTotpEnabledAt(v time.Time) *UserUpsertBulk {
+	return u.Update(func(s *UserUpsert) {
+		s.SetTotpEnabledAt(v)
+	})
+}
+
+// UpdateTotpEnabledAt sets the "totp_enabled_at" field to the value that was provided on create.
+func (u *UserUpsertBulk) UpdateTotpEnabledAt() *UserUpsertBulk {
+	return u.Update(func(s *UserUpsert) {
+		s.UpdateTotpEnabledAt()
+	})
+}
+
+// ClearTotpEnabledAt clears the value of the "totp_enabled_at" field.
+func (u *UserUpsertBulk) ClearTotpEnabledAt() *UserUpsertBulk {
+	return u.Update(func(s *UserUpsert) {
+		s.ClearTotpEnabledAt()
+	})
+}
+
 // Exec executes the query.
 func (u *UserUpsertBulk) Exec(ctx context.Context) error {
 	if u.create.err != nil {

backend/ent/user_update.go

@@ -187,6 +187,60 @@ func (_u *UserUpdate) SetNillableNotes(v *string) *UserUpdate {
 	return _u
 }
 
+// SetTotpSecretEncrypted sets the "totp_secret_encrypted" field.
+func (_u *UserUpdate) SetTotpSecretEncrypted(v string) *UserUpdate {
+	_u.mutation.SetTotpSecretEncrypted(v)
+	return _u
+}
+
+// SetNillableTotpSecretEncrypted sets the "totp_secret_encrypted" field if the given value is not nil.
+func (_u *UserUpdate) SetNillableTotpSecretEncrypted(v *string) *UserUpdate {
+	if v != nil {
+		_u.SetTotpSecretEncrypted(*v)
+	}
+	return _u
+}
+
+// ClearTotpSecretEncrypted clears the value of the "totp_secret_encrypted" field.
+func (_u *UserUpdate) ClearTotpSecretEncrypted() *UserUpdate {
+	_u.mutation.ClearTotpSecretEncrypted()
+	return _u
+}
+
+// SetTotpEnabled sets the "totp_enabled" field.
+func (_u *UserUpdate) SetTotpEnabled(v bool) *UserUpdate {
+	_u.mutation.SetTotpEnabled(v)
+	return _u
+}
+
+// SetNillableTotpEnabled sets the "totp_enabled" field if the given value is not nil.
+func (_u *UserUpdate) SetNillableTotpEnabled(v *bool) *UserUpdate {
+	if v != nil {
+		_u.SetTotpEnabled(*v)
+	}
+	return _u
+}
+
+// SetTotpEnabledAt sets the "totp_enabled_at" field.
+func (_u *UserUpdate) SetTotpEnabledAt(v time.Time) *UserUpdate {
+	_u.mutation.SetTotpEnabledAt(v)
+	return _u
+}
+
+// SetNillableTotpEnabledAt sets the "totp_enabled_at" field if the given value is not nil.
+func (_u *UserUpdate) SetNillableTotpEnabledAt(v *time.Time) *UserUpdate {
+	if v != nil {
+		_u.SetTotpEnabledAt(*v)
+	}
+	return _u
+}
+
+// ClearTotpEnabledAt clears the value of the "totp_enabled_at" field.
+func (_u *UserUpdate) ClearTotpEnabledAt() *UserUpdate {
+	_u.mutation.ClearTotpEnabledAt()
+	return _u
+}
+
 // AddAPIKeyIDs adds the "api_keys" edge to the APIKey entity by IDs.
 func (_u *UserUpdate) AddAPIKeyIDs(ids ...int64) *UserUpdate {
 	_u.mutation.AddAPIKeyIDs(ids...)
@@ -603,6 +657,21 @@ func (_u *UserUpdate) sqlSave(ctx context.Context) (_node int, err error) {
 	if value, ok := _u.mutation.Notes(); ok {
 		_spec.SetField(user.FieldNotes, field.TypeString, value)
 	}
+	if value, ok := _u.mutation.TotpSecretEncrypted(); ok {
+		_spec.SetField(user.FieldTotpSecretEncrypted, field.TypeString, value)
+	}
+	if _u.mutation.TotpSecretEncryptedCleared() {
+		_spec.ClearField(user.FieldTotpSecretEncrypted, field.TypeString)
+	}
+	if value, ok := _u.mutation.TotpEnabled(); ok {
+		_spec.SetField(user.FieldTotpEnabled, field.TypeBool, value)
+	}
+	if value, ok := _u.mutation.TotpEnabledAt(); ok {
+		_spec.SetField(user.FieldTotpEnabledAt, field.TypeTime, value)
+	}
+	if _u.mutation.TotpEnabledAtCleared() {
+		_spec.ClearField(user.FieldTotpEnabledAt, field.TypeTime)
+	}
 	if _u.mutation.APIKeysCleared() {
 		edge := &sqlgraph.EdgeSpec{
 			Rel:     sqlgraph.O2M,
@@ -1147,6 +1216,60 @@ func (_u *UserUpdateOne) SetNillableNotes(v *string) *UserUpdateOne {
 	return _u
 }
 
+// SetTotpSecretEncrypted sets the "totp_secret_encrypted" field.
+func (_u *UserUpdateOne) SetTotpSecretEncrypted(v string) *UserUpdateOne {
+	_u.mutation.SetTotpSecretEncrypted(v)
+	return _u
+}
+
+// SetNillableTotpSecretEncrypted sets the "totp_secret_encrypted" field if the given value is not nil.
+func (_u *UserUpdateOne) SetNillableTotpSecretEncrypted(v *string) *UserUpdateOne {
+	if v != nil {
+		_u.SetTotpSecretEncrypted(*v)
+	}
+	return _u
+}
+
+// ClearTotpSecretEncrypted clears the value of the "totp_secret_encrypted" field.
+func (_u *UserUpdateOne) ClearTotpSecretEncrypted() *UserUpdateOne {
+	_u.mutation.ClearTotpSecretEncrypted()
+	return _u
+}
+
+// SetTotpEnabled sets the "totp_enabled" field.
+func (_u *UserUpdateOne) SetTotpEnabled(v bool) *UserUpdateOne {
+	_u.mutation.SetTotpEnabled(v)
+	return _u
+}
+
+// SetNillableTotpEnabled sets the "totp_enabled" field if the given value is not nil.
+func (_u *UserUpdateOne) SetNillableTotpEnabled(v *bool) *UserUpdateOne {
+	if v != nil {
+		_u.SetTotpEnabled(*v)
+	}
+	return _u
+}
+
+// SetTotpEnabledAt sets the "totp_enabled_at" field.
+func (_u *UserUpdateOne) SetTotpEnabledAt(v time.Time) *UserUpdateOne {
+	_u.mutation.SetTotpEnabledAt(v)
+	return _u
+}
+
+// SetNillableTotpEnabledAt sets the "totp_enabled_at" field if the given value is not nil.
+func (_u *UserUpdateOne) SetNillableTotpEnabledAt(v *time.Time) *UserUpdateOne {
+	if v != nil {
+		_u.SetTotpEnabledAt(*v)
+	}
+	return _u
+}
+
+// ClearTotpEnabledAt clears the value of the "totp_enabled_at" field.
+func (_u *UserUpdateOne) ClearTotpEnabledAt() *UserUpdateOne {
+	_u.mutation.ClearTotpEnabledAt()
+	return _u
+}
+
 // AddAPIKeyIDs adds the "api_keys" edge to the APIKey entity by IDs.
 func (_u *UserUpdateOne) AddAPIKeyIDs(ids ...int64) *UserUpdateOne {
 	_u.mutation.AddAPIKeyIDs(ids...)
@@ -1593,6 +1716,21 @@ func (_u *UserUpdateOne) sqlSave(ctx context.Context) (_node *User, err error) {
 	if value, ok := _u.mutation.Notes(); ok {
 		_spec.SetField(user.FieldNotes, field.TypeString, value)
 	}
+	if value, ok := _u.mutation.TotpSecretEncrypted(); ok {
+		_spec.SetField(user.FieldTotpSecretEncrypted, field.TypeString, value)
+	}
+	if _u.mutation.TotpSecretEncryptedCleared() {
+		_spec.ClearField(user.FieldTotpSecretEncrypted, field.TypeString)
+	}
+	if value, ok := _u.mutation.TotpEnabled(); ok {
+		_spec.SetField(user.FieldTotpEnabled, field.TypeBool, value)
+	}
+	if value, ok := _u.mutation.TotpEnabledAt(); ok {
+		_spec.SetField(user.FieldTotpEnabledAt, field.TypeTime, value)
+	}
+	if _u.mutation.TotpEnabledAtCleared() {
+		_spec.ClearField(user.FieldTotpEnabledAt, field.TypeTime)
+	}
 	if _u.mutation.APIKeysCleared() {
 		edge := &sqlgraph.EdgeSpec{
 			Rel:     sqlgraph.O2M,

backend/go.mod

@@ -37,6 +37,7 @@ require (
 	github.com/andybalholm/brotli v1.2.0 // indirect
 	github.com/apparentlymart/go-textseg/v15 v15.0.0 // indirect
 	github.com/bmatcuk/doublestar v1.3.4 // indirect
+	github.com/boombuler/barcode v1.0.1-0.20190219062509-6c824513bacc // indirect
 	github.com/bytedance/sonic v1.9.1 // indirect
 	github.com/cenkalti/backoff/v4 v4.3.0 // indirect
 	github.com/cespare/xxhash/v2 v2.3.0 // indirect
@@ -106,6 +107,7 @@ require (
 	github.com/pkg/errors v0.9.1 // indirect
 	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
 	github.com/power-devops/perfstat v0.0.0-20210106213030-5aafc221ea8c // indirect
+	github.com/pquerna/otp v1.5.0 // indirect
 	github.com/quic-go/qpack v0.6.0 // indirect
 	github.com/quic-go/quic-go v0.57.1 // indirect
 	github.com/refraction-networking/utls v1.8.1 // indirect

backend/go.sum

@@ -20,6 +20,8 @@ github.com/apparentlymart/go-textseg/v15 v15.0.0 h1:uYvfpb3DyLSCGWnctWKGj857c6ew
 github.com/apparentlymart/go-textseg/v15 v15.0.0/go.mod h1:K8XmNZdhEBkdlyDdvbmmsvpAG721bKi0joRfFdHIWJ4=
 github.com/bmatcuk/doublestar v1.3.4 h1:gPypJ5xD31uhX6Tf54sDPUOBXTqKH4c9aPY66CyQrS0=
 github.com/bmatcuk/doublestar v1.3.4/go.mod h1:wiQtGV+rzVYxB7WIlirSN++5HPtPlXEo9MEoZQC/PmE=
+github.com/boombuler/barcode v1.0.1-0.20190219062509-6c824513bacc h1:biVzkmvwrH8WK8raXaxBx6fRVTlJILwEwQGL1I/ByEI=
+github.com/boombuler/barcode v1.0.1-0.20190219062509-6c824513bacc/go.mod h1:paBWMcWSl3LHKBqUq+rly7CNSldXjb2rDl3JlRe0mD8=
 github.com/bsm/ginkgo/v2 v2.12.0 h1:Ny8MWAHyOepLGlLKYmXG4IEkioBysk6GpaRTLC8zwWs=
 github.com/bsm/ginkgo/v2 v2.12.0/go.mod h1:SwYbGRRDovPVboqFv0tPTcG1sN61LM1Z4ARdbAV9g4c=
 github.com/bsm/gomega v1.27.10 h1:yeMWxP2pV2fG3FgAODIY8EiRE3dy0aeFYt4l7wh6yKA=
@@ -217,6 +219,8 @@ github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRI
 github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/power-devops/perfstat v0.0.0-20210106213030-5aafc221ea8c h1:ncq/mPwQF4JjgDlrVEn3C11VoGHZN7m8qihwgMEtzYw=
 github.com/power-devops/perfstat v0.0.0-20210106213030-5aafc221ea8c/go.mod h1:OmDBASR4679mdNQnz2pUhc2G8CO2JrUAVFDRBDP/hJE=
+github.com/pquerna/otp v1.5.0 h1:NMMR+WrmaqXU4EzdGJEE1aUUI0AMRzsp96fFFWNPwxs=
+github.com/pquerna/otp v1.5.0/go.mod h1:dkJfzwRKNiegxyNb54X/3fLwhCynbMspSyWKnvi1AEg=
 github.com/prashantv/gostub v1.1.0 h1:BTyx3RfQjRHnUWaGF9oQos79AlQ5k8WNktv7VGvVH4g=
 github.com/prashantv/gostub v1.1.0/go.mod h1:A5zLQHz7ieHGG7is6LLXLz7I8+3LZzsrV0P1IAHhP5U=
 github.com/quic-go/qpack v0.6.0 h1:g7W+BMYynC1LbYLSqRt8PBg5Tgwxn214ZZR34VIOjz8=

backend/internal/config/config.go

@@ -47,6 +47,7 @@ type Config struct {
 	Redis        RedisConfig                `mapstructure:"redis"`
 	Ops          OpsConfig                  `mapstructure:"ops"`
 	JWT          JWTConfig                  `mapstructure:"jwt"`
+	Totp         TotpConfig                 `mapstructure:"totp"`
 	LinuxDo      LinuxDoConnectConfig       `mapstructure:"linuxdo_connect"`
 	Default      DefaultConfig              `mapstructure:"default"`
 	RateLimit    RateLimitConfig            `mapstructure:"rate_limit"`
@@ -466,6 +467,16 @@ type JWTConfig struct {
 	ExpireHour int    `mapstructure:"expire_hour"`
 }
 
+// TotpConfig TOTP 双因素认证配置
+type TotpConfig struct {
+	// EncryptionKey 用于加密 TOTP 密钥的 AES-256 密钥（32 字节 hex 编码）
+	// 如果为空，将自动生成一个随机密钥（仅适用于开发环境）
+	EncryptionKey string `mapstructure:"encryption_key"`
+	// EncryptionKeyConfigured 标记加密密钥是否为手动配置（非自动生成）
+	// 只有手动配置了密钥才允许在管理后台启用 TOTP 功能
+	EncryptionKeyConfigured bool `mapstructure:"-"`
+}
+
 type TurnstileConfig struct {
 	Required bool `mapstructure:"required"`
 }
@@ -626,6 +637,20 @@ func Load() (*Config, error) {
 		log.Println("Warning: JWT secret auto-generated. Consider setting a fixed secret for production.")
 	}
 
+	// Auto-generate TOTP encryption key if not set (32 bytes = 64 hex chars for AES-256)
+	cfg.Totp.EncryptionKey = strings.TrimSpace(cfg.Totp.EncryptionKey)
+	if cfg.Totp.EncryptionKey == "" {
+		key, err := generateJWTSecret(32) // Reuse the same random generation function
+		if err != nil {
+			return nil, fmt.Errorf("generate totp encryption key error: %w", err)
+		}
+		cfg.Totp.EncryptionKey = key
+		cfg.Totp.EncryptionKeyConfigured = false
+		log.Println("Warning: TOTP encryption key auto-generated. Consider setting a fixed key for production.")
+	} else {
+		cfg.Totp.EncryptionKeyConfigured = true
+	}
+
 	if err := cfg.Validate(); err != nil {
 		return nil, fmt.Errorf("validate config error: %w", err)
 	}
@@ -756,6 +781,9 @@ func setDefaults() {
 	viper.SetDefault("jwt.secret", "")
 	viper.SetDefault("jwt.expire_hour", 24)
 
+	// TOTP
+	viper.SetDefault("totp.encryption_key", "")
+
 	// Default
 	// Admin credentials are created via the setup flow (web wizard / CLI / AUTO_SETUP).
 	// Do not ship fixed defaults here to avoid insecure "known credentials" in production.

backend/internal/handler/admin/setting_handler.go

@@ -49,6 +49,8 @@ func (h *SettingHandler) GetSettings(c *gin.Context) {
 		EmailVerifyEnabled:                   settings.EmailVerifyEnabled,
 		PromoCodeEnabled:                     settings.PromoCodeEnabled,
 		PasswordResetEnabled:                 settings.PasswordResetEnabled,
+		TotpEnabled:                          settings.TotpEnabled,
+		TotpEncryptionKeyConfigured:          h.settingService.IsTotpEncryptionKeyConfigured(),
 		SMTPHost:                             settings.SMTPHost,
 		SMTPPort:                             settings.SMTPPort,
 		SMTPUsername:                         settings.SMTPUsername,
@@ -94,6 +96,7 @@ type UpdateSettingsRequest struct {
 	EmailVerifyEnabled   bool `json:"email_verify_enabled"`
 	PromoCodeEnabled     bool `json:"promo_code_enabled"`
 	PasswordResetEnabled bool `json:"password_reset_enabled"`
+	TotpEnabled          bool `json:"totp_enabled"` // TOTP 双因素认证
 
 	// 邮件服务设置
 	SMTPHost     string `json:"smtp_host"`
@@ -200,6 +203,16 @@ func (h *SettingHandler) UpdateSettings(c *gin.Context) {
 		}
 	}
 
+	// TOTP 双因素认证参数验证
+	// 只有手动配置了加密密钥才允许启用 TOTP 功能
+	if req.TotpEnabled && !previousSettings.TotpEnabled {
+		// 尝试启用 TOTP，检查加密密钥是否已手动配置
+		if !h.settingService.IsTotpEncryptionKeyConfigured() {
+			response.BadRequest(c, "Cannot enable TOTP: TOTP_ENCRYPTION_KEY environment variable must be configured first. Generate a key with 'openssl rand -hex 32' and set it in your environment.")
+			return
+		}
+	}
+
 	// LinuxDo Connect 参数验证
 	if req.LinuxDoConnectEnabled {
 		req.LinuxDoConnectClientID = strings.TrimSpace(req.LinuxDoConnectClientID)
@@ -246,6 +259,7 @@ func (h *SettingHandler) UpdateSettings(c *gin.Context) {
 		EmailVerifyEnabled:         req.EmailVerifyEnabled,
 		PromoCodeEnabled:           req.PromoCodeEnabled,
 		PasswordResetEnabled:       req.PasswordResetEnabled,
+		TotpEnabled:                req.TotpEnabled,
 		SMTPHost:                   req.SMTPHost,
 		SMTPPort:                   req.SMTPPort,
 		SMTPUsername:               req.SMTPUsername,
@@ -322,6 +336,8 @@ func (h *SettingHandler) UpdateSettings(c *gin.Context) {
 		EmailVerifyEnabled:                   updatedSettings.EmailVerifyEnabled,
 		PromoCodeEnabled:                     updatedSettings.PromoCodeEnabled,
 		PasswordResetEnabled:                 updatedSettings.PasswordResetEnabled,
+		TotpEnabled:                          updatedSettings.TotpEnabled,
+		TotpEncryptionKeyConfigured:          h.settingService.IsTotpEncryptionKeyConfigured(),
 		SMTPHost:                             updatedSettings.SMTPHost,
 		SMTPPort:                             updatedSettings.SMTPPort,
 		SMTPUsername:                         updatedSettings.SMTPUsername,
@@ -391,6 +407,9 @@ func diffSettings(before *service.SystemSettings, after *service.SystemSettings,
 	if before.PasswordResetEnabled != after.PasswordResetEnabled {
 		changed = append(changed, "password_reset_enabled")
 	}
+	if before.TotpEnabled != after.TotpEnabled {
+		changed = append(changed, "totp_enabled")
+	}
 	if before.SMTPHost != after.SMTPHost {
 		changed = append(changed, "smtp_host")
 	}

backend/internal/handler/auth_handler.go

@@ -1,6 +1,8 @@
 package handler
 
 import (
+	"log/slog"
+
 	"github.com/Wei-Shaw/sub2api/internal/config"
 	"github.com/Wei-Shaw/sub2api/internal/handler/dto"
 	"github.com/Wei-Shaw/sub2api/internal/pkg/ip"
@@ -18,16 +20,18 @@ type AuthHandler struct {
 	userService  *service.UserService
 	settingSvc   *service.SettingService
 	promoService *service.PromoService
+	totpService  *service.TotpService
 }
 
 // NewAuthHandler creates a new AuthHandler
-func NewAuthHandler(cfg *config.Config, authService *service.AuthService, userService *service.UserService, settingService *service.SettingService, promoService *service.PromoService) *AuthHandler {
+func NewAuthHandler(cfg *config.Config, authService *service.AuthService, userService *service.UserService, settingService *service.SettingService, promoService *service.PromoService, totpService *service.TotpService) *AuthHandler {
 	return &AuthHandler{
 		cfg:          cfg,
 		authService:  authService,
 		userService:  userService,
 		settingSvc:   settingService,
 		promoService: promoService,
+		totpService:  totpService,
 	}
 }
 
@@ -144,6 +148,100 @@ func (h *AuthHandler) Login(c *gin.Context) {
 		return
 	}
 
+	// Check if TOTP 2FA is enabled for this user
+	if h.totpService != nil && h.settingSvc.IsTotpEnabled(c.Request.Context()) && user.TotpEnabled {
+		// Create a temporary login session for 2FA
+		tempToken, err := h.totpService.CreateLoginSession(c.Request.Context(), user.ID, user.Email)
+		if err != nil {
+			response.InternalError(c, "Failed to create 2FA session")
+			return
+		}
+
+		response.Success(c, TotpLoginResponse{
+			Requires2FA:     true,
+			TempToken:       tempToken,
+			UserEmailMasked: service.MaskEmail(user.Email),
+		})
+		return
+	}
+
+	response.Success(c, AuthResponse{
+		AccessToken: token,
+		TokenType:   "Bearer",
+		User:        dto.UserFromService(user),
+	})
+}
+
+// TotpLoginResponse represents the response when 2FA is required
+type TotpLoginResponse struct {
+	Requires2FA     bool   `json:"requires_2fa"`
+	TempToken       string `json:"temp_token,omitempty"`
+	UserEmailMasked string `json:"user_email_masked,omitempty"`
+}
+
+// Login2FARequest represents the 2FA login request
+type Login2FARequest struct {
+	TempToken string `json:"temp_token" binding:"required"`
+	TotpCode  string `json:"totp_code" binding:"required,len=6"`
+}
+
+// Login2FA completes the login with 2FA verification
+// POST /api/v1/auth/login/2fa
+func (h *AuthHandler) Login2FA(c *gin.Context) {
+	var req Login2FARequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	slog.Debug("login_2fa_request",
+		"temp_token_len", len(req.TempToken),
+		"totp_code_len", len(req.TotpCode))
+
+	// Get the login session
+	session, err := h.totpService.GetLoginSession(c.Request.Context(), req.TempToken)
+	if err != nil || session == nil {
+		tokenPrefix := ""
+		if len(req.TempToken) >= 8 {
+			tokenPrefix = req.TempToken[:8]
+		}
+		slog.Debug("login_2fa_session_invalid",
+			"temp_token_prefix", tokenPrefix,
+			"error", err)
+		response.BadRequest(c, "Invalid or expired 2FA session")
+		return
+	}
+
+	slog.Debug("login_2fa_session_found",
+		"user_id", session.UserID,
+		"email", session.Email)
+
+	// Verify the TOTP code
+	if err := h.totpService.VerifyCode(c.Request.Context(), session.UserID, req.TotpCode); err != nil {
+		slog.Debug("login_2fa_verify_failed",
+			"user_id", session.UserID,
+			"error", err)
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	// Delete the login session
+	_ = h.totpService.DeleteLoginSession(c.Request.Context(), req.TempToken)
+
+	// Get the user
+	user, err := h.userService.GetByID(c.Request.Context(), session.UserID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	// Generate the JWT token
+	token, err := h.authService.GenerateToken(user)
+	if err != nil {
+		response.InternalError(c, "Failed to generate token")
+		return
+	}
+
 	response.Success(c, AuthResponse{
 		AccessToken: token,
 		TokenType:   "Bearer",

backend/internal/handler/dto/settings.go

@@ -6,6 +6,8 @@ type SystemSettings struct {
 	EmailVerifyEnabled          bool `json:"email_verify_enabled"`
 	PromoCodeEnabled            bool `json:"promo_code_enabled"`
 	PasswordResetEnabled        bool `json:"password_reset_enabled"`
+	TotpEnabled                 bool `json:"totp_enabled"`                   // TOTP 双因素认证
+	TotpEncryptionKeyConfigured bool `json:"totp_encryption_key_configured"` // TOTP 加密密钥是否已配置
 
 	SMTPHost               string `json:"smtp_host"`
 	SMTPPort               int    `json:"smtp_port"`
@@ -59,6 +61,7 @@ type PublicSettings struct {
 	EmailVerifyEnabled   bool   `json:"email_verify_enabled"`
 	PromoCodeEnabled     bool   `json:"promo_code_enabled"`
 	PasswordResetEnabled bool   `json:"password_reset_enabled"`
+	TotpEnabled          bool   `json:"totp_enabled"` // TOTP 双因素认证
 	TurnstileEnabled     bool   `json:"turnstile_enabled"`
 	TurnstileSiteKey     string `json:"turnstile_site_key"`
 	SiteName             string `json:"site_name"`

backend/internal/handler/handler.go

@@ -37,6 +37,7 @@ type Handlers struct {
 	Gateway       *GatewayHandler
 	OpenAIGateway *OpenAIGatewayHandler
 	Setting       *SettingHandler
+	Totp          *TotpHandler
 }
 
 // BuildInfo contains build-time information

backend/internal/handler/totp_handler.go

@@ -0,0 +1,181 @@
+package handler
+
+import (
+	"github.com/gin-gonic/gin"
+
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	middleware2 "github.com/Wei-Shaw/sub2api/internal/server/middleware"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+)
+
+// TotpHandler handles TOTP-related requests
+type TotpHandler struct {
+	totpService *service.TotpService
+}
+
+// NewTotpHandler creates a new TotpHandler
+func NewTotpHandler(totpService *service.TotpService) *TotpHandler {
+	return &TotpHandler{
+		totpService: totpService,
+	}
+}
+
+// TotpStatusResponse represents the TOTP status response
+type TotpStatusResponse struct {
+	Enabled        bool   `json:"enabled"`
+	EnabledAt      *int64 `json:"enabled_at,omitempty"` // Unix timestamp
+	FeatureEnabled bool   `json:"feature_enabled"`
+}
+
+// GetStatus returns the TOTP status for the current user
+// GET /api/v1/user/totp/status
+func (h *TotpHandler) GetStatus(c *gin.Context) {
+	subject, ok := middleware2.GetAuthSubjectFromContext(c)
+	if !ok {
+		response.Unauthorized(c, "User not authenticated")
+		return
+	}
+
+	status, err := h.totpService.GetStatus(c.Request.Context(), subject.UserID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	resp := TotpStatusResponse{
+		Enabled:        status.Enabled,
+		FeatureEnabled: status.FeatureEnabled,
+	}
+
+	if status.EnabledAt != nil {
+		ts := status.EnabledAt.Unix()
+		resp.EnabledAt = &ts
+	}
+
+	response.Success(c, resp)
+}
+
+// TotpSetupRequest represents the request to initiate TOTP setup
+type TotpSetupRequest struct {
+	EmailCode string `json:"email_code"`
+	Password  string `json:"password"`
+}
+
+// TotpSetupResponse represents the TOTP setup response
+type TotpSetupResponse struct {
+	Secret     string `json:"secret"`
+	QRCodeURL  string `json:"qr_code_url"`
+	SetupToken string `json:"setup_token"`
+	Countdown  int    `json:"countdown"`
+}
+
+// InitiateSetup starts the TOTP setup process
+// POST /api/v1/user/totp/setup
+func (h *TotpHandler) InitiateSetup(c *gin.Context) {
+	subject, ok := middleware2.GetAuthSubjectFromContext(c)
+	if !ok {
+		response.Unauthorized(c, "User not authenticated")
+		return
+	}
+
+	var req TotpSetupRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		// Allow empty body (optional params)
+		req = TotpSetupRequest{}
+	}
+
+	result, err := h.totpService.InitiateSetup(c.Request.Context(), subject.UserID, req.EmailCode, req.Password)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, TotpSetupResponse{
+		Secret:     result.Secret,
+		QRCodeURL:  result.QRCodeURL,
+		SetupToken: result.SetupToken,
+		Countdown:  result.Countdown,
+	})
+}
+
+// TotpEnableRequest represents the request to enable TOTP
+type TotpEnableRequest struct {
+	TotpCode   string `json:"totp_code" binding:"required,len=6"`
+	SetupToken string `json:"setup_token" binding:"required"`
+}
+
+// Enable completes the TOTP setup
+// POST /api/v1/user/totp/enable
+func (h *TotpHandler) Enable(c *gin.Context) {
+	subject, ok := middleware2.GetAuthSubjectFromContext(c)
+	if !ok {
+		response.Unauthorized(c, "User not authenticated")
+		return
+	}
+
+	var req TotpEnableRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	if err := h.totpService.CompleteSetup(c.Request.Context(), subject.UserID, req.TotpCode, req.SetupToken); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, gin.H{"success": true})
+}
+
+// TotpDisableRequest represents the request to disable TOTP
+type TotpDisableRequest struct {
+	EmailCode string `json:"email_code"`
+	Password  string `json:"password"`
+}
+
+// Disable disables TOTP for the current user
+// POST /api/v1/user/totp/disable
+func (h *TotpHandler) Disable(c *gin.Context) {
+	subject, ok := middleware2.GetAuthSubjectFromContext(c)
+	if !ok {
+		response.Unauthorized(c, "User not authenticated")
+		return
+	}
+
+	var req TotpDisableRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	if err := h.totpService.Disable(c.Request.Context(), subject.UserID, req.EmailCode, req.Password); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, gin.H{"success": true})
+}
+
+// GetVerificationMethod returns the verification method for TOTP operations
+// GET /api/v1/user/totp/verification-method
+func (h *TotpHandler) GetVerificationMethod(c *gin.Context) {
+	method := h.totpService.GetVerificationMethod(c.Request.Context())
+	response.Success(c, method)
+}
+
+// SendVerifyCode sends an email verification code for TOTP operations
+// POST /api/v1/user/totp/send-code
+func (h *TotpHandler) SendVerifyCode(c *gin.Context) {
+	subject, ok := middleware2.GetAuthSubjectFromContext(c)
+	if !ok {
+		response.Unauthorized(c, "User not authenticated")
+		return
+	}
+
+	if err := h.totpService.SendVerifyCode(c.Request.Context(), subject.UserID); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, gin.H{"success": true})
+}

backend/internal/handler/wire.go

@@ -70,6 +70,7 @@ func ProvideHandlers(
 	gatewayHandler *GatewayHandler,
 	openaiGatewayHandler *OpenAIGatewayHandler,
 	settingHandler *SettingHandler,
+	totpHandler *TotpHandler,
 ) *Handlers {
 	return &Handlers{
 		Auth:          authHandler,
@@ -82,6 +83,7 @@ func ProvideHandlers(
 		Gateway:       gatewayHandler,
 		OpenAIGateway: openaiGatewayHandler,
 		Setting:       settingHandler,
+		Totp:          totpHandler,
 	}
 }
 
@@ -96,6 +98,7 @@ var ProviderSet = wire.NewSet(
 	NewSubscriptionHandler,
 	NewGatewayHandler,
 	NewOpenAIGatewayHandler,
+	NewTotpHandler,
 	ProvideSettingHandler,
 
 	// Admin handlers

backend/internal/pkg/tlsfingerprint/dialer_integration_test.go

@@ -0,0 +1,278 @@
+//go:build integration
+
+// Package tlsfingerprint provides TLS fingerprint simulation for HTTP clients.
+//
+// Integration tests for verifying TLS fingerprint correctness.
+// These tests make actual network requests to external services and should be run manually.
+//
+// Run with: go test -v -tags=integration ./internal/pkg/tlsfingerprint/...
+package tlsfingerprint
+
+import (
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+	"strings"
+	"testing"
+	"time"
+)
+
+// skipIfExternalServiceUnavailable checks if the external service is available.
+// If not, it skips the test instead of failing.
+func skipIfExternalServiceUnavailable(t *testing.T, err error) {
+	t.Helper()
+	if err != nil {
+		// Check for common network/TLS errors that indicate external service issues
+		errStr := err.Error()
+		if strings.Contains(errStr, "certificate has expired") ||
+			strings.Contains(errStr, "certificate is not yet valid") ||
+			strings.Contains(errStr, "connection refused") ||
+			strings.Contains(errStr, "no such host") ||
+			strings.Contains(errStr, "network is unreachable") ||
+			strings.Contains(errStr, "timeout") {
+			t.Skipf("skipping test: external service unavailable: %v", err)
+		}
+		t.Fatalf("failed to get fingerprint: %v", err)
+	}
+}
+
+// TestJA3Fingerprint verifies the JA3/JA4 fingerprint matches expected value.
+// This test uses tls.peet.ws to verify the fingerprint.
+// Expected JA3 hash: 1a28e69016765d92e3b381168d68922c (Claude CLI / Node.js 20.x)
+// Expected JA4: t13d5911h1_a33745022dd6_1f22a2ca17c4 (d=domain) or t13i5911h1_... (i=IP)
+func TestJA3Fingerprint(t *testing.T) {
+	// Skip if network is unavailable or if running in short mode
+	if testing.Short() {
+		t.Skip("skipping integration test in short mode")
+	}
+
+	profile := &Profile{
+		Name:         "Claude CLI Test",
+		EnableGREASE: false,
+	}
+	dialer := NewDialer(profile, nil)
+
+	client := &http.Client{
+		Transport: &http.Transport{
+			DialTLSContext: dialer.DialTLSContext,
+		},
+		Timeout: 30 * time.Second,
+	}
+
+	// Use tls.peet.ws fingerprint detection API
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer cancel()
+
+	req, err := http.NewRequestWithContext(ctx, "GET", "https://tls.peet.ws/api/all", nil)
+	if err != nil {
+		t.Fatalf("failed to create request: %v", err)
+	}
+	req.Header.Set("User-Agent", "Claude Code/2.0.0 Node.js/20.0.0")
+
+	resp, err := client.Do(req)
+	skipIfExternalServiceUnavailable(t, err)
+	defer func() { _ = resp.Body.Close() }()
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		t.Fatalf("failed to read response: %v", err)
+	}
+
+	var fpResp FingerprintResponse
+	if err := json.Unmarshal(body, &fpResp); err != nil {
+		t.Logf("Response body: %s", string(body))
+		t.Fatalf("failed to parse fingerprint response: %v", err)
+	}
+
+	// Log all fingerprint information
+	t.Logf("JA3: %s", fpResp.TLS.JA3)
+	t.Logf("JA3 Hash: %s", fpResp.TLS.JA3Hash)
+	t.Logf("JA4: %s", fpResp.TLS.JA4)
+	t.Logf("PeetPrint: %s", fpResp.TLS.PeetPrint)
+	t.Logf("PeetPrint Hash: %s", fpResp.TLS.PeetPrintHash)
+
+	// Verify JA3 hash matches expected value
+	expectedJA3Hash := "1a28e69016765d92e3b381168d68922c"
+	if fpResp.TLS.JA3Hash == expectedJA3Hash {
+		t.Logf("✓ JA3 hash matches expected value: %s", expectedJA3Hash)
+	} else {
+		t.Errorf("✗ JA3 hash mismatch: got %s, expected %s", fpResp.TLS.JA3Hash, expectedJA3Hash)
+	}
+
+	// Verify JA4 fingerprint
+	// JA4 format: t[version][sni][cipher_count][ext_count][alpn]_[cipher_hash]_[ext_hash]
+	// Expected: t13d5910h1 (d=domain) or t13i5910h1 (i=IP)
+	// The suffix _a33745022dd6_1f22a2ca17c4 should match
+	expectedJA4Suffix := "_a33745022dd6_1f22a2ca17c4"
+	if strings.HasSuffix(fpResp.TLS.JA4, expectedJA4Suffix) {
+		t.Logf("✓ JA4 suffix matches expected value: %s", expectedJA4Suffix)
+	} else {
+		t.Errorf("✗ JA4 suffix mismatch: got %s, expected suffix %s", fpResp.TLS.JA4, expectedJA4Suffix)
+	}
+
+	// Verify JA4 prefix (t13d5911h1 or t13i5911h1)
+	// d = domain (SNI present), i = IP (no SNI)
+	// Since we connect to tls.peet.ws (domain), we expect 'd'
+	expectedJA4Prefix := "t13d5911h1"
+	if strings.HasPrefix(fpResp.TLS.JA4, expectedJA4Prefix) {
+		t.Logf("✓ JA4 prefix matches: %s (t13=TLS1.3, d=domain, 59=ciphers, 11=extensions, h1=HTTP/1.1)", expectedJA4Prefix)
+	} else {
+		// Also accept 'i' variant for IP connections
+		altPrefix := "t13i5911h1"
+		if strings.HasPrefix(fpResp.TLS.JA4, altPrefix) {
+			t.Logf("✓ JA4 prefix matches (IP variant): %s", altPrefix)
+		} else {
+			t.Errorf("✗ JA4 prefix mismatch: got %s, expected %s or %s", fpResp.TLS.JA4, expectedJA4Prefix, altPrefix)
+		}
+	}
+
+	// Verify JA3 contains expected cipher suites (TLS 1.3 ciphers at the beginning)
+	if strings.Contains(fpResp.TLS.JA3, "4866-4867-4865") {
+		t.Logf("✓ JA3 contains expected TLS 1.3 cipher suites")
+	} else {
+		t.Logf("Warning: JA3 does not contain expected TLS 1.3 cipher suites")
+	}
+
+	// Verify extension list (should be 11 extensions including SNI)
+	// Expected: 0-11-10-35-16-22-23-13-43-45-51
+	expectedExtensions := "0-11-10-35-16-22-23-13-43-45-51"
+	if strings.Contains(fpResp.TLS.JA3, expectedExtensions) {
+		t.Logf("✓ JA3 contains expected extension list: %s", expectedExtensions)
+	} else {
+		t.Logf("Warning: JA3 extension list may differ")
+	}
+}
+
+// TestProfileExpectation defines expected fingerprint values for a profile.
+type TestProfileExpectation struct {
+	Profile       *Profile
+	ExpectedJA3   string // Expected JA3 hash (empty = don't check)
+	ExpectedJA4   string // Expected full JA4 (empty = don't check)
+	JA4CipherHash string // Expected JA4 cipher hash - the stable middle part (empty = don't check)
+}
+
+// TestAllProfiles tests multiple TLS fingerprint profiles against tls.peet.ws.
+// Run with: go test -v -tags=integration -run TestAllProfiles ./internal/pkg/tlsfingerprint/...
+func TestAllProfiles(t *testing.T) {
+	if testing.Short() {
+		t.Skip("skipping integration test in short mode")
+	}
+
+	// Define all profiles to test with their expected fingerprints
+	// These profiles are from config.yaml gateway.tls_fingerprint.profiles
+	profiles := []TestProfileExpectation{
+		{
+			// Linux x64 Node.js v22.17.1
+			// Expected JA3 Hash: 1a28e69016765d92e3b381168d68922c
+			// Expected JA4: t13d5911h1_a33745022dd6_1f22a2ca17c4
+			Profile: &Profile{
+				Name:         "linux_x64_node_v22171",
+				EnableGREASE: false,
+				CipherSuites: []uint16{4866, 4867, 4865, 49199, 49195, 49200, 49196, 158, 49191, 103, 49192, 107, 163, 159, 52393, 52392, 52394, 49327, 49325, 49315, 49311, 49245, 49249, 49239, 49235, 162, 49326, 49324, 49314, 49310, 49244, 49248, 49238, 49234, 49188, 106, 49187, 64, 49162, 49172, 57, 56, 49161, 49171, 51, 50, 157, 49313, 49309, 49233, 156, 49312, 49308, 49232, 61, 60, 53, 47, 255},
+				Curves:       []uint16{29, 23, 30, 25, 24, 256, 257, 258, 259, 260},
+				PointFormats: []uint8{0, 1, 2},
+			},
+			JA4CipherHash: "a33745022dd6", // stable part
+		},
+		{
+			// MacOS arm64 Node.js v22.18.0
+			// Expected JA3 Hash: 70cb5ca646080902703ffda87036a5ea
+			// Expected JA4: t13d5912h1_a33745022dd6_dbd39dd1d406
+			Profile: &Profile{
+				Name:         "macos_arm64_node_v22180",
+				EnableGREASE: false,
+				CipherSuites: []uint16{4866, 4867, 4865, 49199, 49195, 49200, 49196, 158, 49191, 103, 49192, 107, 163, 159, 52393, 52392, 52394, 49327, 49325, 49315, 49311, 49245, 49249, 49239, 49235, 162, 49326, 49324, 49314, 49310, 49244, 49248, 49238, 49234, 49188, 106, 49187, 64, 49162, 49172, 57, 56, 49161, 49171, 51, 50, 157, 49313, 49309, 49233, 156, 49312, 49308, 49232, 61, 60, 53, 47, 255},
+				Curves:       []uint16{29, 23, 30, 25, 24, 256, 257, 258, 259, 260},
+				PointFormats: []uint8{0, 1, 2},
+			},
+			JA4CipherHash: "a33745022dd6", // stable part (same cipher suites)
+		},
+	}
+
+	for _, tc := range profiles {
+		tc := tc // capture range variable
+		t.Run(tc.Profile.Name, func(t *testing.T) {
+			fp := fetchFingerprint(t, tc.Profile)
+			if fp == nil {
+				return // fetchFingerprint already called t.Fatal
+			}
+
+			t.Logf("Profile: %s", tc.Profile.Name)
+			t.Logf("  JA3:           %s", fp.JA3)
+			t.Logf("  JA3 Hash:      %s", fp.JA3Hash)
+			t.Logf("  JA4:           %s", fp.JA4)
+			t.Logf("  PeetPrint:     %s", fp.PeetPrint)
+			t.Logf("  PeetPrintHash: %s", fp.PeetPrintHash)
+
+			// Verify expectations
+			if tc.ExpectedJA3 != "" {
+				if fp.JA3Hash == tc.ExpectedJA3 {
+					t.Logf("  ✓ JA3 hash matches: %s", tc.ExpectedJA3)
+				} else {
+					t.Errorf("  ✗ JA3 hash mismatch: got %s, expected %s", fp.JA3Hash, tc.ExpectedJA3)
+				}
+			}
+
+			if tc.ExpectedJA4 != "" {
+				if fp.JA4 == tc.ExpectedJA4 {
+					t.Logf("  ✓ JA4 matches: %s", tc.ExpectedJA4)
+				} else {
+					t.Errorf("  ✗ JA4 mismatch: got %s, expected %s", fp.JA4, tc.ExpectedJA4)
+				}
+			}
+
+			// Check JA4 cipher hash (stable middle part)
+			// JA4 format: prefix_cipherHash_extHash
+			if tc.JA4CipherHash != "" {
+				if strings.Contains(fp.JA4, "_"+tc.JA4CipherHash+"_") {
+					t.Logf("  ✓ JA4 cipher hash matches: %s", tc.JA4CipherHash)
+				} else {
+					t.Errorf("  ✗ JA4 cipher hash mismatch: got %s, expected cipher hash %s", fp.JA4, tc.JA4CipherHash)
+				}
+			}
+		})
+	}
+}
+
+// fetchFingerprint makes a request to tls.peet.ws and returns the TLS fingerprint info.
+func fetchFingerprint(t *testing.T, profile *Profile) *TLSInfo {
+	t.Helper()
+
+	dialer := NewDialer(profile, nil)
+	client := &http.Client{
+		Transport: &http.Transport{
+			DialTLSContext: dialer.DialTLSContext,
+		},
+		Timeout: 30 * time.Second,
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer cancel()
+
+	req, err := http.NewRequestWithContext(ctx, "GET", "https://tls.peet.ws/api/all", nil)
+	if err != nil {
+		t.Fatalf("failed to create request: %v", err)
+		return nil
+	}
+	req.Header.Set("User-Agent", "Claude Code/2.0.0 Node.js/20.0.0")
+
+	resp, err := client.Do(req)
+	skipIfExternalServiceUnavailable(t, err)
+	defer func() { _ = resp.Body.Close() }()
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		t.Fatalf("failed to read response: %v", err)
+		return nil
+	}
+
+	var fpResp FingerprintResponse
+	if err := json.Unmarshal(body, &fpResp); err != nil {
+		t.Logf("Response body: %s", string(body))
+		t.Fatalf("failed to parse fingerprint response: %v", err)
+		return nil
+	}
+
+	return &fpResp.TLS
+}

backend/internal/pkg/tlsfingerprint/dialer_test.go

@@ -1,21 +1,16 @@
 // Package tlsfingerprint provides TLS fingerprint simulation for HTTP clients.
 //
-// Integration tests for verifying TLS fingerprint correctness.
+// Unit tests for TLS fingerprint dialer.
-// These tests make actual network requests and should be run manually.
+// Integration tests that require external network are in dialer_integration_test.go
+// and require the 'integration' build tag.
 //
-// Run with: go test -v ./internal/pkg/tlsfingerprint/...
+// Run unit tests: go test -v ./internal/pkg/tlsfingerprint/...
-// Run integration tests: go test -v -run TestJA3 ./internal/pkg/tlsfingerprint/...
+// Run integration tests: go test -v -tags=integration ./internal/pkg/tlsfingerprint/...
 package tlsfingerprint
 
 import (
-	"context"
-	"encoding/json"
-	"io"
-	"net/http"
 	"net/url"
-	"strings"
 	"testing"
-	"time"
 )
 
 // FingerprintResponse represents the response from tls.peet.ws/api/all.
@@ -36,148 +31,6 @@ type TLSInfo struct {
 	SessionID     string `json:"session_id"`
 }
 
-// TestDialerBasicConnection tests that the dialer can establish TLS connections.
-func TestDialerBasicConnection(t *testing.T) {
-	if testing.Short() {
-		t.Skip("skipping network test in short mode")
-	}
-
-	// Create a dialer with default profile
-	profile := &Profile{
-		Name:         "Test Profile",
-		EnableGREASE: false,
-	}
-	dialer := NewDialer(profile, nil)
-
-	// Create HTTP client with custom TLS dialer
-	client := &http.Client{
-		Transport: &http.Transport{
-			DialTLSContext: dialer.DialTLSContext,
-		},
-		Timeout: 30 * time.Second,
-	}
-
-	// Make a request to a known HTTPS endpoint
-	resp, err := client.Get("https://www.google.com")
-	if err != nil {
-		t.Fatalf("failed to connect: %v", err)
-	}
-	defer func() { _ = resp.Body.Close() }()
-
-	if resp.StatusCode != http.StatusOK {
-		t.Errorf("expected status 200, got %d", resp.StatusCode)
-	}
-}
-
-// TestJA3Fingerprint verifies the JA3/JA4 fingerprint matches expected value.
-// This test uses tls.peet.ws to verify the fingerprint.
-// Expected JA3 hash: 1a28e69016765d92e3b381168d68922c (Claude CLI / Node.js 20.x)
-// Expected JA4: t13d5911h1_a33745022dd6_1f22a2ca17c4 (d=domain) or t13i5911h1_... (i=IP)
-func TestJA3Fingerprint(t *testing.T) {
-	// Skip if network is unavailable or if running in short mode
-	if testing.Short() {
-		t.Skip("skipping integration test in short mode")
-	}
-
-	profile := &Profile{
-		Name:         "Claude CLI Test",
-		EnableGREASE: false,
-	}
-	dialer := NewDialer(profile, nil)
-
-	client := &http.Client{
-		Transport: &http.Transport{
-			DialTLSContext: dialer.DialTLSContext,
-		},
-		Timeout: 30 * time.Second,
-	}
-
-	// Use tls.peet.ws fingerprint detection API
-	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
-	defer cancel()
-
-	req, err := http.NewRequestWithContext(ctx, "GET", "https://tls.peet.ws/api/all", nil)
-	if err != nil {
-		t.Fatalf("failed to create request: %v", err)
-	}
-	req.Header.Set("User-Agent", "Claude Code/2.0.0 Node.js/20.0.0")
-
-	resp, err := client.Do(req)
-	if err != nil {
-		t.Fatalf("failed to get fingerprint: %v", err)
-	}
-	defer func() { _ = resp.Body.Close() }()
-
-	body, err := io.ReadAll(resp.Body)
-	if err != nil {
-		t.Fatalf("failed to read response: %v", err)
-	}
-
-	var fpResp FingerprintResponse
-	if err := json.Unmarshal(body, &fpResp); err != nil {
-		t.Logf("Response body: %s", string(body))
-		t.Fatalf("failed to parse fingerprint response: %v", err)
-	}
-
-	// Log all fingerprint information
-	t.Logf("JA3: %s", fpResp.TLS.JA3)
-	t.Logf("JA3 Hash: %s", fpResp.TLS.JA3Hash)
-	t.Logf("JA4: %s", fpResp.TLS.JA4)
-	t.Logf("PeetPrint: %s", fpResp.TLS.PeetPrint)
-	t.Logf("PeetPrint Hash: %s", fpResp.TLS.PeetPrintHash)
-
-	// Verify JA3 hash matches expected value
-	expectedJA3Hash := "1a28e69016765d92e3b381168d68922c"
-	if fpResp.TLS.JA3Hash == expectedJA3Hash {
-		t.Logf("✓ JA3 hash matches expected value: %s", expectedJA3Hash)
-	} else {
-		t.Errorf("✗ JA3 hash mismatch: got %s, expected %s", fpResp.TLS.JA3Hash, expectedJA3Hash)
-	}
-
-	// Verify JA4 fingerprint
-	// JA4 format: t[version][sni][cipher_count][ext_count][alpn]_[cipher_hash]_[ext_hash]
-	// Expected: t13d5910h1 (d=domain) or t13i5910h1 (i=IP)
-	// The suffix _a33745022dd6_1f22a2ca17c4 should match
-	expectedJA4Suffix := "_a33745022dd6_1f22a2ca17c4"
-	if strings.HasSuffix(fpResp.TLS.JA4, expectedJA4Suffix) {
-		t.Logf("✓ JA4 suffix matches expected value: %s", expectedJA4Suffix)
-	} else {
-		t.Errorf("✗ JA4 suffix mismatch: got %s, expected suffix %s", fpResp.TLS.JA4, expectedJA4Suffix)
-	}
-
-	// Verify JA4 prefix (t13d5911h1 or t13i5911h1)
-	// d = domain (SNI present), i = IP (no SNI)
-	// Since we connect to tls.peet.ws (domain), we expect 'd'
-	expectedJA4Prefix := "t13d5911h1"
-	if strings.HasPrefix(fpResp.TLS.JA4, expectedJA4Prefix) {
-		t.Logf("✓ JA4 prefix matches: %s (t13=TLS1.3, d=domain, 59=ciphers, 11=extensions, h1=HTTP/1.1)", expectedJA4Prefix)
-	} else {
-		// Also accept 'i' variant for IP connections
-		altPrefix := "t13i5911h1"
-		if strings.HasPrefix(fpResp.TLS.JA4, altPrefix) {
-			t.Logf("✓ JA4 prefix matches (IP variant): %s", altPrefix)
-		} else {
-			t.Errorf("✗ JA4 prefix mismatch: got %s, expected %s or %s", fpResp.TLS.JA4, expectedJA4Prefix, altPrefix)
-		}
-	}
-
-	// Verify JA3 contains expected cipher suites (TLS 1.3 ciphers at the beginning)
-	if strings.Contains(fpResp.TLS.JA3, "4866-4867-4865") {
-		t.Logf("✓ JA3 contains expected TLS 1.3 cipher suites")
-	} else {
-		t.Logf("Warning: JA3 does not contain expected TLS 1.3 cipher suites")
-	}
-
-	// Verify extension list (should be 11 extensions including SNI)
-	// Expected: 0-11-10-35-16-22-23-13-43-45-51
-	expectedExtensions := "0-11-10-35-16-22-23-13-43-45-51"
-	if strings.Contains(fpResp.TLS.JA3, expectedExtensions) {
-		t.Logf("✓ JA3 contains expected extension list: %s", expectedExtensions)
-	} else {
-		t.Logf("Warning: JA3 extension list may differ")
-	}
-}
-
 // TestDialerWithProfile tests that different profiles produce different fingerprints.
 func TestDialerWithProfile(t *testing.T) {
 	// Create two dialers with different profiles
@@ -305,139 +158,3 @@ func mustParseURL(rawURL string) *url.URL {
 	}
 	return u
 }
-
-// TestProfileExpectation defines expected fingerprint values for a profile.
-type TestProfileExpectation struct {
-	Profile       *Profile
-	ExpectedJA3   string // Expected JA3 hash (empty = don't check)
-	ExpectedJA4   string // Expected full JA4 (empty = don't check)
-	JA4CipherHash string // Expected JA4 cipher hash - the stable middle part (empty = don't check)
-}
-
-// TestAllProfiles tests multiple TLS fingerprint profiles against tls.peet.ws.
-// Run with: go test -v -run TestAllProfiles ./internal/pkg/tlsfingerprint/...
-func TestAllProfiles(t *testing.T) {
-	if testing.Short() {
-		t.Skip("skipping integration test in short mode")
-	}
-
-	// Define all profiles to test with their expected fingerprints
-	// These profiles are from config.yaml gateway.tls_fingerprint.profiles
-	profiles := []TestProfileExpectation{
-		{
-			// Linux x64 Node.js v22.17.1
-			// Expected JA3 Hash: 1a28e69016765d92e3b381168d68922c
-			// Expected JA4: t13d5911h1_a33745022dd6_1f22a2ca17c4
-			Profile: &Profile{
-				Name:         "linux_x64_node_v22171",
-				EnableGREASE: false,
-				CipherSuites: []uint16{4866, 4867, 4865, 49199, 49195, 49200, 49196, 158, 49191, 103, 49192, 107, 163, 159, 52393, 52392, 52394, 49327, 49325, 49315, 49311, 49245, 49249, 49239, 49235, 162, 49326, 49324, 49314, 49310, 49244, 49248, 49238, 49234, 49188, 106, 49187, 64, 49162, 49172, 57, 56, 49161, 49171, 51, 50, 157, 49313, 49309, 49233, 156, 49312, 49308, 49232, 61, 60, 53, 47, 255},
-				Curves:       []uint16{29, 23, 30, 25, 24, 256, 257, 258, 259, 260},
-				PointFormats: []uint8{0, 1, 2},
-			},
-			JA4CipherHash: "a33745022dd6", // stable part
-		},
-		{
-			// MacOS arm64 Node.js v22.18.0
-			// Expected JA3 Hash: 70cb5ca646080902703ffda87036a5ea
-			// Expected JA4: t13d5912h1_a33745022dd6_dbd39dd1d406
-			Profile: &Profile{
-				Name:         "macos_arm64_node_v22180",
-				EnableGREASE: false,
-				CipherSuites: []uint16{4866, 4867, 4865, 49199, 49195, 49200, 49196, 158, 49191, 103, 49192, 107, 163, 159, 52393, 52392, 52394, 49327, 49325, 49315, 49311, 49245, 49249, 49239, 49235, 162, 49326, 49324, 49314, 49310, 49244, 49248, 49238, 49234, 49188, 106, 49187, 64, 49162, 49172, 57, 56, 49161, 49171, 51, 50, 157, 49313, 49309, 49233, 156, 49312, 49308, 49232, 61, 60, 53, 47, 255},
-				Curves:       []uint16{29, 23, 30, 25, 24, 256, 257, 258, 259, 260},
-				PointFormats: []uint8{0, 1, 2},
-			},
-			JA4CipherHash: "a33745022dd6", // stable part (same cipher suites)
-		},
-	}
-
-	for _, tc := range profiles {
-		tc := tc // capture range variable
-		t.Run(tc.Profile.Name, func(t *testing.T) {
-			fp := fetchFingerprint(t, tc.Profile)
-			if fp == nil {
-				return // fetchFingerprint already called t.Fatal
-			}
-
-			t.Logf("Profile: %s", tc.Profile.Name)
-			t.Logf("  JA3:           %s", fp.JA3)
-			t.Logf("  JA3 Hash:      %s", fp.JA3Hash)
-			t.Logf("  JA4:           %s", fp.JA4)
-			t.Logf("  PeetPrint:     %s", fp.PeetPrint)
-			t.Logf("  PeetPrintHash: %s", fp.PeetPrintHash)
-
-			// Verify expectations
-			if tc.ExpectedJA3 != "" {
-				if fp.JA3Hash == tc.ExpectedJA3 {
-					t.Logf("  ✓ JA3 hash matches: %s", tc.ExpectedJA3)
-				} else {
-					t.Errorf("  ✗ JA3 hash mismatch: got %s, expected %s", fp.JA3Hash, tc.ExpectedJA3)
-				}
-			}
-
-			if tc.ExpectedJA4 != "" {
-				if fp.JA4 == tc.ExpectedJA4 {
-					t.Logf("  ✓ JA4 matches: %s", tc.ExpectedJA4)
-				} else {
-					t.Errorf("  ✗ JA4 mismatch: got %s, expected %s", fp.JA4, tc.ExpectedJA4)
-				}
-			}
-
-			// Check JA4 cipher hash (stable middle part)
-			// JA4 format: prefix_cipherHash_extHash
-			if tc.JA4CipherHash != "" {
-				if strings.Contains(fp.JA4, "_"+tc.JA4CipherHash+"_") {
-					t.Logf("  ✓ JA4 cipher hash matches: %s", tc.JA4CipherHash)
-				} else {
-					t.Errorf("  ✗ JA4 cipher hash mismatch: got %s, expected cipher hash %s", fp.JA4, tc.JA4CipherHash)
-				}
-			}
-		})
-	}
-}
-
-// fetchFingerprint makes a request to tls.peet.ws and returns the TLS fingerprint info.
-func fetchFingerprint(t *testing.T, profile *Profile) *TLSInfo {
-	t.Helper()
-
-	dialer := NewDialer(profile, nil)
-	client := &http.Client{
-		Transport: &http.Transport{
-			DialTLSContext: dialer.DialTLSContext,
-		},
-		Timeout: 30 * time.Second,
-	}
-
-	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
-	defer cancel()
-
-	req, err := http.NewRequestWithContext(ctx, "GET", "https://tls.peet.ws/api/all", nil)
-	if err != nil {
-		t.Fatalf("failed to create request: %v", err)
-		return nil
-	}
-	req.Header.Set("User-Agent", "Claude Code/2.0.0 Node.js/20.0.0")
-
-	resp, err := client.Do(req)
-	if err != nil {
-		t.Fatalf("failed to get fingerprint: %v", err)
-		return nil
-	}
-	defer func() { _ = resp.Body.Close() }()
-
-	body, err := io.ReadAll(resp.Body)
-	if err != nil {
-		t.Fatalf("failed to read response: %v", err)
-		return nil
-	}
-
-	var fpResp FingerprintResponse
-	if err := json.Unmarshal(body, &fpResp); err != nil {
-		t.Logf("Response body: %s", string(body))
-		t.Fatalf("failed to parse fingerprint response: %v", err)
-		return nil
-	}
-
-	return &fpResp.TLS
-}

backend/internal/repository/aes_encryptor.go

@@ -0,0 +1,95 @@
+package repository
+
+import (
+	"crypto/aes"
+	"crypto/cipher"
+	"crypto/rand"
+	"encoding/base64"
+	"encoding/hex"
+	"fmt"
+	"io"
+
+	"github.com/Wei-Shaw/sub2api/internal/config"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+)
+
+// AESEncryptor implements SecretEncryptor using AES-256-GCM
+type AESEncryptor struct {
+	key []byte
+}
+
+// NewAESEncryptor creates a new AES encryptor
+func NewAESEncryptor(cfg *config.Config) (service.SecretEncryptor, error) {
+	key, err := hex.DecodeString(cfg.Totp.EncryptionKey)
+	if err != nil {
+		return nil, fmt.Errorf("invalid totp encryption key: %w", err)
+	}
+
+	if len(key) != 32 {
+		return nil, fmt.Errorf("totp encryption key must be 32 bytes (64 hex chars), got %d bytes", len(key))
+	}
+
+	return &AESEncryptor{key: key}, nil
+}
+
+// Encrypt encrypts plaintext using AES-256-GCM
+// Output format: base64(nonce + ciphertext + tag)
+func (e *AESEncryptor) Encrypt(plaintext string) (string, error) {
+	block, err := aes.NewCipher(e.key)
+	if err != nil {
+		return "", fmt.Errorf("create cipher: %w", err)
+	}
+
+	gcm, err := cipher.NewGCM(block)
+	if err != nil {
+		return "", fmt.Errorf("create gcm: %w", err)
+	}
+
+	// Generate a random nonce
+	nonce := make([]byte, gcm.NonceSize())
+	if _, err := io.ReadFull(rand.Reader, nonce); err != nil {
+		return "", fmt.Errorf("generate nonce: %w", err)
+	}
+
+	// Encrypt the plaintext
+	// Seal appends the ciphertext and tag to the nonce
+	ciphertext := gcm.Seal(nonce, nonce, []byte(plaintext), nil)
+
+	// Encode as base64
+	return base64.StdEncoding.EncodeToString(ciphertext), nil
+}
+
+// Decrypt decrypts ciphertext using AES-256-GCM
+func (e *AESEncryptor) Decrypt(ciphertext string) (string, error) {
+	// Decode from base64
+	data, err := base64.StdEncoding.DecodeString(ciphertext)
+	if err != nil {
+		return "", fmt.Errorf("decode base64: %w", err)
+	}
+
+	block, err := aes.NewCipher(e.key)
+	if err != nil {
+		return "", fmt.Errorf("create cipher: %w", err)
+	}
+
+	gcm, err := cipher.NewGCM(block)
+	if err != nil {
+		return "", fmt.Errorf("create gcm: %w", err)
+	}
+
+	nonceSize := gcm.NonceSize()
+	if len(data) < nonceSize {
+		return "", fmt.Errorf("ciphertext too short")
+	}
+
+	// Extract nonce and ciphertext
+	nonce, ciphertextData := data[:nonceSize], data[nonceSize:]
+
+	// Decrypt
+	plaintext, err := gcm.Open(nil, nonce, ciphertextData, nil)
+	if err != nil {
+		return "", fmt.Errorf("decrypt: %w", err)
+	}
+
+	return string(plaintext), nil
+}

backend/internal/repository/api_key_repo.go

@@ -396,6 +396,9 @@ func userEntityToService(u *dbent.User) *service.User {
 		Balance:             u.Balance,
 		Concurrency:         u.Concurrency,
 		Status:              u.Status,
+		TotpSecretEncrypted: u.TotpSecretEncrypted,
+		TotpEnabled:         u.TotpEnabled,
+		TotpEnabledAt:       u.TotpEnabledAt,
 		CreatedAt:           u.CreatedAt,
 		UpdatedAt:           u.UpdatedAt,
 	}

backend/internal/repository/totp_cache.go

@@ -0,0 +1,149 @@
+package repository
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"time"
+
+	"github.com/redis/go-redis/v9"
+
+	"github.com/Wei-Shaw/sub2api/internal/service"
+)
+
+const (
+	totpSetupKeyPrefix    = "totp:setup:"
+	totpLoginKeyPrefix    = "totp:login:"
+	totpAttemptsKeyPrefix = "totp:attempts:"
+	totpAttemptsTTL       = 15 * time.Minute
+)
+
+// TotpCache implements service.TotpCache using Redis
+type TotpCache struct {
+	rdb *redis.Client
+}
+
+// NewTotpCache creates a new TOTP cache
+func NewTotpCache(rdb *redis.Client) service.TotpCache {
+	return &TotpCache{rdb: rdb}
+}
+
+// GetSetupSession retrieves a TOTP setup session
+func (c *TotpCache) GetSetupSession(ctx context.Context, userID int64) (*service.TotpSetupSession, error) {
+	key := fmt.Sprintf("%s%d", totpSetupKeyPrefix, userID)
+	data, err := c.rdb.Get(ctx, key).Bytes()
+	if err != nil {
+		if err == redis.Nil {
+			return nil, nil
+		}
+		return nil, fmt.Errorf("get setup session: %w", err)
+	}
+
+	var session service.TotpSetupSession
+	if err := json.Unmarshal(data, &session); err != nil {
+		return nil, fmt.Errorf("unmarshal setup session: %w", err)
+	}
+
+	return &session, nil
+}
+
+// SetSetupSession stores a TOTP setup session
+func (c *TotpCache) SetSetupSession(ctx context.Context, userID int64, session *service.TotpSetupSession, ttl time.Duration) error {
+	key := fmt.Sprintf("%s%d", totpSetupKeyPrefix, userID)
+	data, err := json.Marshal(session)
+	if err != nil {
+		return fmt.Errorf("marshal setup session: %w", err)
+	}
+
+	if err := c.rdb.Set(ctx, key, data, ttl).Err(); err != nil {
+		return fmt.Errorf("set setup session: %w", err)
+	}
+
+	return nil
+}
+
+// DeleteSetupSession deletes a TOTP setup session
+func (c *TotpCache) DeleteSetupSession(ctx context.Context, userID int64) error {
+	key := fmt.Sprintf("%s%d", totpSetupKeyPrefix, userID)
+	return c.rdb.Del(ctx, key).Err()
+}
+
+// GetLoginSession retrieves a TOTP login session
+func (c *TotpCache) GetLoginSession(ctx context.Context, tempToken string) (*service.TotpLoginSession, error) {
+	key := totpLoginKeyPrefix + tempToken
+	data, err := c.rdb.Get(ctx, key).Bytes()
+	if err != nil {
+		if err == redis.Nil {
+			return nil, nil
+		}
+		return nil, fmt.Errorf("get login session: %w", err)
+	}
+
+	var session service.TotpLoginSession
+	if err := json.Unmarshal(data, &session); err != nil {
+		return nil, fmt.Errorf("unmarshal login session: %w", err)
+	}
+
+	return &session, nil
+}
+
+// SetLoginSession stores a TOTP login session
+func (c *TotpCache) SetLoginSession(ctx context.Context, tempToken string, session *service.TotpLoginSession, ttl time.Duration) error {
+	key := totpLoginKeyPrefix + tempToken
+	data, err := json.Marshal(session)
+	if err != nil {
+		return fmt.Errorf("marshal login session: %w", err)
+	}
+
+	if err := c.rdb.Set(ctx, key, data, ttl).Err(); err != nil {
+		return fmt.Errorf("set login session: %w", err)
+	}
+
+	return nil
+}
+
+// DeleteLoginSession deletes a TOTP login session
+func (c *TotpCache) DeleteLoginSession(ctx context.Context, tempToken string) error {
+	key := totpLoginKeyPrefix + tempToken
+	return c.rdb.Del(ctx, key).Err()
+}
+
+// IncrementVerifyAttempts increments the verify attempt counter
+func (c *TotpCache) IncrementVerifyAttempts(ctx context.Context, userID int64) (int, error) {
+	key := fmt.Sprintf("%s%d", totpAttemptsKeyPrefix, userID)
+
+	// Use pipeline for atomic increment and set TTL
+	pipe := c.rdb.Pipeline()
+	incrCmd := pipe.Incr(ctx, key)
+	pipe.Expire(ctx, key, totpAttemptsTTL)
+
+	if _, err := pipe.Exec(ctx); err != nil {
+		return 0, fmt.Errorf("increment verify attempts: %w", err)
+	}
+
+	count, err := incrCmd.Result()
+	if err != nil {
+		return 0, fmt.Errorf("get increment result: %w", err)
+	}
+
+	return int(count), nil
+}
+
+// GetVerifyAttempts gets the current verify attempt count
+func (c *TotpCache) GetVerifyAttempts(ctx context.Context, userID int64) (int, error) {
+	key := fmt.Sprintf("%s%d", totpAttemptsKeyPrefix, userID)
+	count, err := c.rdb.Get(ctx, key).Int()
+	if err != nil {
+		if err == redis.Nil {
+			return 0, nil
+		}
+		return 0, fmt.Errorf("get verify attempts: %w", err)
+	}
+	return count, nil
+}
+
+// ClearVerifyAttempts clears the verify attempt counter
+func (c *TotpCache) ClearVerifyAttempts(ctx context.Context, userID int64) error {
+	key := fmt.Sprintf("%s%d", totpAttemptsKeyPrefix, userID)
+	return c.rdb.Del(ctx, key).Err()
+}

backend/internal/repository/user_repo.go

@@ -7,6 +7,7 @@ import (
 	"fmt"
 	"sort"
 	"strings"
+	"time"
 
 	dbent "github.com/Wei-Shaw/sub2api/ent"
 	dbuser "github.com/Wei-Shaw/sub2api/ent/user"
@@ -466,3 +467,46 @@ func applyUserEntityToService(dst *service.User, src *dbent.User) {
 	dst.CreatedAt = src.CreatedAt
 	dst.UpdatedAt = src.UpdatedAt
 }
+
+// UpdateTotpSecret 更新用户的 TOTP 加密密钥
+func (r *userRepository) UpdateTotpSecret(ctx context.Context, userID int64, encryptedSecret *string) error {
+	client := clientFromContext(ctx, r.client)
+	update := client.User.UpdateOneID(userID)
+	if encryptedSecret == nil {
+		update = update.ClearTotpSecretEncrypted()
+	} else {
+		update = update.SetTotpSecretEncrypted(*encryptedSecret)
+	}
+	_, err := update.Save(ctx)
+	if err != nil {
+		return translatePersistenceError(err, service.ErrUserNotFound, nil)
+	}
+	return nil
+}
+
+// EnableTotp 启用用户的 TOTP 双因素认证
+func (r *userRepository) EnableTotp(ctx context.Context, userID int64) error {
+	client := clientFromContext(ctx, r.client)
+	_, err := client.User.UpdateOneID(userID).
+		SetTotpEnabled(true).
+		SetTotpEnabledAt(time.Now()).
+		Save(ctx)
+	if err != nil {
+		return translatePersistenceError(err, service.ErrUserNotFound, nil)
+	}
+	return nil
+}
+
+// DisableTotp 禁用用户的 TOTP 双因素认证
+func (r *userRepository) DisableTotp(ctx context.Context, userID int64) error {
+	client := clientFromContext(ctx, r.client)
+	_, err := client.User.UpdateOneID(userID).
+		SetTotpEnabled(false).
+		ClearTotpEnabledAt().
+		ClearTotpSecretEncrypted().
+		Save(ctx)
+	if err != nil {
+		return translatePersistenceError(err, service.ErrUserNotFound, nil)
+	}
+	return nil
+}

backend/internal/repository/wire.go

@@ -82,6 +82,10 @@ var ProviderSet = wire.NewSet(
 	NewSchedulerCache,
 	NewSchedulerOutboxRepository,
 	NewProxyLatencyCache,
+	NewTotpCache,
+
+	// Encryptors
+	NewAESEncryptor,
 
 	// HTTP service ports (DI Strategy A: return interface directly)
 	NewTurnstileVerifier,

backend/internal/server/api_contract_test.go

@@ -453,6 +453,8 @@ func TestAPIContracts(t *testing.T) {
 					"email_verify_enabled": false,
 					"promo_code_enabled": true,
 					"password_reset_enabled": false,
+					"totp_enabled": false,
+					"totp_encryption_key_configured": false,
 					"smtp_host": "smtp.example.com",
 					"smtp_port": 587,
 					"smtp_username": "user",
@@ -596,7 +598,7 @@ func newContractDeps(t *testing.T) *contractDeps {
 	settingService := service.NewSettingService(settingRepo, cfg)
 
 	adminService := service.NewAdminService(userRepo, groupRepo, &accountRepo, proxyRepo, apiKeyRepo, redeemRepo, nil, nil, nil, nil)
-	authHandler := handler.NewAuthHandler(cfg, nil, userService, settingService, nil)
+	authHandler := handler.NewAuthHandler(cfg, nil, userService, settingService, nil, nil)
 	apiKeyHandler := handler.NewAPIKeyHandler(apiKeyService)
 	usageHandler := handler.NewUsageHandler(usageService, apiKeyService)
 	adminSettingHandler := adminhandler.NewSettingHandler(settingService, nil, nil, nil)
@@ -755,6 +757,18 @@ func (r *stubUserRepo) RemoveGroupFromAllowedGroups(ctx context.Context, groupID
 	return 0, errors.New("not implemented")
 }
 
+func (r *stubUserRepo) UpdateTotpSecret(ctx context.Context, userID int64, encryptedSecret *string) error {
+	return errors.New("not implemented")
+}
+
+func (r *stubUserRepo) EnableTotp(ctx context.Context, userID int64) error {
+	return errors.New("not implemented")
+}
+
+func (r *stubUserRepo) DisableTotp(ctx context.Context, userID int64) error {
+	return errors.New("not implemented")
+}
+
 type stubApiKeyCache struct{}
 
 func (stubApiKeyCache) GetCreateAttemptCount(ctx context.Context, userID int64) (int, error) {

backend/internal/server/routes/auth.go

@@ -26,6 +26,7 @@ func RegisterAuthRoutes(
 	{
 		auth.POST("/register", h.Auth.Register)
 		auth.POST("/login", h.Auth.Login)
+		auth.POST("/login/2fa", h.Auth.Login2FA)
 		auth.POST("/send-verify-code", h.Auth.SendVerifyCode)
 		// 优惠码验证接口添加速率限制：每分钟最多 10 次（Redis 故障时 fail-close）
 		auth.POST("/validate-promo-code", rateLimiter.LimitWithOptions("validate-promo", 10, time.Minute, middleware.RateLimitOptions{

backend/internal/server/routes/user.go

@@ -22,6 +22,17 @@ func RegisterUserRoutes(
 			user.GET("/profile", h.User.GetProfile)
 			user.PUT("/password", h.User.ChangePassword)
 			user.PUT("", h.User.UpdateProfile)
+
+			// TOTP 双因素认证
+			totp := user.Group("/totp")
+			{
+				totp.GET("/status", h.Totp.GetStatus)
+				totp.GET("/verification-method", h.Totp.GetVerificationMethod)
+				totp.POST("/send-code", h.Totp.SendVerifyCode)
+				totp.POST("/setup", h.Totp.InitiateSetup)
+				totp.POST("/enable", h.Totp.Enable)
+				totp.POST("/disable", h.Totp.Disable)
+			}
 		}
 
 		// API Key管理

backend/internal/service/admin_service_delete_test.go

@@ -93,6 +93,18 @@ func (s *userRepoStub) RemoveGroupFromAllowedGroups(ctx context.Context, groupID
 	panic("unexpected RemoveGroupFromAllowedGroups call")
 }
 
+func (s *userRepoStub) UpdateTotpSecret(ctx context.Context, userID int64, encryptedSecret *string) error {
+	panic("unexpected UpdateTotpSecret call")
+}
+
+func (s *userRepoStub) EnableTotp(ctx context.Context, userID int64) error {
+	panic("unexpected EnableTotp call")
+}
+
+func (s *userRepoStub) DisableTotp(ctx context.Context, userID int64) error {
+	panic("unexpected DisableTotp call")
+}
+
 type groupRepoStub struct {
 	affectedUserIDs []int64
 	deleteErr       error

backend/internal/service/domain_constants.go

@@ -88,6 +88,9 @@ const (
 	SettingKeyTurnstileSiteKey   = "turnstile_site_key"   // Turnstile Site Key
 	SettingKeyTurnstileSecretKey = "turnstile_secret_key" // Turnstile Secret Key
 
+	// TOTP 双因素认证设置
+	SettingKeyTotpEnabled = "totp_enabled" // 是否启用 TOTP 2FA 功能
+
 	// LinuxDo Connect OAuth 登录设置
 	SettingKeyLinuxDoConnectEnabled      = "linuxdo_connect_enabled"
 	SettingKeyLinuxDoConnectClientID     = "linuxdo_connect_client_id"

backend/internal/service/email_service.go

@@ -282,8 +282,8 @@ func (s *EmailService) VerifyCode(ctx context.Context, email, code string) error
 		return ErrVerifyCodeMaxAttempts
 	}
 
-	// 验证码不匹配
+	// 验证码不匹配 (constant-time comparison to prevent timing attacks)
-	if data.Code != code {
+	if subtle.ConstantTimeCompare([]byte(data.Code), []byte(code)) != 1 {
 		data.Attempts++
 		if err := s.cache.SetVerificationCode(ctx, email, data, verifyCodeTTL); err != nil {
 			log.Printf("[Email] Failed to update verification attempt count: %v", err)

backend/internal/service/setting_service.go

@@ -62,6 +62,7 @@ func (s *SettingService) GetPublicSettings(ctx context.Context) (*PublicSettings
 		SettingKeyEmailVerifyEnabled,
 		SettingKeyPromoCodeEnabled,
 		SettingKeyPasswordResetEnabled,
+		SettingKeyTotpEnabled,
 		SettingKeyTurnstileEnabled,
 		SettingKeyTurnstileSiteKey,
 		SettingKeySiteName,
@@ -96,6 +97,7 @@ func (s *SettingService) GetPublicSettings(ctx context.Context) (*PublicSettings
 		EmailVerifyEnabled:   emailVerifyEnabled,
 		PromoCodeEnabled:     settings[SettingKeyPromoCodeEnabled] != "false", // 默认启用
 		PasswordResetEnabled: passwordResetEnabled,
+		TotpEnabled:          settings[SettingKeyTotpEnabled] == "true",
 		TurnstileEnabled:     settings[SettingKeyTurnstileEnabled] == "true",
 		TurnstileSiteKey:     settings[SettingKeyTurnstileSiteKey],
 		SiteName:             s.getStringOrDefault(settings, SettingKeySiteName, "Sub2API"),
@@ -135,6 +137,7 @@ func (s *SettingService) GetPublicSettingsForInjection(ctx context.Context) (any
 		EmailVerifyEnabled   bool   `json:"email_verify_enabled"`
 		PromoCodeEnabled     bool   `json:"promo_code_enabled"`
 		PasswordResetEnabled bool   `json:"password_reset_enabled"`
+		TotpEnabled          bool   `json:"totp_enabled"`
 		TurnstileEnabled     bool   `json:"turnstile_enabled"`
 		TurnstileSiteKey     string `json:"turnstile_site_key,omitempty"`
 		SiteName             string `json:"site_name"`
@@ -152,6 +155,7 @@ func (s *SettingService) GetPublicSettingsForInjection(ctx context.Context) (any
 		EmailVerifyEnabled:   settings.EmailVerifyEnabled,
 		PromoCodeEnabled:     settings.PromoCodeEnabled,
 		PasswordResetEnabled: settings.PasswordResetEnabled,
+		TotpEnabled:          settings.TotpEnabled,
 		TurnstileEnabled:     settings.TurnstileEnabled,
 		TurnstileSiteKey:     settings.TurnstileSiteKey,
 		SiteName:             settings.SiteName,
@@ -176,6 +180,7 @@ func (s *SettingService) UpdateSettings(ctx context.Context, settings *SystemSet
 	updates[SettingKeyEmailVerifyEnabled] = strconv.FormatBool(settings.EmailVerifyEnabled)
 	updates[SettingKeyPromoCodeEnabled] = strconv.FormatBool(settings.PromoCodeEnabled)
 	updates[SettingKeyPasswordResetEnabled] = strconv.FormatBool(settings.PasswordResetEnabled)
+	updates[SettingKeyTotpEnabled] = strconv.FormatBool(settings.TotpEnabled)
 
 	// 邮件服务设置（只有非空才更新密码）
 	updates[SettingKeySMTPHost] = settings.SMTPHost
@@ -285,6 +290,21 @@ func (s *SettingService) IsPasswordResetEnabled(ctx context.Context) bool {
 	return value == "true"
 }
 
+// IsTotpEnabled 检查是否启用 TOTP 双因素认证功能
+func (s *SettingService) IsTotpEnabled(ctx context.Context) bool {
+	value, err := s.settingRepo.GetValue(ctx, SettingKeyTotpEnabled)
+	if err != nil {
+		return false // 默认关闭
+	}
+	return value == "true"
+}
+
+// IsTotpEncryptionKeyConfigured 检查 TOTP 加密密钥是否已手动配置
+// 只有手动配置了密钥才允许在管理后台启用 TOTP 功能
+func (s *SettingService) IsTotpEncryptionKeyConfigured() bool {
+	return s.cfg.Totp.EncryptionKeyConfigured
+}
+
 // GetSiteName 获取网站名称
 func (s *SettingService) GetSiteName(ctx context.Context) string {
 	value, err := s.settingRepo.GetValue(ctx, SettingKeySiteName)
@@ -369,6 +389,7 @@ func (s *SettingService) parseSettings(settings map[string]string) *SystemSettin
 		EmailVerifyEnabled:           emailVerifyEnabled,
 		PromoCodeEnabled:             settings[SettingKeyPromoCodeEnabled] != "false", // 默认启用
 		PasswordResetEnabled:         emailVerifyEnabled && settings[SettingKeyPasswordResetEnabled] == "true",
+		TotpEnabled:                  settings[SettingKeyTotpEnabled] == "true",
 		SMTPHost:                     settings[SettingKeySMTPHost],
 		SMTPUsername:                 settings[SettingKeySMTPUsername],
 		SMTPFrom:                     settings[SettingKeySMTPFrom],

backend/internal/service/settings_view.go

@@ -5,6 +5,7 @@ type SystemSettings struct {
 	EmailVerifyEnabled   bool
 	PromoCodeEnabled     bool
 	PasswordResetEnabled bool
+	TotpEnabled          bool // TOTP 双因素认证
 
 	SMTPHost               string
 	SMTPPort               int
@@ -62,6 +63,7 @@ type PublicSettings struct {
 	EmailVerifyEnabled   bool
 	PromoCodeEnabled     bool
 	PasswordResetEnabled bool
+	TotpEnabled          bool // TOTP 双因素认证
 	TurnstileEnabled     bool
 	TurnstileSiteKey     string
 	SiteName             string

backend/internal/service/totp_service.go

@@ -0,0 +1,506 @@
+package service
+
+import (
+	"context"
+	"crypto/rand"
+	"crypto/subtle"
+	"encoding/hex"
+	"fmt"
+	"log/slog"
+	"time"
+
+	"github.com/pquerna/otp/totp"
+
+	infraerrors "github.com/Wei-Shaw/sub2api/internal/pkg/errors"
+)
+
+var (
+	ErrTotpNotEnabled      = infraerrors.BadRequest("TOTP_NOT_ENABLED", "totp feature is not enabled")
+	ErrTotpAlreadyEnabled  = infraerrors.BadRequest("TOTP_ALREADY_ENABLED", "totp is already enabled for this account")
+	ErrTotpNotSetup        = infraerrors.BadRequest("TOTP_NOT_SETUP", "totp is not set up for this account")
+	ErrTotpInvalidCode     = infraerrors.BadRequest("TOTP_INVALID_CODE", "invalid totp code")
+	ErrTotpSetupExpired    = infraerrors.BadRequest("TOTP_SETUP_EXPIRED", "totp setup session expired")
+	ErrTotpTooManyAttempts = infraerrors.TooManyRequests("TOTP_TOO_MANY_ATTEMPTS", "too many verification attempts, please try again later")
+	ErrVerifyCodeRequired  = infraerrors.BadRequest("VERIFY_CODE_REQUIRED", "email verification code is required")
+	ErrPasswordRequired    = infraerrors.BadRequest("PASSWORD_REQUIRED", "password is required")
+)
+
+// TotpCache defines cache operations for TOTP service
+type TotpCache interface {
+	// Setup session methods
+	GetSetupSession(ctx context.Context, userID int64) (*TotpSetupSession, error)
+	SetSetupSession(ctx context.Context, userID int64, session *TotpSetupSession, ttl time.Duration) error
+	DeleteSetupSession(ctx context.Context, userID int64) error
+
+	// Login session methods (for 2FA login flow)
+	GetLoginSession(ctx context.Context, tempToken string) (*TotpLoginSession, error)
+	SetLoginSession(ctx context.Context, tempToken string, session *TotpLoginSession, ttl time.Duration) error
+	DeleteLoginSession(ctx context.Context, tempToken string) error
+
+	// Rate limiting
+	IncrementVerifyAttempts(ctx context.Context, userID int64) (int, error)
+	GetVerifyAttempts(ctx context.Context, userID int64) (int, error)
+	ClearVerifyAttempts(ctx context.Context, userID int64) error
+}
+
+// SecretEncryptor defines encryption operations for TOTP secrets
+type SecretEncryptor interface {
+	Encrypt(plaintext string) (string, error)
+	Decrypt(ciphertext string) (string, error)
+}
+
+// TotpSetupSession represents a TOTP setup session
+type TotpSetupSession struct {
+	Secret     string // Plain text TOTP secret (not encrypted yet)
+	SetupToken string // Random token to verify setup request
+	CreatedAt  time.Time
+}
+
+// TotpLoginSession represents a pending 2FA login session
+type TotpLoginSession struct {
+	UserID      int64
+	Email       string
+	TokenExpiry time.Time
+}
+
+// TotpStatus represents the TOTP status for a user
+type TotpStatus struct {
+	Enabled        bool       `json:"enabled"`
+	EnabledAt      *time.Time `json:"enabled_at,omitempty"`
+	FeatureEnabled bool       `json:"feature_enabled"`
+}
+
+// TotpSetupResponse represents the response for initiating TOTP setup
+type TotpSetupResponse struct {
+	Secret     string `json:"secret"`
+	QRCodeURL  string `json:"qr_code_url"`
+	SetupToken string `json:"setup_token"`
+	Countdown  int    `json:"countdown"` // seconds until setup expires
+}
+
+const (
+	totpSetupTTL    = 5 * time.Minute
+	totpLoginTTL    = 5 * time.Minute
+	totpAttemptsTTL = 15 * time.Minute
+	maxTotpAttempts = 5
+	totpIssuer      = "Sub2API"
+)
+
+// TotpService handles TOTP operations
+type TotpService struct {
+	userRepo          UserRepository
+	encryptor         SecretEncryptor
+	cache             TotpCache
+	settingService    *SettingService
+	emailService      *EmailService
+	emailQueueService *EmailQueueService
+}
+
+// NewTotpService creates a new TOTP service
+func NewTotpService(
+	userRepo UserRepository,
+	encryptor SecretEncryptor,
+	cache TotpCache,
+	settingService *SettingService,
+	emailService *EmailService,
+	emailQueueService *EmailQueueService,
+) *TotpService {
+	return &TotpService{
+		userRepo:          userRepo,
+		encryptor:         encryptor,
+		cache:             cache,
+		settingService:    settingService,
+		emailService:      emailService,
+		emailQueueService: emailQueueService,
+	}
+}
+
+// GetStatus returns the TOTP status for a user
+func (s *TotpService) GetStatus(ctx context.Context, userID int64) (*TotpStatus, error) {
+	featureEnabled := s.settingService.IsTotpEnabled(ctx)
+
+	user, err := s.userRepo.GetByID(ctx, userID)
+	if err != nil {
+		return nil, fmt.Errorf("get user: %w", err)
+	}
+
+	return &TotpStatus{
+		Enabled:        user.TotpEnabled,
+		EnabledAt:      user.TotpEnabledAt,
+		FeatureEnabled: featureEnabled,
+	}, nil
+}
+
+// InitiateSetup starts the TOTP setup process
+// If email verification is enabled, emailCode is required; otherwise password is required
+func (s *TotpService) InitiateSetup(ctx context.Context, userID int64, emailCode, password string) (*TotpSetupResponse, error) {
+	// Check if TOTP feature is enabled globally
+	if !s.settingService.IsTotpEnabled(ctx) {
+		return nil, ErrTotpNotEnabled
+	}
+
+	// Get user and check if TOTP is already enabled
+	user, err := s.userRepo.GetByID(ctx, userID)
+	if err != nil {
+		return nil, fmt.Errorf("get user: %w", err)
+	}
+
+	if user.TotpEnabled {
+		return nil, ErrTotpAlreadyEnabled
+	}
+
+	// Verify identity based on email verification setting
+	if s.settingService.IsEmailVerifyEnabled(ctx) {
+		// Email verification enabled - verify email code
+		if emailCode == "" {
+			return nil, ErrVerifyCodeRequired
+		}
+		if err := s.emailService.VerifyCode(ctx, user.Email, emailCode); err != nil {
+			return nil, err
+		}
+	} else {
+		// Email verification disabled - verify password
+		if password == "" {
+			return nil, ErrPasswordRequired
+		}
+		if !user.CheckPassword(password) {
+			return nil, ErrPasswordIncorrect
+		}
+	}
+
+	// Generate a new TOTP key
+	key, err := totp.Generate(totp.GenerateOpts{
+		Issuer:      totpIssuer,
+		AccountName: user.Email,
+	})
+	if err != nil {
+		return nil, fmt.Errorf("generate totp key: %w", err)
+	}
+
+	// Generate a random setup token
+	setupToken, err := generateRandomToken(32)
+	if err != nil {
+		return nil, fmt.Errorf("generate setup token: %w", err)
+	}
+
+	// Store the setup session in cache
+	session := &TotpSetupSession{
+		Secret:     key.Secret(),
+		SetupToken: setupToken,
+		CreatedAt:  time.Now(),
+	}
+
+	if err := s.cache.SetSetupSession(ctx, userID, session, totpSetupTTL); err != nil {
+		return nil, fmt.Errorf("store setup session: %w", err)
+	}
+
+	return &TotpSetupResponse{
+		Secret:     key.Secret(),
+		QRCodeURL:  key.URL(),
+		SetupToken: setupToken,
+		Countdown:  int(totpSetupTTL.Seconds()),
+	}, nil
+}
+
+// CompleteSetup completes the TOTP setup by verifying the code
+func (s *TotpService) CompleteSetup(ctx context.Context, userID int64, totpCode, setupToken string) error {
+	// Check if TOTP feature is enabled globally
+	if !s.settingService.IsTotpEnabled(ctx) {
+		return ErrTotpNotEnabled
+	}
+
+	// Get the setup session
+	session, err := s.cache.GetSetupSession(ctx, userID)
+	if err != nil {
+		return ErrTotpSetupExpired
+	}
+
+	if session == nil {
+		return ErrTotpSetupExpired
+	}
+
+	// Verify the setup token (constant-time comparison)
+	if subtle.ConstantTimeCompare([]byte(session.SetupToken), []byte(setupToken)) != 1 {
+		return ErrTotpSetupExpired
+	}
+
+	// Verify the TOTP code
+	if !totp.Validate(totpCode, session.Secret) {
+		return ErrTotpInvalidCode
+	}
+
+	setupSecretPrefix := "N/A"
+	if len(session.Secret) >= 4 {
+		setupSecretPrefix = session.Secret[:4]
+	}
+	slog.Debug("totp_complete_setup_before_encrypt",
+		"user_id", userID,
+		"secret_len", len(session.Secret),
+		"secret_prefix", setupSecretPrefix)
+
+	// Encrypt the secret
+	encryptedSecret, err := s.encryptor.Encrypt(session.Secret)
+	if err != nil {
+		return fmt.Errorf("encrypt totp secret: %w", err)
+	}
+
+	slog.Debug("totp_complete_setup_encrypted",
+		"user_id", userID,
+		"encrypted_len", len(encryptedSecret))
+
+	// Verify encryption by decrypting
+	decrypted, decErr := s.encryptor.Decrypt(encryptedSecret)
+	if decErr != nil {
+		slog.Debug("totp_complete_setup_verify_failed",
+			"user_id", userID,
+			"error", decErr)
+	} else {
+		decryptedPrefix := "N/A"
+		if len(decrypted) >= 4 {
+			decryptedPrefix = decrypted[:4]
+		}
+		slog.Debug("totp_complete_setup_verified",
+			"user_id", userID,
+			"original_len", len(session.Secret),
+			"decrypted_len", len(decrypted),
+			"match", session.Secret == decrypted,
+			"decrypted_prefix", decryptedPrefix)
+	}
+
+	// Update user with encrypted TOTP secret
+	if err := s.userRepo.UpdateTotpSecret(ctx, userID, &encryptedSecret); err != nil {
+		return fmt.Errorf("update totp secret: %w", err)
+	}
+
+	// Enable TOTP for the user
+	if err := s.userRepo.EnableTotp(ctx, userID); err != nil {
+		return fmt.Errorf("enable totp: %w", err)
+	}
+
+	// Clean up the setup session
+	_ = s.cache.DeleteSetupSession(ctx, userID)
+
+	return nil
+}
+
+// Disable disables TOTP for a user
+// If email verification is enabled, emailCode is required; otherwise password is required
+func (s *TotpService) Disable(ctx context.Context, userID int64, emailCode, password string) error {
+	// Get user
+	user, err := s.userRepo.GetByID(ctx, userID)
+	if err != nil {
+		return fmt.Errorf("get user: %w", err)
+	}
+
+	if !user.TotpEnabled {
+		return ErrTotpNotSetup
+	}
+
+	// Verify identity based on email verification setting
+	if s.settingService.IsEmailVerifyEnabled(ctx) {
+		// Email verification enabled - verify email code
+		if emailCode == "" {
+			return ErrVerifyCodeRequired
+		}
+		if err := s.emailService.VerifyCode(ctx, user.Email, emailCode); err != nil {
+			return err
+		}
+	} else {
+		// Email verification disabled - verify password
+		if password == "" {
+			return ErrPasswordRequired
+		}
+		if !user.CheckPassword(password) {
+			return ErrPasswordIncorrect
+		}
+	}
+
+	// Disable TOTP
+	if err := s.userRepo.DisableTotp(ctx, userID); err != nil {
+		return fmt.Errorf("disable totp: %w", err)
+	}
+
+	return nil
+}
+
+// VerifyCode verifies a TOTP code for a user
+func (s *TotpService) VerifyCode(ctx context.Context, userID int64, code string) error {
+	slog.Debug("totp_verify_code_called",
+		"user_id", userID,
+		"code_len", len(code))
+
+	// Check rate limiting
+	attempts, err := s.cache.GetVerifyAttempts(ctx, userID)
+	if err == nil && attempts >= maxTotpAttempts {
+		return ErrTotpTooManyAttempts
+	}
+
+	// Get user
+	user, err := s.userRepo.GetByID(ctx, userID)
+	if err != nil {
+		slog.Debug("totp_verify_get_user_failed",
+			"user_id", userID,
+			"error", err)
+		return infraerrors.InternalServer("TOTP_VERIFY_ERROR", "failed to verify totp code")
+	}
+
+	if !user.TotpEnabled || user.TotpSecretEncrypted == nil {
+		slog.Debug("totp_verify_not_setup",
+			"user_id", userID,
+			"enabled", user.TotpEnabled,
+			"has_secret", user.TotpSecretEncrypted != nil)
+		return ErrTotpNotSetup
+	}
+
+	slog.Debug("totp_verify_encrypted_secret",
+		"user_id", userID,
+		"encrypted_len", len(*user.TotpSecretEncrypted))
+
+	// Decrypt the secret
+	secret, err := s.encryptor.Decrypt(*user.TotpSecretEncrypted)
+	if err != nil {
+		slog.Debug("totp_verify_decrypt_failed",
+			"user_id", userID,
+			"error", err)
+		return infraerrors.InternalServer("TOTP_VERIFY_ERROR", "failed to verify totp code")
+	}
+
+	secretPrefix := "N/A"
+	if len(secret) >= 4 {
+		secretPrefix = secret[:4]
+	}
+	slog.Debug("totp_verify_decrypted",
+		"user_id", userID,
+		"secret_len", len(secret),
+		"secret_prefix", secretPrefix)
+
+	// Verify the code
+	valid := totp.Validate(code, secret)
+	slog.Debug("totp_verify_result",
+		"user_id", userID,
+		"valid", valid,
+		"secret_len", len(secret),
+		"secret_prefix", secretPrefix,
+		"server_time", time.Now().UTC().Format(time.RFC3339))
+
+	if !valid {
+		// Increment failed attempts
+		_, _ = s.cache.IncrementVerifyAttempts(ctx, userID)
+		return ErrTotpInvalidCode
+	}
+
+	// Clear attempt counter on success
+	_ = s.cache.ClearVerifyAttempts(ctx, userID)
+
+	return nil
+}
+
+// CreateLoginSession creates a temporary login session for 2FA
+func (s *TotpService) CreateLoginSession(ctx context.Context, userID int64, email string) (string, error) {
+	// Generate a random temp token
+	tempToken, err := generateRandomToken(32)
+	if err != nil {
+		return "", fmt.Errorf("generate temp token: %w", err)
+	}
+
+	session := &TotpLoginSession{
+		UserID:      userID,
+		Email:       email,
+		TokenExpiry: time.Now().Add(totpLoginTTL),
+	}
+
+	if err := s.cache.SetLoginSession(ctx, tempToken, session, totpLoginTTL); err != nil {
+		return "", fmt.Errorf("store login session: %w", err)
+	}
+
+	return tempToken, nil
+}
+
+// GetLoginSession retrieves a login session
+func (s *TotpService) GetLoginSession(ctx context.Context, tempToken string) (*TotpLoginSession, error) {
+	return s.cache.GetLoginSession(ctx, tempToken)
+}
+
+// DeleteLoginSession deletes a login session
+func (s *TotpService) DeleteLoginSession(ctx context.Context, tempToken string) error {
+	return s.cache.DeleteLoginSession(ctx, tempToken)
+}
+
+// IsTotpEnabledForUser checks if TOTP is enabled for a specific user
+func (s *TotpService) IsTotpEnabledForUser(ctx context.Context, userID int64) (bool, error) {
+	user, err := s.userRepo.GetByID(ctx, userID)
+	if err != nil {
+		return false, fmt.Errorf("get user: %w", err)
+	}
+	return user.TotpEnabled, nil
+}
+
+// MaskEmail masks an email address for display
+func MaskEmail(email string) string {
+	if len(email) < 3 {
+		return "***"
+	}
+
+	atIdx := -1
+	for i, c := range email {
+		if c == '@' {
+			atIdx = i
+			break
+		}
+	}
+
+	if atIdx == -1 || atIdx < 1 {
+		return email[:1] + "***"
+	}
+
+	localPart := email[:atIdx]
+	domain := email[atIdx:]
+
+	if len(localPart) <= 2 {
+		return localPart[:1] + "***" + domain
+	}
+
+	return localPart[:1] + "***" + localPart[len(localPart)-1:] + domain
+}
+
+// generateRandomToken generates a random hex-encoded token
+func generateRandomToken(byteLength int) (string, error) {
+	b := make([]byte, byteLength)
+	if _, err := rand.Read(b); err != nil {
+		return "", err
+	}
+	return hex.EncodeToString(b), nil
+}
+
+// VerificationMethod represents the method required for TOTP operations
+type VerificationMethod struct {
+	Method string `json:"method"` // "email" or "password"
+}
+
+// GetVerificationMethod returns the verification method for TOTP operations
+func (s *TotpService) GetVerificationMethod(ctx context.Context) *VerificationMethod {
+	if s.settingService.IsEmailVerifyEnabled(ctx) {
+		return &VerificationMethod{Method: "email"}
+	}
+	return &VerificationMethod{Method: "password"}
+}
+
+// SendVerifyCode sends an email verification code for TOTP operations
+func (s *TotpService) SendVerifyCode(ctx context.Context, userID int64) error {
+	// Check if email verification is enabled
+	if !s.settingService.IsEmailVerifyEnabled(ctx) {
+		return infraerrors.BadRequest("EMAIL_VERIFY_NOT_ENABLED", "email verification is not enabled")
+	}
+
+	// Get user email
+	user, err := s.userRepo.GetByID(ctx, userID)
+	if err != nil {
+		return fmt.Errorf("get user: %w", err)
+	}
+
+	// Get site name for email
+	siteName := s.settingService.GetSiteName(ctx)
+
+	// Send verification code via queue
+	return s.emailQueueService.EnqueueVerifyCode(user.Email, siteName)
+}

backend/internal/service/user.go

@@ -21,6 +21,11 @@ type User struct {
 	CreatedAt     time.Time
 	UpdatedAt     time.Time
 
+	// TOTP 双因素认证字段
+	TotpSecretEncrypted *string    // AES-256-GCM 加密的 TOTP 密钥
+	TotpEnabled         bool       // 是否启用 TOTP
+	TotpEnabledAt       *time.Time // TOTP 启用时间
+
 	APIKeys       []APIKey
 	Subscriptions []UserSubscription
 }

backend/internal/service/user_service.go

@@ -38,6 +38,11 @@ type UserRepository interface {
 	UpdateConcurrency(ctx context.Context, id int64, amount int) error
 	ExistsByEmail(ctx context.Context, email string) (bool, error)
 	RemoveGroupFromAllowedGroups(ctx context.Context, groupID int64) (int64, error)
+
+	// TOTP 相关方法
+	UpdateTotpSecret(ctx context.Context, userID int64, encryptedSecret *string) error
+	EnableTotp(ctx context.Context, userID int64) error
+	DisableTotp(ctx context.Context, userID int64) error
 }
 
 // UpdateProfileRequest 更新用户资料请求

backend/internal/service/wire.go

@@ -271,4 +271,5 @@ var ProviderSet = wire.NewSet(
 	NewAntigravityQuotaFetcher,
 	NewUserAttributeService,
 	NewUsageCache,
+	NewTotpService,
 )

backend/migrations/044_add_user_totp.sql

@@ -0,0 +1,12 @@
+-- 为 users 表添加 TOTP 双因素认证字段
+ALTER TABLE users
+  ADD COLUMN IF NOT EXISTS totp_secret_encrypted TEXT DEFAULT NULL,
+  ADD COLUMN IF NOT EXISTS totp_enabled BOOLEAN NOT NULL DEFAULT FALSE,
+  ADD COLUMN IF NOT EXISTS totp_enabled_at TIMESTAMPTZ DEFAULT NULL;
+
+COMMENT ON COLUMN users.totp_secret_encrypted IS 'AES-256-GCM 加密的 TOTP 密钥';
+COMMENT ON COLUMN users.totp_enabled IS '是否启用 TOTP 双因素认证';
+COMMENT ON COLUMN users.totp_enabled_at IS 'TOTP 启用时间';
+
+-- 创建索引以支持快速查询启用 2FA 的用户
+CREATE INDEX IF NOT EXISTS idx_users_totp_enabled ON users(totp_enabled) WHERE deleted_at IS NULL AND totp_enabled = true;

deploy/.env.example

@@ -61,6 +61,18 @@ ADMIN_PASSWORD=
 JWT_SECRET=
 JWT_EXPIRE_HOUR=24
 
+# -----------------------------------------------------------------------------
+# TOTP (2FA) Configuration
+# TOTP（双因素认证）配置
+# -----------------------------------------------------------------------------
+# IMPORTANT: Set a fixed encryption key for TOTP secrets. If left empty, a
+# random key will be generated on each startup, causing all existing TOTP
+# configurations to become invalid (users won't be able to login with 2FA).
+# Generate a secure key: openssl rand -hex 32
+# 重要：设置固定的 TOTP 加密密钥。如果留空，每次启动将生成随机密钥，
+# 导致现有的 TOTP 配置失效（用户无法使用双因素认证登录）。
+TOTP_ENCRYPTION_KEY=
+
 # -----------------------------------------------------------------------------
 # Configuration File (Optional)
 # -----------------------------------------------------------------------------

deploy/config.example.yaml

@@ -403,6 +403,21 @@ jwt:
   # 令牌过期时间（小时，最大 24）
   expire_hour: 24
 
+# =============================================================================
+# TOTP (2FA) Configuration
+# TOTP 双因素认证配置
+# =============================================================================
+totp:
+  # IMPORTANT: Set a fixed encryption key for TOTP secrets.
+  # 重要：设置固定的 TOTP 加密密钥。
+  # If left empty, a random key will be generated on each startup, causing all
+  # existing TOTP configurations to become invalid (users won't be able to
+  # login with 2FA).
+  # 如果留空，每次启动将生成随机密钥，导致现有的 TOTP 配置失效（用户无法使用
+  # 双因素认证登录）。
+  # Generate with / 生成命令: openssl rand -hex 32
+  encryption_key: ""
+
 # =============================================================================
 # LinuxDo Connect OAuth Login (SSO)
 # LinuxDo Connect OAuth 登录（用于 Sub2API 用户登录）

deploy/docker-compose.yml

@@ -79,6 +79,16 @@ services:
       - JWT_SECRET=${JWT_SECRET:-}
       - JWT_EXPIRE_HOUR=${JWT_EXPIRE_HOUR:-24}
 
+      # =======================================================================
+      # TOTP (2FA) Configuration
+      # =======================================================================
+      # IMPORTANT: Set a fixed encryption key for TOTP secrets. If left empty,
+      # a random key will be generated on each startup, causing all existing
+      # TOTP configurations to become invalid (users won't be able to login
+      # with 2FA).
+      # Generate a secure key: openssl rand -hex 32
+      - TOTP_ENCRYPTION_KEY=${TOTP_ENCRYPTION_KEY:-}
+
       # =======================================================================
       # Timezone Configuration
       # This affects ALL time operations in the application:

frontend/package-lock.json

@@ -15,6 +15,7 @@
         "driver.js": "^1.4.0",
         "file-saver": "^2.0.5",
         "pinia": "^2.1.7",
+        "qrcode": "^1.5.4",
         "vue": "^3.4.0",
         "vue-chartjs": "^5.3.0",
         "vue-i18n": "^9.14.5",
@@ -25,6 +26,7 @@
         "@types/file-saver": "^2.0.7",
         "@types/mdx": "^2.0.13",
         "@types/node": "^20.10.5",
+        "@types/qrcode": "^1.5.6",
         "@typescript-eslint/eslint-plugin": "^7.18.0",
         "@typescript-eslint/parser": "^7.18.0",
         "@vitejs/plugin-vue": "^5.2.3",
@@ -1680,6 +1682,16 @@
       "integrity": "sha512-dISoDXWWQwUquiKsyZ4Ng+HX2KsPL7LyHKHQwgGFEA3IaKac4Obd+h2a/a6waisAoepJlBcx9paWqjA8/HVjCw==",
       "license": "MIT"
     },
+    "node_modules/@types/qrcode": {
+      "version": "1.5.6",
+      "resolved": "https://registry.npmmirror.com/@types/qrcode/-/qrcode-1.5.6.tgz",
+      "integrity": "sha512-te7NQcV2BOvdj2b1hCAHzAoMNuj65kNBMz0KBaxM6c3VGBOhU0dURQKOtH8CFNI/dsKkwlv32p26qYQTWoB5bw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/node": "*"
+      }
+    },
     "node_modules/@types/web-bluetooth": {
       "version": "0.0.20",
       "resolved": "https://registry.npmjs.org/@types/web-bluetooth/-/web-bluetooth-0.0.20.tgz",
@@ -2354,7 +2366,6 @@
       "version": "5.0.1",
       "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz",
       "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==",
-      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">=8"
@@ -2364,7 +2375,6 @@
       "version": "4.3.0",
       "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz",
       "integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "color-convert": "^2.0.1"
@@ -2646,6 +2656,15 @@
         "node": ">=6"
       }
     },
+    "node_modules/camelcase": {
+      "version": "5.3.1",
+      "resolved": "https://registry.npmmirror.com/camelcase/-/camelcase-5.3.1.tgz",
+      "integrity": "sha512-L28STB170nwWS63UjtlEOE3dldQApaJXZkOI1uMFfzf3rRuPegHaHesyee+YxQ+W6SvRDQV6UrdOdRiR153wJg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
     "node_modules/camelcase-css": {
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/camelcase-css/-/camelcase-css-2.0.1.tgz",
@@ -2784,6 +2803,51 @@
         "node": ">= 6"
       }
     },
+    "node_modules/cliui": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmmirror.com/cliui/-/cliui-6.0.0.tgz",
+      "integrity": "sha512-t6wbgtoCXvAzst7QgXxJYqPt0usEfbgQdftEPbLL/cvv6HPE5VgvqCuAIDR0NgU52ds6rFwqrgakNLrHEjCbrQ==",
+      "license": "ISC",
+      "dependencies": {
+        "string-width": "^4.2.0",
+        "strip-ansi": "^6.0.0",
+        "wrap-ansi": "^6.2.0"
+      }
+    },
+    "node_modules/cliui/node_modules/emoji-regex": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmmirror.com/emoji-regex/-/emoji-regex-8.0.0.tgz",
+      "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==",
+      "license": "MIT"
+    },
+    "node_modules/cliui/node_modules/string-width": {
+      "version": "4.2.3",
+      "resolved": "https://registry.npmmirror.com/string-width/-/string-width-4.2.3.tgz",
+      "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==",
+      "license": "MIT",
+      "dependencies": {
+        "emoji-regex": "^8.0.0",
+        "is-fullwidth-code-point": "^3.0.0",
+        "strip-ansi": "^6.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/cliui/node_modules/wrap-ansi": {
+      "version": "6.2.0",
+      "resolved": "https://registry.npmmirror.com/wrap-ansi/-/wrap-ansi-6.2.0.tgz",
+      "integrity": "sha512-r6lPcBGxZXlIcymEu7InxDMhdW0KDxpLgoFLcguasxCaJ/SOIZwINatK9KY/tf+ZrlywOKU0UDj3ATXUBfxJXA==",
+      "license": "MIT",
+      "dependencies": {
+        "ansi-styles": "^4.0.0",
+        "string-width": "^4.1.0",
+        "strip-ansi": "^6.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/clsx": {
       "version": "2.1.1",
       "resolved": "https://registry.npmjs.org/clsx/-/clsx-2.1.1.tgz",
@@ -2806,7 +2870,6 @@
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz",
       "integrity": "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "color-name": "~1.1.4"
@@ -2819,7 +2882,6 @@
       "version": "1.1.4",
       "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz",
       "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/combined-stream": {
@@ -2989,6 +3051,15 @@
         }
       }
     },
+    "node_modules/decamelize": {
+      "version": "1.2.0",
+      "resolved": "https://registry.npmmirror.com/decamelize/-/decamelize-1.2.0.tgz",
+      "integrity": "sha512-z2S+W9X73hAUUki+N+9Za2lBlun89zigOyGrsax+KUQ6wKW4ZoWpEYBkGhQjwAjjDCkWxhY0VKEhk8wzY7F5cA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
     "node_modules/decimal.js": {
       "version": "10.6.0",
       "resolved": "https://registry.npmjs.org/decimal.js/-/decimal.js-10.6.0.tgz",
@@ -3029,6 +3100,12 @@
       "dev": true,
       "license": "Apache-2.0"
     },
+    "node_modules/dijkstrajs": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmmirror.com/dijkstrajs/-/dijkstrajs-1.0.3.tgz",
+      "integrity": "sha512-qiSlmBq9+BCdCA/L46dw8Uy93mloxsPSbwnm5yrKn2vMPiy8KyAskTF6zuV/j5BMsmOGZDPs7KjU+mjb670kfA==",
+      "license": "MIT"
+    },
     "node_modules/dir-glob": {
       "version": "3.0.1",
       "resolved": "https://registry.npmjs.org/dir-glob/-/dir-glob-3.0.1.tgz",
@@ -3759,6 +3836,15 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/get-caller-file": {
+      "version": "2.0.5",
+      "resolved": "https://registry.npmmirror.com/get-caller-file/-/get-caller-file-2.0.5.tgz",
+      "integrity": "sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg==",
+      "license": "ISC",
+      "engines": {
+        "node": "6.* || 8.* || >= 10.*"
+      }
+    },
     "node_modules/get-intrinsic": {
       "version": "1.3.0",
       "resolved": "https://registry.npmjs.org/get-intrinsic/-/get-intrinsic-1.3.0.tgz",
@@ -4156,7 +4242,6 @@
       "version": "3.0.0",
       "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz",
       "integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==",
-      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">=8"
@@ -4883,6 +4968,15 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/p-try": {
+      "version": "2.2.0",
+      "resolved": "https://registry.npmmirror.com/p-try/-/p-try-2.2.0.tgz",
+      "integrity": "sha512-R4nPAVTAU0B9D35/Gk3uJf/7XYbQcyohSKdvAxIRSNghFl4e71hVoGnBNQz9cWaXxO2I10KTC+3jMdvvoKw6dQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
     "node_modules/package-json-from-dist": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/package-json-from-dist/-/package-json-from-dist-1.0.1.tgz",
@@ -4957,7 +5051,6 @@
       "version": "4.0.0",
       "resolved": "https://registry.npmjs.org/path-exists/-/path-exists-4.0.0.tgz",
       "integrity": "sha512-ak9Qy5Q7jYb2Wwcey5Fpvg2KoAc/ZIhLSLOSBmRmygPsGwkVVt0fZa0qrtMz+m6tJTAHfZQ8FnmB4MG4LWy7/w==",
-      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">=8"
@@ -5093,6 +5186,15 @@
         "node": ">= 6"
       }
     },
+    "node_modules/pngjs": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmmirror.com/pngjs/-/pngjs-5.0.0.tgz",
+      "integrity": "sha512-40QW5YalBNfQo5yRYmiw7Yz6TKKVr3h6970B2YE+3fQpsWcrbj1PzJgxeJ19DRQjhMbKPIuMY8rFaXc8moolVw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=10.13.0"
+      }
+    },
     "node_modules/polished": {
       "version": "4.3.1",
       "resolved": "https://registry.npmjs.org/polished/-/polished-4.3.1.tgz",
@@ -5313,6 +5415,23 @@
         "node": ">=6"
       }
     },
+    "node_modules/qrcode": {
+      "version": "1.5.4",
+      "resolved": "https://registry.npmmirror.com/qrcode/-/qrcode-1.5.4.tgz",
+      "integrity": "sha512-1ca71Zgiu6ORjHqFBDpnSMTR2ReToX4l1Au1VFLyVeBTFavzQnv5JxMFr3ukHVKpSrSA2MCk0lNJSykjUfz7Zg==",
+      "license": "MIT",
+      "dependencies": {
+        "dijkstrajs": "^1.0.1",
+        "pngjs": "^5.0.0",
+        "yargs": "^15.3.1"
+      },
+      "bin": {
+        "qrcode": "bin/qrcode"
+      },
+      "engines": {
+        "node": ">=10.13.0"
+      }
+    },
     "node_modules/querystringify": {
       "version": "2.2.0",
       "resolved": "https://registry.npmjs.org/querystringify/-/querystringify-2.2.0.tgz",
@@ -5370,6 +5489,21 @@
         "node": ">=8.10.0"
       }
     },
+    "node_modules/require-directory": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmmirror.com/require-directory/-/require-directory-2.1.1.tgz",
+      "integrity": "sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/require-main-filename": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmmirror.com/require-main-filename/-/require-main-filename-2.0.0.tgz",
+      "integrity": "sha512-NKN5kMDylKuldxYLSUfrbo5Tuzh4hd+2E8NPPX02mZtn1VuREQToYe/ZdlJy+J3uCpfaiGF05e7B8W0iXbQHmg==",
+      "license": "ISC"
+    },
     "node_modules/requires-port": {
       "version": "1.0.0",
       "resolved": "https://registry.npmjs.org/requires-port/-/requires-port-1.0.0.tgz",
@@ -5543,6 +5677,12 @@
         "node": ">=10"
       }
     },
+    "node_modules/set-blocking": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmmirror.com/set-blocking/-/set-blocking-2.0.0.tgz",
+      "integrity": "sha512-KiKBS8AnWGEyLzofFfmvKwpdPzqiy16LvQfK3yv/fVH7Bj13/wl3JSR1J+rfgRE9q7xUJK4qvgS8raSOeLUehw==",
+      "license": "ISC"
+    },
     "node_modules/shebang-command": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/shebang-command/-/shebang-command-2.0.0.tgz",
@@ -5714,7 +5854,6 @@
       "version": "6.0.1",
       "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz",
       "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "ansi-regex": "^5.0.1"
@@ -6715,6 +6854,12 @@
         "node": ">= 8"
       }
     },
+    "node_modules/which-module": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmmirror.com/which-module/-/which-module-2.0.1.tgz",
+      "integrity": "sha512-iBdZ57RDvnOR9AGBhML2vFZf7h8vmBjhoaZqODJBFWHVtKkDmKuHai3cx5PgVMrX5YDNp27AofYbAwctSS+vhQ==",
+      "license": "ISC"
+    },
     "node_modules/why-is-node-running": {
       "version": "2.3.0",
       "resolved": "https://registry.npmjs.org/why-is-node-running/-/why-is-node-running-2.3.0.tgz",
@@ -6928,6 +7073,12 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/y18n": {
+      "version": "4.0.3",
+      "resolved": "https://registry.npmmirror.com/y18n/-/y18n-4.0.3.tgz",
+      "integrity": "sha512-JKhqTOwSrqNA1NY5lSztJ1GrBiUodLMmIZuLiDaMRJ+itFd+ABVE8XBjOvIWL+rSqNDC74LCSFmlb/U4UZ4hJQ==",
+      "license": "ISC"
+    },
     "node_modules/yaml": {
       "version": "1.10.2",
       "resolved": "https://registry.npmjs.org/yaml/-/yaml-1.10.2.tgz",
@@ -6937,6 +7088,113 @@
         "node": ">= 6"
       }
     },
+    "node_modules/yargs": {
+      "version": "15.4.1",
+      "resolved": "https://registry.npmmirror.com/yargs/-/yargs-15.4.1.tgz",
+      "integrity": "sha512-aePbxDmcYW++PaqBsJ+HYUFwCdv4LVvdnhBy78E57PIor8/OVvhMrADFFEDh8DHDFRv/O9i3lPhsENjO7QX0+A==",
+      "license": "MIT",
+      "dependencies": {
+        "cliui": "^6.0.0",
+        "decamelize": "^1.2.0",
+        "find-up": "^4.1.0",
+        "get-caller-file": "^2.0.1",
+        "require-directory": "^2.1.1",
+        "require-main-filename": "^2.0.0",
+        "set-blocking": "^2.0.0",
+        "string-width": "^4.2.0",
+        "which-module": "^2.0.0",
+        "y18n": "^4.0.0",
+        "yargs-parser": "^18.1.2"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/yargs-parser": {
+      "version": "18.1.3",
+      "resolved": "https://registry.npmmirror.com/yargs-parser/-/yargs-parser-18.1.3.tgz",
+      "integrity": "sha512-o50j0JeToy/4K6OZcaQmW6lyXXKhq7csREXcDwk2omFPJEwUNOVtJKvmDr9EI1fAJZUyZcRF7kxGBWmRXudrCQ==",
+      "license": "ISC",
+      "dependencies": {
+        "camelcase": "^5.0.0",
+        "decamelize": "^1.2.0"
+      },
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/yargs/node_modules/emoji-regex": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmmirror.com/emoji-regex/-/emoji-regex-8.0.0.tgz",
+      "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==",
+      "license": "MIT"
+    },
+    "node_modules/yargs/node_modules/find-up": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmmirror.com/find-up/-/find-up-4.1.0.tgz",
+      "integrity": "sha512-PpOwAdQ/YlXQ2vj8a3h8IipDuYRi3wceVQQGYWxNINccq40Anw7BlsEXCMbt1Zt+OLA6Fq9suIpIWD0OsnISlw==",
+      "license": "MIT",
+      "dependencies": {
+        "locate-path": "^5.0.0",
+        "path-exists": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/yargs/node_modules/locate-path": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmmirror.com/locate-path/-/locate-path-5.0.0.tgz",
+      "integrity": "sha512-t7hw9pI+WvuwNJXwk5zVHpyhIqzg2qTlklJOf0mVxGSbe3Fp2VieZcduNYjaLDoy6p9uGpQEGWG87WpMKlNq8g==",
+      "license": "MIT",
+      "dependencies": {
+        "p-locate": "^4.1.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/yargs/node_modules/p-limit": {
+      "version": "2.3.0",
+      "resolved": "https://registry.npmmirror.com/p-limit/-/p-limit-2.3.0.tgz",
+      "integrity": "sha512-//88mFWSJx8lxCzwdAABTJL2MyWB12+eIY7MDL2SqLmAkeKU9qxRvWuSyTjm3FUmpBEMuFfckAIqEaVGUDxb6w==",
+      "license": "MIT",
+      "dependencies": {
+        "p-try": "^2.0.0"
+      },
+      "engines": {
+        "node": ">=6"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/yargs/node_modules/p-locate": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmmirror.com/p-locate/-/p-locate-4.1.0.tgz",
+      "integrity": "sha512-R79ZZ/0wAxKGu3oYMlz8jy/kbhsNrS7SKZ7PxEHBgJ5+F2mtFW2fK2cOtBh1cHYkQsbzFV7I+EoRKe6Yt0oK7A==",
+      "license": "MIT",
+      "dependencies": {
+        "p-limit": "^2.2.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/yargs/node_modules/string-width": {
+      "version": "4.2.3",
+      "resolved": "https://registry.npmmirror.com/string-width/-/string-width-4.2.3.tgz",
+      "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==",
+      "license": "MIT",
+      "dependencies": {
+        "emoji-regex": "^8.0.0",
+        "is-fullwidth-code-point": "^3.0.0",
+        "strip-ansi": "^6.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/yocto-queue": {
       "version": "0.1.0",
       "resolved": "https://registry.npmjs.org/yocto-queue/-/yocto-queue-0.1.0.tgz",

frontend/package.json

@@ -22,6 +22,7 @@
     "driver.js": "^1.4.0",
     "file-saver": "^2.0.5",
     "pinia": "^2.1.7",
+    "qrcode": "^1.5.4",
     "vue": "^3.4.0",
     "vue-chartjs": "^5.3.0",
     "vue-i18n": "^9.14.5",
@@ -32,6 +33,7 @@
     "@types/file-saver": "^2.0.7",
     "@types/mdx": "^2.0.13",
     "@types/node": "^20.10.5",
+    "@types/qrcode": "^1.5.6",
     "@typescript-eslint/eslint-plugin": "^7.18.0",
     "@typescript-eslint/parser": "^7.18.0",
     "@vitejs/plugin-vue": "^5.2.3",

frontend/pnpm-lock.yaml

@@ -29,6 +29,9 @@ importers:
       pinia:
         specifier: ^2.1.7
         version: 2.3.1(typescript@5.6.3)(vue@3.5.26(typescript@5.6.3))
+      qrcode:
+        specifier: ^1.5.4
+        version: 1.5.4
       vue:
         specifier: ^3.4.0
         version: 3.5.26(typescript@5.6.3)
@@ -54,6 +57,9 @@ importers:
       '@types/node':
         specifier: ^20.10.5
         version: 20.19.27
+      '@types/qrcode':
+        specifier: ^1.5.6
+        version: 1.5.6
       '@typescript-eslint/eslint-plugin':
         specifier: ^7.18.0
         version: 7.18.0(@typescript-eslint/parser@7.18.0(eslint@8.57.1)(typescript@5.6.3))(eslint@8.57.1)(typescript@5.6.3)
@@ -1239,56 +1245,67 @@ packages:
     resolution: {integrity: sha512-EHMUcDwhtdRGlXZsGSIuXSYwD5kOT9NVnx9sqzYiwAc91wfYOE1g1djOEDseZJKKqtHAHGwnGPQu3kytmfaXLQ==}
     cpu: [arm]
     os: [linux]
+    libc: [glibc]
 
   '@rollup/rollup-linux-arm-musleabihf@4.54.0':
     resolution: {integrity: sha512-+pBrqEjaakN2ySv5RVrj/qLytYhPKEUwk+e3SFU5jTLHIcAtqh2rLrd/OkbNuHJpsBgxsD8ccJt5ga/SeG0JmA==}
     cpu: [arm]
     os: [linux]
+    libc: [musl]
 
   '@rollup/rollup-linux-arm64-gnu@4.54.0':
     resolution: {integrity: sha512-NSqc7rE9wuUaRBsBp5ckQ5CVz5aIRKCwsoa6WMF7G01sX3/qHUw/z4pv+D+ahL1EIKy6Enpcnz1RY8pf7bjwng==}
     cpu: [arm64]
     os: [linux]
+    libc: [glibc]
 
   '@rollup/rollup-linux-arm64-musl@4.54.0':
     resolution: {integrity: sha512-gr5vDbg3Bakga5kbdpqx81m2n9IX8M6gIMlQQIXiLTNeQW6CucvuInJ91EuCJ/JYvc+rcLLsDFcfAD1K7fMofg==}
     cpu: [arm64]
     os: [linux]
+    libc: [musl]
 
   '@rollup/rollup-linux-loong64-gnu@4.54.0':
     resolution: {integrity: sha512-gsrtB1NA3ZYj2vq0Rzkylo9ylCtW/PhpLEivlgWe0bpgtX5+9j9EZa0wtZiCjgu6zmSeZWyI/e2YRX1URozpIw==}
     cpu: [loong64]
     os: [linux]
+    libc: [glibc]
 
   '@rollup/rollup-linux-ppc64-gnu@4.54.0':
     resolution: {integrity: sha512-y3qNOfTBStmFNq+t4s7Tmc9hW2ENtPg8FeUD/VShI7rKxNW7O4fFeaYbMsd3tpFlIg1Q8IapFgy7Q9i2BqeBvA==}
     cpu: [ppc64]
     os: [linux]
+    libc: [glibc]
 
   '@rollup/rollup-linux-riscv64-gnu@4.54.0':
     resolution: {integrity: sha512-89sepv7h2lIVPsFma8iwmccN7Yjjtgz0Rj/Ou6fEqg3HDhpCa+Et+YSufy27i6b0Wav69Qv4WBNl3Rs6pwhebQ==}
     cpu: [riscv64]
     os: [linux]
+    libc: [glibc]
 
   '@rollup/rollup-linux-riscv64-musl@4.54.0':
     resolution: {integrity: sha512-ZcU77ieh0M2Q8Ur7D5X7KvK+UxbXeDHwiOt/CPSBTI1fBmeDMivW0dPkdqkT4rOgDjrDDBUed9x4EgraIKoR2A==}
     cpu: [riscv64]
     os: [linux]
+    libc: [musl]
 
   '@rollup/rollup-linux-s390x-gnu@4.54.0':
     resolution: {integrity: sha512-2AdWy5RdDF5+4YfG/YesGDDtbyJlC9LHmL6rZw6FurBJ5n4vFGupsOBGfwMRjBYH7qRQowT8D/U4LoSvVwOhSQ==}
     cpu: [s390x]
     os: [linux]
+    libc: [glibc]
 
   '@rollup/rollup-linux-x64-gnu@4.54.0':
     resolution: {integrity: sha512-WGt5J8Ij/rvyqpFexxk3ffKqqbLf9AqrTBbWDk7ApGUzaIs6V+s2s84kAxklFwmMF/vBNGrVdYgbblCOFFezMQ==}
     cpu: [x64]
     os: [linux]
+    libc: [glibc]
 
   '@rollup/rollup-linux-x64-musl@4.54.0':
     resolution: {integrity: sha512-JzQmb38ATzHjxlPHuTH6tE7ojnMKM2kYNzt44LO/jJi8BpceEC8QuXYA908n8r3CNuG/B3BV8VR3Hi1rYtmPiw==}
     cpu: [x64]
     os: [linux]
+    libc: [musl]
 
   '@rollup/rollup-openharmony-arm64@4.54.0':
     resolution: {integrity: sha512-huT3fd0iC7jigGh7n3q/+lfPcXxBi+om/Rs3yiFxjvSxbSB6aohDFXbWvlspaqjeOh+hx7DDHS+5Es5qRkWkZg==}
@@ -1479,6 +1496,9 @@ packages:
   '@types/parse-json@4.0.2':
     resolution: {integrity: sha512-dISoDXWWQwUquiKsyZ4Ng+HX2KsPL7LyHKHQwgGFEA3IaKac4Obd+h2a/a6waisAoepJlBcx9paWqjA8/HVjCw==}
 
+  '@types/qrcode@1.5.6':
+    resolution: {integrity: sha512-te7NQcV2BOvdj2b1hCAHzAoMNuj65kNBMz0KBaxM6c3VGBOhU0dURQKOtH8CFNI/dsKkwlv32p26qYQTWoB5bw==}
+
   '@types/react@19.2.7':
     resolution: {integrity: sha512-MWtvHrGZLFttgeEj28VXHxpmwYbor/ATPYbBfSFZEIRK0ecCFLl2Qo55z52Hss+UV9CRN7trSeq1zbgx7YDWWg==}
 
@@ -1832,6 +1852,10 @@ packages:
     resolution: {integrity: sha512-QOSvevhslijgYwRx6Rv7zKdMF8lbRmx+uQGx2+vDc+KI/eBnsy9kit5aj23AgGu3pa4t9AgwbnXWqS+iOY+2aA==}
     engines: {node: '>= 6'}
 
+  camelcase@5.3.1:
+    resolution: {integrity: sha512-L28STB170nwWS63UjtlEOE3dldQApaJXZkOI1uMFfzf3rRuPegHaHesyee+YxQ+W6SvRDQV6UrdOdRiR153wJg==}
+    engines: {node: '>=6'}
+
   caniuse-lite@1.0.30001761:
     resolution: {integrity: sha512-JF9ptu1vP2coz98+5051jZ4PwQgd2ni8A+gYSN7EA7dPKIMf0pDlSUxhdmVOaV3/fYK5uWBkgSXJaRLr4+3A6g==}
 
@@ -1895,6 +1919,9 @@ packages:
   classnames@2.5.1:
     resolution: {integrity: sha512-saHYOzhIQs6wy2sVxTM6bUDsQO4F50V9RQ22qBpEdCW+I+/Wmke2HOl6lS6dTpdxVhb88/I6+Hs+438c3lfUow==}
 
+  cliui@6.0.0:
+    resolution: {integrity: sha512-t6wbgtoCXvAzst7QgXxJYqPt0usEfbgQdftEPbLL/cvv6HPE5VgvqCuAIDR0NgU52ds6rFwqrgakNLrHEjCbrQ==}
+
   clsx@1.2.1:
     resolution: {integrity: sha512-EcR6r5a8bj6pu3ycsa/E/cKVGuTgZJZdsyUYHOksG/UHIiKfjxzRxYJpyVBwYaQeOvghal9fcc4PidlgzugAQg==}
     engines: {node: '>=6'}
@@ -2164,6 +2191,10 @@ packages:
       supports-color:
         optional: true
 
+  decamelize@1.2.0:
+    resolution: {integrity: sha512-z2S+W9X73hAUUki+N+9Za2lBlun89zigOyGrsax+KUQ6wKW4ZoWpEYBkGhQjwAjjDCkWxhY0VKEhk8wzY7F5cA==}
+    engines: {node: '>=0.10.0'}
+
   decimal.js@10.6.0:
     resolution: {integrity: sha512-YpgQiITW3JXGntzdUmyUR1V812Hn8T1YVXhCu+wO3OpS4eU9l4YdD3qjyiKdV6mvV29zapkMeD390UVEf2lkUg==}
 
@@ -2198,6 +2229,9 @@ packages:
   didyoumean@1.2.2:
     resolution: {integrity: sha512-gxtyfqMg7GKyhQmb056K7M3xszy/myH8w+B4RT+QXBQsvAOdc3XymqDDPHx1BgPgsdAA5SIifona89YtRATDzw==}
 
+  dijkstrajs@1.0.3:
+    resolution: {integrity: sha512-qiSlmBq9+BCdCA/L46dw8Uy93mloxsPSbwnm5yrKn2vMPiy8KyAskTF6zuV/j5BMsmOGZDPs7KjU+mjb670kfA==}
+
   dir-glob@3.0.1:
     resolution: {integrity: sha512-WkrWp9GR4KXfKGYzOLmTuGVi1UWFfws377n9cc55/tb6DuqyF6pcQ5AbiHEshaDpY9v6oaSr2XCDidGmMwdzIA==}
     engines: {node: '>=8'}
@@ -2424,6 +2458,10 @@ packages:
   find-root@1.1.0:
     resolution: {integrity: sha512-NKfW6bec6GfKc0SGx1e07QZY9PE99u0Bft/0rzSD5k3sO/vwkVUpDUKVm5Gpp5Ue3YfShPFTX2070tDs5kB9Ng==}
 
+  find-up@4.1.0:
+    resolution: {integrity: sha512-PpOwAdQ/YlXQ2vj8a3h8IipDuYRi3wceVQQGYWxNINccq40Anw7BlsEXCMbt1Zt+OLA6Fq9suIpIWD0OsnISlw==}
+    engines: {node: '>=8'}
+
   find-up@5.0.0:
     resolution: {integrity: sha512-78/PXT1wlLLDgTzDs7sjq9hzz0vXD+zn+7wypEe4fXQxCmdmqfGsEPQxmiCSQI3ajFV91bVSsvNtrJRiW6nGng==}
     engines: {node: '>=10'}
@@ -2488,6 +2526,10 @@ packages:
   function-bind@1.1.2:
     resolution: {integrity: sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA==}
 
+  get-caller-file@2.0.5:
+    resolution: {integrity: sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg==}
+    engines: {node: 6.* || 8.* || >= 10.*}
+
   get-east-asian-width@1.4.0:
     resolution: {integrity: sha512-QZjmEOC+IT1uk6Rx0sX22V6uHWVwbdbxf1faPqJ1QhLdGgsRGCZoyaQBm/piRdJy/D2um6hM1UP7ZEeQ4EkP+Q==}
     engines: {node: '>=18'}
@@ -2856,6 +2898,10 @@ packages:
   lit@3.3.2:
     resolution: {integrity: sha512-NF9zbsP79l4ao2SNrH3NkfmFgN/hBYSQo90saIVI1o5GpjAdCPVstVzO1MrLOakHoEhYkrtRjPK6Ob521aoYWQ==}
 
+  locate-path@5.0.0:
+    resolution: {integrity: sha512-t7hw9pI+WvuwNJXwk5zVHpyhIqzg2qTlklJOf0mVxGSbe3Fp2VieZcduNYjaLDoy6p9uGpQEGWG87WpMKlNq8g==}
+    engines: {node: '>=8'}
+
   locate-path@6.0.0:
     resolution: {integrity: sha512-iPZK6eYjbxRu3uB4/WZ3EsEIMJFMqAoopl3R+zuq0UjcAm/MO6KCweDgPfP3elTztoKP3KtnVHxTn2NHBSDVUw==}
     engines: {node: '>=10'}
@@ -3239,14 +3285,26 @@ packages:
     resolution: {integrity: sha512-6IpQ7mKUxRcZNLIObR0hz7lxsapSSIYNZJwXPGeF0mTVqGKFIXj1DQcMoT22S3ROcLyY/rz0PWaWZ9ayWmad9g==}
     engines: {node: '>= 0.8.0'}
 
+  p-limit@2.3.0:
+    resolution: {integrity: sha512-//88mFWSJx8lxCzwdAABTJL2MyWB12+eIY7MDL2SqLmAkeKU9qxRvWuSyTjm3FUmpBEMuFfckAIqEaVGUDxb6w==}
+    engines: {node: '>=6'}
+
   p-limit@3.1.0:
     resolution: {integrity: sha512-TYOanM3wGwNGsZN2cVTYPArw454xnXj5qmWF1bEoAc4+cU/ol7GVh7odevjp1FNHduHc3KZMcFduxU5Xc6uJRQ==}
     engines: {node: '>=10'}
 
+  p-locate@4.1.0:
+    resolution: {integrity: sha512-R79ZZ/0wAxKGu3oYMlz8jy/kbhsNrS7SKZ7PxEHBgJ5+F2mtFW2fK2cOtBh1cHYkQsbzFV7I+EoRKe6Yt0oK7A==}
+    engines: {node: '>=8'}
+
   p-locate@5.0.0:
     resolution: {integrity: sha512-LaNjtRWUBY++zB5nE/NwcaoMylSPk+S+ZHNB1TzdbMJMny6dynpAGt7X/tl/QYq3TIeE6nxHppbo2LGymrG5Pw==}
     engines: {node: '>=10'}
 
+  p-try@2.2.0:
+    resolution: {integrity: sha512-R4nPAVTAU0B9D35/Gk3uJf/7XYbQcyohSKdvAxIRSNghFl4e71hVoGnBNQz9cWaXxO2I10KTC+3jMdvvoKw6dQ==}
+    engines: {node: '>=6'}
+
   package-json-from-dist@1.0.1:
     resolution: {integrity: sha512-UEZIS3/by4OC8vL3P2dTXRETpebLI2NiI5vIrjaD/5UtrkFX/tNbwjTSRAGC/+7CAo2pIcBaRgWmcBBHcsaCIw==}
 
@@ -3341,6 +3399,10 @@ packages:
   pkg-types@1.3.1:
     resolution: {integrity: sha512-/Jm5M4RvtBFVkKWRu2BLUTNP8/M2a+UwuAX+ae4770q1qVGtfjG+WTCupoZixokjmHiry8uI+dlY8KXYV5HVVQ==}
 
+  pngjs@5.0.0:
+    resolution: {integrity: sha512-40QW5YalBNfQo5yRYmiw7Yz6TKKVr3h6970B2YE+3fQpsWcrbj1PzJgxeJ19DRQjhMbKPIuMY8rFaXc8moolVw==}
+    engines: {node: '>=10.13.0'}
+
   points-on-curve@0.2.0:
     resolution: {integrity: sha512-0mYKnYYe9ZcqMCWhUjItv/oHjvgEsfKvnUTg8sAtnHr3GVy7rGkXCb6d5cSyqrWqL4k81b9CPg3urd+T7aop3A==}
 
@@ -3421,6 +3483,11 @@ packages:
     resolution: {integrity: sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg==}
     engines: {node: '>=6'}
 
+  qrcode@1.5.4:
+    resolution: {integrity: sha512-1ca71Zgiu6ORjHqFBDpnSMTR2ReToX4l1Au1VFLyVeBTFavzQnv5JxMFr3ukHVKpSrSA2MCk0lNJSykjUfz7Zg==}
+    engines: {node: '>=10.13.0'}
+    hasBin: true
+
   query-string@9.3.1:
     resolution: {integrity: sha512-5fBfMOcDi5SA9qj5jZhWAcTtDfKF5WFdd2uD9nVNlbxVv1baq65aALy6qofpNEGELHvisjjasxQp7BlM9gvMzw==}
     engines: {node: '>=18'}
@@ -3664,6 +3731,13 @@ packages:
   remark-stringify@11.0.0:
     resolution: {integrity: sha512-1OSmLd3awB/t8qdoEOMazZkNsfVTeY4fTsgzcQFdXNq8ToTN4ZGwrMnlda4K6smTFKD+GRV6O48i6Z4iKgPPpw==}
 
+  require-directory@2.1.1:
+    resolution: {integrity: sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q==}
+    engines: {node: '>=0.10.0'}
+
+  require-main-filename@2.0.0:
+    resolution: {integrity: sha512-NKN5kMDylKuldxYLSUfrbo5Tuzh4hd+2E8NPPX02mZtn1VuREQToYe/ZdlJy+J3uCpfaiGF05e7B8W0iXbQHmg==}
+
   requires-port@1.0.0:
     resolution: {integrity: sha512-KigOCHcocU3XODJxsu8i/j8T9tzT4adHiecwORRQ0ZZFcp7ahwXuRU1m+yuO90C5ZUyGeGfocHDI14M3L3yDAQ==}
 
@@ -3739,6 +3813,9 @@ packages:
     engines: {node: '>=10'}
     hasBin: true
 
+  set-blocking@2.0.0:
+    resolution: {integrity: sha512-KiKBS8AnWGEyLzofFfmvKwpdPzqiy16LvQfK3yv/fVH7Bj13/wl3JSR1J+rfgRE9q7xUJK4qvgS8raSOeLUehw==}
+
   set-value@2.0.1:
     resolution: {integrity: sha512-JxHc1weCN68wRY0fhCoXpyK55m/XPHafOmK4UWD7m2CI14GMcFypt4w/0+NV5f/ZMby2F6S2wwA7fgynh9gWSw==}
     engines: {node: '>=0.10.0'}
@@ -4263,6 +4340,9 @@ packages:
     resolution: {integrity: sha512-De72GdQZzNTUBBChsXueQUnPKDkg/5A5zp7pFDuQAj5UFoENpiACU0wlCvzpAGnTkj++ihpKwKyYewn/XNUbKw==}
     engines: {node: '>=18'}
 
+  which-module@2.0.1:
+    resolution: {integrity: sha512-iBdZ57RDvnOR9AGBhML2vFZf7h8vmBjhoaZqODJBFWHVtKkDmKuHai3cx5PgVMrX5YDNp27AofYbAwctSS+vhQ==}
+
   which@2.0.2:
     resolution: {integrity: sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==}
     engines: {node: '>= 8'}
@@ -4285,6 +4365,10 @@ packages:
     resolution: {integrity: sha512-OELeY0Q61OXpdUfTp+oweA/vtLVg5VDOXh+3he3PNzLGG/y0oylSOC1xRVj0+l4vQ3tj/bB1HVHv1ocXkQceFA==}
     engines: {node: '>=0.8'}
 
+  wrap-ansi@6.2.0:
+    resolution: {integrity: sha512-r6lPcBGxZXlIcymEu7InxDMhdW0KDxpLgoFLcguasxCaJ/SOIZwINatK9KY/tf+ZrlywOKU0UDj3ATXUBfxJXA==}
+    engines: {node: '>=8'}
+
   wrap-ansi@7.0.0:
     resolution: {integrity: sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==}
     engines: {node: '>=10'}
@@ -4324,10 +4408,21 @@ packages:
   xmlchars@2.2.0:
     resolution: {integrity: sha512-JZnDKK8B0RCDw84FNdDAIpZK+JuJw+s7Lz8nksI7SIuU3UXJJslUthsi+uWBUYOwPFwW7W7PRLRfUKpxjtjFCw==}
 
+  y18n@4.0.3:
+    resolution: {integrity: sha512-JKhqTOwSrqNA1NY5lSztJ1GrBiUodLMmIZuLiDaMRJ+itFd+ABVE8XBjOvIWL+rSqNDC74LCSFmlb/U4UZ4hJQ==}
+
   yaml@1.10.2:
     resolution: {integrity: sha512-r3vXyErRCYJ7wg28yvBY5VSoAF8ZvlcW9/BwUzEtUsjvX/DKs24dIkuwjtuprwJJHsbyUbLApepYTR1BN4uHrg==}
     engines: {node: '>= 6'}
 
+  yargs-parser@18.1.3:
+    resolution: {integrity: sha512-o50j0JeToy/4K6OZcaQmW6lyXXKhq7csREXcDwk2omFPJEwUNOVtJKvmDr9EI1fAJZUyZcRF7kxGBWmRXudrCQ==}
+    engines: {node: '>=6'}
+
+  yargs@15.4.1:
+    resolution: {integrity: sha512-aePbxDmcYW++PaqBsJ+HYUFwCdv4LVvdnhBy78E57PIor8/OVvhMrADFFEDh8DHDFRv/O9i3lPhsENjO7QX0+A==}
+    engines: {node: '>=8'}
+
   yocto-queue@0.1.0:
     resolution: {integrity: sha512-rVksvsnNCdJ/ohGc6xgPwyN8eheCxsiLM8mxuE/t/mOVqJewPuO1miLpTHQiRgTKCLexL4MeAFVagts7HmNZ2Q==}
     engines: {node: '>=10'}
@@ -5838,6 +5933,10 @@ snapshots:
 
   '@types/parse-json@4.0.2': {}
 
+  '@types/qrcode@1.5.6':
+    dependencies:
+      '@types/node': 20.19.27
+
   '@types/react@19.2.7':
     dependencies:
       csstype: 3.2.3
@@ -6321,6 +6420,8 @@ snapshots:
 
   camelcase-css@2.0.1: {}
 
+  camelcase@5.3.1: {}
+
   caniuse-lite@1.0.30001761: {}
 
   ccount@2.0.1: {}
@@ -6395,6 +6496,12 @@ snapshots:
 
   classnames@2.5.1: {}
 
+  cliui@6.0.0:
+    dependencies:
+      string-width: 4.2.3
+      strip-ansi: 6.0.1
+      wrap-ansi: 6.2.0
+
   clsx@1.2.1: {}
 
   clsx@2.1.1: {}
@@ -6668,6 +6775,8 @@ snapshots:
     dependencies:
       ms: 2.1.3
 
+  decamelize@1.2.0: {}
+
   decimal.js@10.6.0: {}
 
   decode-named-character-reference@1.2.0:
@@ -6694,6 +6803,8 @@ snapshots:
 
   didyoumean@1.2.2: {}
 
+  dijkstrajs@1.0.3: {}
+
   dir-glob@3.0.1:
     dependencies:
       path-type: 4.0.0
@@ -6978,6 +7089,11 @@ snapshots:
 
   find-root@1.1.0: {}
 
+  find-up@4.1.0:
+    dependencies:
+      locate-path: 5.0.0
+      path-exists: 4.0.0
+
   find-up@5.0.0:
     dependencies:
       locate-path: 6.0.0
@@ -7029,6 +7145,8 @@ snapshots:
 
   function-bind@1.1.2: {}
 
+  get-caller-file@2.0.5: {}
+
   get-east-asian-width@1.4.0: {}
 
   get-intrinsic@1.3.0:
@@ -7521,6 +7639,10 @@ snapshots:
       lit-element: 4.2.2
       lit-html: 3.3.2
 
+  locate-path@5.0.0:
+    dependencies:
+      p-locate: 4.1.0
+
   locate-path@6.0.0:
     dependencies:
       p-locate: 5.0.0
@@ -8194,14 +8316,24 @@ snapshots:
       type-check: 0.4.0
       word-wrap: 1.2.5
 
+  p-limit@2.3.0:
+    dependencies:
+      p-try: 2.2.0
+
   p-limit@3.1.0:
     dependencies:
       yocto-queue: 0.1.0
 
+  p-locate@4.1.0:
+    dependencies:
+      p-limit: 2.3.0
+
   p-locate@5.0.0:
     dependencies:
       p-limit: 3.1.0
 
+  p-try@2.2.0: {}
+
   package-json-from-dist@1.0.1: {}
 
   package-manager-detector@1.6.0: {}
@@ -8284,6 +8416,8 @@ snapshots:
       mlly: 1.8.0
       pathe: 2.0.3
 
+  pngjs@5.0.0: {}
+
   points-on-curve@0.2.0: {}
 
   points-on-path@0.2.1:
@@ -8352,6 +8486,12 @@ snapshots:
 
   punycode@2.3.1: {}
 
+  qrcode@1.5.4:
+    dependencies:
+      dijkstrajs: 1.0.3
+      pngjs: 5.0.0
+      yargs: 15.4.1
+
   query-string@9.3.1:
     dependencies:
       decode-uri-component: 0.4.1
@@ -8703,6 +8843,10 @@ snapshots:
       mdast-util-to-markdown: 2.1.2
       unified: 11.0.5
 
+  require-directory@2.1.1: {}
+
+  require-main-filename@2.0.0: {}
+
   requires-port@1.0.0: {}
 
   reselect@5.1.1: {}
@@ -8788,6 +8932,8 @@ snapshots:
 
   semver@7.7.3: {}
 
+  set-blocking@2.0.0: {}
+
   set-value@2.0.1:
     dependencies:
       extend-shallow: 2.0.1
@@ -9298,6 +9444,8 @@ snapshots:
       tr46: 5.1.1
       webidl-conversions: 7.0.0
 
+  which-module@2.0.1: {}
+
   which@2.0.2:
     dependencies:
       isexe: 2.0.0
@@ -9313,6 +9461,12 @@ snapshots:
 
   word@0.3.0: {}
 
+  wrap-ansi@6.2.0:
+    dependencies:
+      ansi-styles: 4.3.0
+      string-width: 4.2.3
+      strip-ansi: 6.0.1
+
   wrap-ansi@7.0.0:
     dependencies:
       ansi-styles: 4.3.0
@@ -9345,8 +9499,29 @@ snapshots:
 
   xmlchars@2.2.0: {}
 
+  y18n@4.0.3: {}
+
   yaml@1.10.2: {}
 
+  yargs-parser@18.1.3:
+    dependencies:
+      camelcase: 5.3.1
+      decamelize: 1.2.0
+
+  yargs@15.4.1:
+    dependencies:
+      cliui: 6.0.0
+      decamelize: 1.2.0
+      find-up: 4.1.0
+      get-caller-file: 2.0.5
+      require-directory: 2.1.1
+      require-main-filename: 2.0.0
+      set-blocking: 2.0.0
+      string-width: 4.2.3
+      which-module: 2.0.1
+      y18n: 4.0.3
+      yargs-parser: 18.1.3
+
   yocto-queue@0.1.0: {}
 
   zustand@3.7.2(react@19.2.3):

frontend/src/api/admin/settings.ts

@@ -14,6 +14,8 @@ export interface SystemSettings {
   email_verify_enabled: boolean
   promo_code_enabled: boolean
   password_reset_enabled: boolean
+  totp_enabled: boolean // TOTP 双因素认证
+  totp_encryption_key_configured: boolean // TOTP 加密密钥是否已配置
   // Default settings
   default_balance: number
   default_concurrency: number
@@ -68,6 +70,7 @@ export interface UpdateSettingsRequest {
   email_verify_enabled?: boolean
   promo_code_enabled?: boolean
   password_reset_enabled?: boolean
+  totp_enabled?: boolean // TOTP 双因素认证
   default_balance?: number
   default_concurrency?: number
   site_name?: string

frontend/src/api/auth.ts

@@ -11,9 +11,23 @@ import type {
   CurrentUserResponse,
   SendVerifyCodeRequest,
   SendVerifyCodeResponse,
-  PublicSettings
+  PublicSettings,
+  TotpLoginResponse,
+  TotpLogin2FARequest
 } from '@/types'
 
+/**
+ * Login response type - can be either full auth or 2FA required
+ */
+export type LoginResponse = AuthResponse | TotpLoginResponse
+
+/**
+ * Type guard to check if login response requires 2FA
+ */
+export function isTotp2FARequired(response: LoginResponse): response is TotpLoginResponse {
+  return 'requires_2fa' in response && response.requires_2fa === true
+}
+
 /**
  * Store authentication token in localStorage
  */
@@ -38,11 +52,28 @@ export function clearAuthToken(): void {
 
 /**
  * User login
- * @param credentials - Username and password
+ * @param credentials - Email and password
+ * @returns Authentication response with token and user data, or 2FA required response
+ */
+export async function login(credentials: LoginRequest): Promise<LoginResponse> {
+  const { data } = await apiClient.post<LoginResponse>('/auth/login', credentials)
+
+  // Only store token if 2FA is not required
+  if (!isTotp2FARequired(data)) {
+    setAuthToken(data.access_token)
+    localStorage.setItem('auth_user', JSON.stringify(data.user))
+  }
+
+  return data
+}
+
+/**
+ * Complete login with 2FA code
+ * @param request - Temp token and TOTP code
  * @returns Authentication response with token and user data
  */
-export async function login(credentials: LoginRequest): Promise<AuthResponse> {
+export async function login2FA(request: TotpLogin2FARequest): Promise<AuthResponse> {
-  const { data } = await apiClient.post<AuthResponse>('/auth/login', credentials)
+  const { data } = await apiClient.post<AuthResponse>('/auth/login/2fa', request)
 
   // Store token and user data
   setAuthToken(data.access_token)
@@ -186,6 +217,8 @@ export async function resetPassword(request: ResetPasswordRequest): Promise<Rese
 
 export const authAPI = {
   login,
+  login2FA,
+  isTotp2FARequired,
   register,
   getCurrentUser,
   logout,

frontend/src/api/index.ts

@@ -7,7 +7,7 @@
 export { apiClient } from './client'
 
 // Auth API
-export { authAPI } from './auth'
+export { authAPI, isTotp2FARequired, type LoginResponse } from './auth'
 
 // User APIs
 export { keysAPI } from './keys'
@@ -15,6 +15,7 @@ export { usageAPI } from './usage'
 export { userAPI } from './user'
 export { redeemAPI, type RedeemHistoryItem } from './redeem'
 export { userGroupsAPI } from './groups'
+export { totpAPI } from './totp'
 
 // Admin APIs
 export { adminAPI } from './admin'

frontend/src/api/totp.ts

@@ -0,0 +1,83 @@
+/**
+ * TOTP (2FA) API endpoints
+ * Handles Two-Factor Authentication with Google Authenticator
+ */
+
+import { apiClient } from './client'
+import type {
+  TotpStatus,
+  TotpSetupRequest,
+  TotpSetupResponse,
+  TotpEnableRequest,
+  TotpEnableResponse,
+  TotpDisableRequest,
+  TotpVerificationMethod
+} from '@/types'
+
+/**
+ * Get TOTP status for current user
+ * @returns TOTP status including enabled state and feature availability
+ */
+export async function getStatus(): Promise<TotpStatus> {
+  const { data } = await apiClient.get<TotpStatus>('/user/totp/status')
+  return data
+}
+
+/**
+ * Get verification method for TOTP operations
+ * @returns Method ('email' or 'password') required for setup/disable
+ */
+export async function getVerificationMethod(): Promise<TotpVerificationMethod> {
+  const { data } = await apiClient.get<TotpVerificationMethod>('/user/totp/verification-method')
+  return data
+}
+
+/**
+ * Send email verification code for TOTP operations
+ * @returns Success response
+ */
+export async function sendVerifyCode(): Promise<{ success: boolean }> {
+  const { data } = await apiClient.post<{ success: boolean }>('/user/totp/send-code')
+  return data
+}
+
+/**
+ * Initiate TOTP setup - generates secret and QR code
+ * @param request - Email code or password depending on verification method
+ * @returns Setup response with secret, QR code URL, and setup token
+ */
+export async function initiateSetup(request?: TotpSetupRequest): Promise<TotpSetupResponse> {
+  const { data } = await apiClient.post<TotpSetupResponse>('/user/totp/setup', request || {})
+  return data
+}
+
+/**
+ * Complete TOTP setup by verifying the code
+ * @param request - TOTP code and setup token
+ * @returns Enable response with success status and enabled timestamp
+ */
+export async function enable(request: TotpEnableRequest): Promise<TotpEnableResponse> {
+  const { data } = await apiClient.post<TotpEnableResponse>('/user/totp/enable', request)
+  return data
+}
+
+/**
+ * Disable TOTP for current user
+ * @param request - Email code or password depending on verification method
+ * @returns Success response
+ */
+export async function disable(request: TotpDisableRequest): Promise<{ success: boolean }> {
+  const { data } = await apiClient.post<{ success: boolean }>('/user/totp/disable', request)
+  return data
+}
+
+export const totpAPI = {
+  getStatus,
+  getVerificationMethod,
+  sendVerifyCode,
+  initiateSetup,
+  enable,
+  disable
+}
+
+export default totpAPI

frontend/src/components/auth/TotpLoginModal.vue

@@ -0,0 +1,176 @@
+<template>
+  <div class="fixed inset-0 z-50 overflow-y-auto">
+    <div class="flex min-h-full items-center justify-center p-4">
+      <div class="fixed inset-0 bg-black/50 transition-opacity"></div>
+
+      <div class="relative w-full max-w-md transform rounded-xl bg-white p-6 shadow-xl transition-all dark:bg-dark-800">
+        <!-- Header -->
+        <div class="mb-6 text-center">
+          <div class="mx-auto flex h-12 w-12 items-center justify-center rounded-full bg-primary-100 dark:bg-primary-900/30">
+            <svg class="h-6 w-6 text-primary-600 dark:text-primary-400" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="1.5">
+              <path stroke-linecap="round" stroke-linejoin="round" d="M9 12.75L11.25 15 15 9.75m-3-7.036A11.959 11.959 0 013.598 6 11.99 11.99 0 003 9.749c0 5.592 3.824 10.29 9 11.623 5.176-1.332 9-6.03 9-11.622 0-1.31-.21-2.571-.598-3.751h-.152c-3.196 0-6.1-1.248-8.25-3.285z" />
+            </svg>
+          </div>
+          <h3 class="mt-4 text-xl font-semibold text-gray-900 dark:text-white">
+            {{ t('profile.totp.loginTitle') }}
+          </h3>
+          <p class="mt-2 text-sm text-gray-500 dark:text-gray-400">
+            {{ t('profile.totp.loginHint') }}
+          </p>
+          <p v-if="userEmailMasked" class="mt-1 text-sm font-medium text-gray-700 dark:text-gray-300">
+            {{ userEmailMasked }}
+          </p>
+        </div>
+
+        <!-- Code Input -->
+        <div class="mb-6">
+          <div class="flex justify-center gap-2">
+            <input
+              v-for="(_, index) in 6"
+              :key="index"
+              :ref="(el) => setInputRef(el, index)"
+              type="text"
+              maxlength="1"
+              inputmode="numeric"
+              pattern="[0-9]"
+              class="h-12 w-10 rounded-lg border border-gray-300 text-center text-lg font-semibold focus:border-primary-500 focus:ring-primary-500 dark:border-dark-600 dark:bg-dark-700"
+              :disabled="verifying"
+              @input="handleCodeInput($event, index)"
+              @keydown="handleKeydown($event, index)"
+              @paste="handlePaste"
+            />
+          </div>
+          <!-- Loading indicator -->
+          <div v-if="verifying" class="mt-3 flex items-center justify-center gap-2 text-sm text-gray-500">
+            <div class="animate-spin rounded-full h-4 w-4 border-b-2 border-primary-500"></div>
+            {{ t('common.verifying') }}
+          </div>
+        </div>
+
+        <!-- Error -->
+        <div v-if="error" class="mb-4 rounded-lg bg-red-50 p-3 text-sm text-red-700 dark:bg-red-900/30 dark:text-red-400">
+          {{ error }}
+        </div>
+
+        <!-- Cancel button only -->
+        <button
+          type="button"
+          class="btn btn-secondary w-full"
+          :disabled="verifying"
+          @click="$emit('cancel')"
+        >
+          {{ t('common.cancel') }}
+        </button>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, watch, nextTick, onMounted } from 'vue'
+import { useI18n } from 'vue-i18n'
+
+defineProps<{
+  tempToken: string
+  userEmailMasked?: string
+}>()
+
+const emit = defineEmits<{
+  verify: [code: string]
+  cancel: []
+}>()
+
+const { t } = useI18n()
+
+const verifying = ref(false)
+const error = ref('')
+const code = ref<string[]>(['', '', '', '', '', ''])
+const inputRefs = ref<(HTMLInputElement | null)[]>([])
+
+// Watch for code changes and auto-submit when 6 digits are entered
+watch(
+  () => code.value.join(''),
+  (newCode) => {
+    if (newCode.length === 6 && !verifying.value) {
+      emit('verify', newCode)
+    }
+  }
+)
+
+defineExpose({
+  setVerifying: (value: boolean) => { verifying.value = value },
+  setError: (message: string) => {
+    error.value = message
+    code.value = ['', '', '', '', '', '']
+    // Clear input DOM values
+    inputRefs.value.forEach(input => {
+      if (input) input.value = ''
+    })
+    nextTick(() => {
+      inputRefs.value[0]?.focus()
+    })
+  }
+})
+
+const setInputRef = (el: any, index: number) => {
+  inputRefs.value[index] = el as HTMLInputElement | null
+}
+
+const handleCodeInput = (event: Event, index: number) => {
+  const input = event.target as HTMLInputElement
+  const value = input.value.replace(/[^0-9]/g, '')
+  code.value[index] = value
+
+  if (value && index < 5) {
+    nextTick(() => {
+      inputRefs.value[index + 1]?.focus()
+    })
+  }
+}
+
+const handleKeydown = (event: KeyboardEvent, index: number) => {
+  if (event.key === 'Backspace') {
+    const input = event.target as HTMLInputElement
+    // If current cell is empty and not the first, move to previous cell
+    if (!input.value && index > 0) {
+      event.preventDefault()
+      inputRefs.value[index - 1]?.focus()
+    }
+    // Otherwise, let the browser handle the backspace naturally
+    // The input event will sync code.value via handleCodeInput
+  }
+}
+
+const handlePaste = (event: ClipboardEvent) => {
+  event.preventDefault()
+  const pastedData = event.clipboardData?.getData('text') || ''
+  const digits = pastedData.replace(/[^0-9]/g, '').slice(0, 6).split('')
+
+  // Update both the ref and the input elements
+  digits.forEach((digit, index) => {
+    code.value[index] = digit
+    if (inputRefs.value[index]) {
+      inputRefs.value[index]!.value = digit
+    }
+  })
+
+  // Clear remaining inputs if pasted less than 6 digits
+  for (let i = digits.length; i < 6; i++) {
+    code.value[i] = ''
+    if (inputRefs.value[i]) {
+      inputRefs.value[i]!.value = ''
+    }
+  }
+
+  const focusIndex = Math.min(digits.length, 5)
+  nextTick(() => {
+    inputRefs.value[focusIndex]?.focus()
+  })
+}
+
+onMounted(() => {
+  nextTick(() => {
+    inputRefs.value[0]?.focus()
+  })
+})
+</script>

frontend/src/components/user/profile/ProfileTotpCard.vue

@@ -0,0 +1,154 @@
+<template>
+  <div class="card">
+    <div class="border-b border-gray-100 px-6 py-4 dark:border-dark-700">
+      <h2 class="text-lg font-medium text-gray-900 dark:text-white">
+        {{ t('profile.totp.title') }}
+      </h2>
+      <p class="mt-1 text-sm text-gray-500 dark:text-gray-400">
+        {{ t('profile.totp.description') }}
+      </p>
+    </div>
+    <div class="px-6 py-6">
+      <!-- Loading state -->
+      <div v-if="loading" class="flex items-center justify-center py-8">
+        <div class="animate-spin rounded-full h-8 w-8 border-b-2 border-primary-500"></div>
+      </div>
+
+      <!-- Feature disabled globally -->
+      <div v-else-if="status && !status.feature_enabled" class="flex items-center gap-4 py-4">
+        <div class="flex-shrink-0 rounded-full bg-gray-100 p-3 dark:bg-dark-700">
+          <svg class="h-6 w-6 text-gray-400" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="1.5">
+            <path stroke-linecap="round" stroke-linejoin="round" d="M12 9v3.75m-9.303 3.376c-.866 1.5.217 3.374 1.948 3.374h14.71c1.73 0 2.813-1.874 1.948-3.374L13.949 3.378c-.866-1.5-3.032-1.5-3.898 0L2.697 16.126zM12 15.75h.007v.008H12v-.008z" />
+          </svg>
+        </div>
+        <div>
+          <p class="font-medium text-gray-700 dark:text-gray-300">
+            {{ t('profile.totp.featureDisabled') }}
+          </p>
+          <p class="text-sm text-gray-500 dark:text-gray-400">
+            {{ t('profile.totp.featureDisabledHint') }}
+          </p>
+        </div>
+      </div>
+
+      <!-- 2FA Enabled -->
+      <div v-else-if="status?.enabled" class="flex items-center justify-between">
+        <div class="flex items-center gap-4">
+          <div class="flex-shrink-0 rounded-full bg-green-100 p-3 dark:bg-green-900/30">
+            <svg class="h-6 w-6 text-green-600 dark:text-green-400" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="1.5">
+              <path stroke-linecap="round" stroke-linejoin="round" d="M9 12.75L11.25 15 15 9.75m-3-7.036A11.959 11.959 0 013.598 6 11.99 11.99 0 003 9.749c0 5.592 3.824 10.29 9 11.623 5.176-1.332 9-6.03 9-11.622 0-1.31-.21-2.571-.598-3.751h-.152c-3.196 0-6.1-1.248-8.25-3.285z" />
+            </svg>
+          </div>
+          <div>
+            <p class="font-medium text-gray-900 dark:text-white">
+              {{ t('profile.totp.enabled') }}
+            </p>
+            <p v-if="status.enabled_at" class="text-sm text-gray-500 dark:text-gray-400">
+              {{ t('profile.totp.enabledAt') }}: {{ formatDate(status.enabled_at) }}
+            </p>
+          </div>
+        </div>
+        <button
+          type="button"
+          class="btn btn-outline-danger"
+          @click="showDisableDialog = true"
+        >
+          {{ t('profile.totp.disable') }}
+        </button>
+      </div>
+
+      <!-- 2FA Not Enabled -->
+      <div v-else class="flex items-center justify-between">
+        <div class="flex items-center gap-4">
+          <div class="flex-shrink-0 rounded-full bg-gray-100 p-3 dark:bg-dark-700">
+            <svg class="h-6 w-6 text-gray-400" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="1.5">
+              <path stroke-linecap="round" stroke-linejoin="round" d="M9 12.75L11.25 15 15 9.75m-3-7.036A11.959 11.959 0 013.598 6 11.99 11.99 0 003 9.749c0 5.592 3.824 10.29 9 11.623 5.176-1.332 9-6.03 9-11.622 0-1.31-.21-2.571-.598-3.751h-.152c-3.196 0-6.1-1.248-8.25-3.285z" />
+            </svg>
+          </div>
+          <div>
+            <p class="font-medium text-gray-700 dark:text-gray-300">
+              {{ t('profile.totp.notEnabled') }}
+            </p>
+            <p class="text-sm text-gray-500 dark:text-gray-400">
+              {{ t('profile.totp.notEnabledHint') }}
+            </p>
+          </div>
+        </div>
+        <button
+          type="button"
+          class="btn btn-primary"
+          @click="showSetupModal = true"
+        >
+          {{ t('profile.totp.enable') }}
+        </button>
+      </div>
+    </div>
+
+    <!-- Setup Modal -->
+    <TotpSetupModal
+      v-if="showSetupModal"
+      @close="showSetupModal = false"
+      @success="handleSetupSuccess"
+    />
+
+    <!-- Disable Dialog -->
+    <TotpDisableDialog
+      v-if="showDisableDialog"
+      @close="showDisableDialog = false"
+      @success="handleDisableSuccess"
+    />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, onMounted } from 'vue'
+import { useI18n } from 'vue-i18n'
+import { totpAPI } from '@/api'
+import type { TotpStatus } from '@/types'
+import TotpSetupModal from './TotpSetupModal.vue'
+import TotpDisableDialog from './TotpDisableDialog.vue'
+
+const { t } = useI18n()
+
+const loading = ref(true)
+const status = ref<TotpStatus | null>(null)
+const showSetupModal = ref(false)
+const showDisableDialog = ref(false)
+
+const loadStatus = async () => {
+  loading.value = true
+  try {
+    status.value = await totpAPI.getStatus()
+  } catch (error) {
+    console.error('Failed to load TOTP status:', error)
+  } finally {
+    loading.value = false
+  }
+}
+
+const handleSetupSuccess = () => {
+  showSetupModal.value = false
+  loadStatus()
+}
+
+const handleDisableSuccess = () => {
+  showDisableDialog.value = false
+  loadStatus()
+}
+
+const formatDate = (timestamp: number) => {
+  // Backend returns Unix timestamp in seconds, convert to milliseconds
+  const date = new Date(timestamp * 1000)
+  return date.toLocaleDateString(undefined, {
+    year: 'numeric',
+    month: 'long',
+    day: 'numeric',
+    hour: '2-digit',
+    minute: '2-digit'
+  })
+}
+
+onMounted(() => {
+  loadStatus()
+})
+</script>

frontend/src/components/user/profile/TotpDisableDialog.vue

@@ -0,0 +1,179 @@
+<template>
+  <div class="fixed inset-0 z-50 overflow-y-auto" @click.self="$emit('close')">
+    <div class="flex min-h-full items-center justify-center p-4">
+      <div class="fixed inset-0 bg-black/50 transition-opacity" @click="$emit('close')"></div>
+
+      <div class="relative w-full max-w-md transform rounded-xl bg-white p-6 shadow-xl transition-all dark:bg-dark-800">
+        <!-- Header -->
+        <div class="mb-6">
+          <div class="mx-auto flex h-12 w-12 items-center justify-center rounded-full bg-red-100 dark:bg-red-900/30">
+            <svg class="h-6 w-6 text-red-600 dark:text-red-400" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="1.5">
+              <path stroke-linecap="round" stroke-linejoin="round" d="M12 9v3.75m-9.303 3.376c-.866 1.5.217 3.374 1.948 3.374h14.71c1.73 0 2.813-1.874 1.948-3.374L13.949 3.378c-.866-1.5-3.032-1.5-3.898 0L2.697 16.126zM12 15.75h.007v.008H12v-.008z" />
+            </svg>
+          </div>
+          <h3 class="mt-4 text-center text-xl font-semibold text-gray-900 dark:text-white">
+            {{ t('profile.totp.disableTitle') }}
+          </h3>
+          <p class="mt-2 text-center text-sm text-gray-500 dark:text-gray-400">
+            {{ t('profile.totp.disableWarning') }}
+          </p>
+        </div>
+
+        <!-- Loading verification method -->
+        <div v-if="methodLoading" class="flex items-center justify-center py-8">
+          <div class="animate-spin rounded-full h-8 w-8 border-b-2 border-primary-500"></div>
+        </div>
+
+        <form v-else @submit.prevent="handleDisable" class="space-y-4">
+          <!-- Email verification -->
+          <div v-if="verificationMethod === 'email'">
+            <label class="input-label">{{ t('profile.totp.emailCode') }}</label>
+            <div class="flex gap-2">
+              <input
+                v-model="form.emailCode"
+                type="text"
+                maxlength="6"
+                inputmode="numeric"
+                class="input flex-1"
+                :placeholder="t('profile.totp.enterEmailCode')"
+              />
+              <button
+                type="button"
+                class="btn btn-secondary whitespace-nowrap"
+                :disabled="sendingCode || codeCooldown > 0"
+                @click="handleSendCode"
+              >
+                {{ codeCooldown > 0 ? `${codeCooldown}s` : (sendingCode ? t('common.sending') : t('profile.totp.sendCode')) }}
+              </button>
+            </div>
+          </div>
+
+          <!-- Password verification -->
+          <div v-else>
+            <label for="password" class="input-label">
+              {{ t('profile.currentPassword') }}
+            </label>
+            <input
+              id="password"
+              v-model="form.password"
+              type="password"
+              autocomplete="current-password"
+              class="input"
+              :placeholder="t('profile.totp.enterPassword')"
+            />
+          </div>
+
+          <!-- Error -->
+          <div v-if="error" class="rounded-lg bg-red-50 p-3 text-sm text-red-700 dark:bg-red-900/30 dark:text-red-400">
+            {{ error }}
+          </div>
+
+          <!-- Actions -->
+          <div class="flex justify-end gap-3 pt-4">
+            <button type="button" class="btn btn-secondary" @click="$emit('close')">
+              {{ t('common.cancel') }}
+            </button>
+            <button
+              type="submit"
+              class="btn btn-danger"
+              :disabled="loading || !canSubmit"
+            >
+              {{ loading ? t('common.processing') : t('profile.totp.confirmDisable') }}
+            </button>
+          </div>
+        </form>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, onMounted, computed } from 'vue'
+import { useI18n } from 'vue-i18n'
+import { useAppStore } from '@/stores/app'
+import { totpAPI } from '@/api'
+
+const emit = defineEmits<{
+  close: []
+  success: []
+}>()
+
+const { t } = useI18n()
+const appStore = useAppStore()
+
+const methodLoading = ref(true)
+const verificationMethod = ref<'email' | 'password'>('password')
+const loading = ref(false)
+const error = ref('')
+const sendingCode = ref(false)
+const codeCooldown = ref(0)
+const form = ref({
+  emailCode: '',
+  password: ''
+})
+
+const canSubmit = computed(() => {
+  if (verificationMethod.value === 'email') {
+    return form.value.emailCode.length === 6
+  }
+  return form.value.password.length > 0
+})
+
+const loadVerificationMethod = async () => {
+  methodLoading.value = true
+  try {
+    const method = await totpAPI.getVerificationMethod()
+    verificationMethod.value = method.method
+  } catch (err: any) {
+    appStore.showError(err.response?.data?.message || t('common.error'))
+    emit('close')
+  } finally {
+    methodLoading.value = false
+  }
+}
+
+const handleSendCode = async () => {
+  sendingCode.value = true
+  try {
+    await totpAPI.sendVerifyCode()
+    appStore.showSuccess(t('profile.totp.codeSent'))
+    // Start cooldown
+    codeCooldown.value = 60
+    const timer = setInterval(() => {
+      codeCooldown.value--
+      if (codeCooldown.value <= 0) {
+        clearInterval(timer)
+      }
+    }, 1000)
+  } catch (err: any) {
+    appStore.showError(err.response?.data?.message || t('profile.totp.sendCodeFailed'))
+  } finally {
+    sendingCode.value = false
+  }
+}
+
+const handleDisable = async () => {
+  if (!canSubmit.value) return
+
+  loading.value = true
+  error.value = ''
+
+  try {
+    const request = verificationMethod.value === 'email'
+      ? { email_code: form.value.emailCode }
+      : { password: form.value.password }
+
+    await totpAPI.disable(request)
+    appStore.showSuccess(t('profile.totp.disableSuccess'))
+    emit('success')
+  } catch (err: any) {
+    error.value = err.response?.data?.message || t('profile.totp.disableFailed')
+  } finally {
+    loading.value = false
+  }
+}
+
+onMounted(() => {
+  loadVerificationMethod()
+})
+</script>

frontend/src/components/user/profile/TotpSetupModal.vue

@@ -0,0 +1,400 @@
+<template>
+  <div class="fixed inset-0 z-50 overflow-y-auto" @click.self="$emit('close')">
+    <div class="flex min-h-full items-center justify-center p-4">
+      <div class="fixed inset-0 bg-black/50 transition-opacity" @click="$emit('close')"></div>
+
+      <div class="relative w-full max-w-md transform rounded-xl bg-white p-6 shadow-xl transition-all dark:bg-dark-800">
+        <!-- Header -->
+        <div class="mb-6 text-center">
+          <h3 class="text-xl font-semibold text-gray-900 dark:text-white">
+            {{ t('profile.totp.setupTitle') }}
+          </h3>
+          <p class="mt-2 text-sm text-gray-500 dark:text-gray-400">
+            {{ stepDescription }}
+          </p>
+        </div>
+
+        <!-- Step 0: Identity Verification -->
+        <div v-if="step === 0" class="space-y-6">
+          <!-- Loading verification method -->
+          <div v-if="methodLoading" class="flex items-center justify-center py-8">
+            <div class="animate-spin rounded-full h-8 w-8 border-b-2 border-primary-500"></div>
+          </div>
+
+          <template v-else>
+            <!-- Email verification -->
+            <div v-if="verificationMethod === 'email'" class="space-y-4">
+              <div>
+                <label class="input-label">{{ t('profile.totp.emailCode') }}</label>
+                <div class="flex gap-2">
+                  <input
+                    v-model="verifyForm.emailCode"
+                    type="text"
+                    maxlength="6"
+                    inputmode="numeric"
+                    class="input flex-1"
+                    :placeholder="t('profile.totp.enterEmailCode')"
+                  />
+                  <button
+                    type="button"
+                    class="btn btn-secondary whitespace-nowrap"
+                    :disabled="sendingCode || codeCooldown > 0"
+                    @click="handleSendCode"
+                  >
+                    {{ codeCooldown > 0 ? `${codeCooldown}s` : (sendingCode ? t('common.sending') : t('profile.totp.sendCode')) }}
+                  </button>
+                </div>
+              </div>
+            </div>
+
+            <!-- Password verification -->
+            <div v-else class="space-y-4">
+              <div>
+                <label class="input-label">{{ t('profile.currentPassword') }}</label>
+                <input
+                  v-model="verifyForm.password"
+                  type="password"
+                  autocomplete="current-password"
+                  class="input"
+                  :placeholder="t('profile.totp.enterPassword')"
+                />
+              </div>
+            </div>
+
+            <div v-if="verifyError" class="rounded-lg bg-red-50 p-3 text-sm text-red-700 dark:bg-red-900/30 dark:text-red-400">
+              {{ verifyError }}
+            </div>
+
+            <div class="flex justify-end gap-3 pt-4">
+              <button type="button" class="btn btn-secondary" @click="$emit('close')">
+                {{ t('common.cancel') }}
+              </button>
+              <button
+                type="button"
+                class="btn btn-primary"
+                :disabled="!canProceedFromVerify || setupLoading"
+                @click="handleVerifyAndSetup"
+              >
+                {{ setupLoading ? t('common.loading') : t('common.next') }}
+              </button>
+            </div>
+          </template>
+        </div>
+
+        <!-- Step 1: Show QR Code -->
+        <div v-if="step === 1" class="space-y-6">
+          <!-- QR Code and Secret -->
+          <template v-if="setupData">
+            <div class="flex justify-center">
+              <div class="rounded-lg border border-gray-200 p-4 bg-white dark:border-dark-600 dark:bg-white">
+                <img :src="qrCodeDataUrl" alt="QR Code" class="h-48 w-48" />
+              </div>
+            </div>
+
+            <div class="text-center">
+              <p class="text-sm text-gray-500 dark:text-gray-400 mb-2">
+                {{ t('profile.totp.manualEntry') }}
+              </p>
+              <div class="flex items-center justify-center gap-2">
+                <code class="rounded bg-gray-100 px-3 py-2 font-mono text-sm dark:bg-dark-700">
+                  {{ setupData.secret }}
+                </code>
+                <button
+                  type="button"
+                  class="rounded p-1.5 text-gray-500 hover:bg-gray-100 dark:hover:bg-dark-700"
+                  @click="copySecret"
+                >
+                  <svg class="h-5 w-5" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="1.5">
+                    <path stroke-linecap="round" stroke-linejoin="round" d="M15.666 3.888A2.25 2.25 0 0013.5 2.25h-3c-1.03 0-1.9.693-2.166 1.638m7.332 0c.055.194.084.4.084.612v0a.75.75 0 01-.75.75H9a.75.75 0 01-.75-.75v0c0-.212.03-.418.084-.612m7.332 0c.646.049 1.288.11 1.927.184 1.1.128 1.907 1.077 1.907 2.185V19.5a2.25 2.25 0 01-2.25 2.25H6.75A2.25 2.25 0 014.5 19.5V6.257c0-1.108.806-2.057 1.907-2.185a48.208 48.208 0 011.927-.184" />
+                  </svg>
+                </button>
+              </div>
+            </div>
+          </template>
+
+          <div class="flex justify-end gap-3 pt-4">
+            <button type="button" class="btn btn-secondary" @click="$emit('close')">
+              {{ t('common.cancel') }}
+            </button>
+            <button
+              type="button"
+              class="btn btn-primary"
+              :disabled="!setupData"
+              @click="step = 2"
+            >
+              {{ t('common.next') }}
+            </button>
+          </div>
+        </div>
+
+        <!-- Step 2: Verify Code -->
+        <div v-if="step === 2" class="space-y-6">
+          <form @submit.prevent="handleVerify">
+            <div class="mb-6">
+              <label class="input-label text-center block mb-3">
+                {{ t('profile.totp.enterCode') }}
+              </label>
+              <div class="flex justify-center gap-2">
+                <input
+                  v-for="(_, index) in 6"
+                  :key="index"
+                  :ref="(el) => setInputRef(el, index)"
+                  type="text"
+                  maxlength="1"
+                  inputmode="numeric"
+                  pattern="[0-9]"
+                  class="h-12 w-10 rounded-lg border border-gray-300 text-center text-lg font-semibold focus:border-primary-500 focus:ring-primary-500 dark:border-dark-600 dark:bg-dark-700"
+                  @input="handleCodeInput($event, index)"
+                  @keydown="handleKeydown($event, index)"
+                  @paste="handlePaste"
+                />
+              </div>
+            </div>
+
+            <div v-if="error" class="mb-4 rounded-lg bg-red-50 p-3 text-sm text-red-700 dark:bg-red-900/30 dark:text-red-400">
+              {{ error }}
+            </div>
+
+            <div class="flex justify-end gap-3">
+              <button type="button" class="btn btn-secondary" @click="step = 1">
+                {{ t('common.back') }}
+              </button>
+              <button
+                type="submit"
+                class="btn btn-primary"
+                :disabled="verifying || code.join('').length !== 6"
+              >
+                {{ verifying ? t('common.verifying') : t('profile.totp.verify') }}
+              </button>
+            </div>
+          </form>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, onMounted, nextTick, watch, computed } from 'vue'
+import { useI18n } from 'vue-i18n'
+import { useAppStore } from '@/stores/app'
+import { totpAPI } from '@/api'
+import type { TotpSetupResponse } from '@/types'
+import QRCode from 'qrcode'
+
+const emit = defineEmits<{
+  close: []
+  success: []
+}>()
+
+const { t } = useI18n()
+const appStore = useAppStore()
+
+// Step: 0 = verify identity, 1 = QR code, 2 = verify TOTP code
+const step = ref(0)
+const methodLoading = ref(true)
+const verificationMethod = ref<'email' | 'password'>('password')
+const verifyForm = ref({ emailCode: '', password: '' })
+const verifyError = ref('')
+const sendingCode = ref(false)
+const codeCooldown = ref(0)
+
+const setupLoading = ref(false)
+const setupData = ref<TotpSetupResponse | null>(null)
+const verifying = ref(false)
+const error = ref('')
+const code = ref<string[]>(['', '', '', '', '', ''])
+const inputRefs = ref<(HTMLInputElement | null)[]>([])
+const qrCodeDataUrl = ref('')
+
+const stepDescription = computed(() => {
+  switch (step.value) {
+    case 0:
+      return verificationMethod.value === 'email'
+        ? t('profile.totp.verifyEmailFirst')
+        : t('profile.totp.verifyPasswordFirst')
+    case 1:
+      return t('profile.totp.setupStep1')
+    case 2:
+      return t('profile.totp.setupStep2')
+    default:
+      return ''
+  }
+})
+
+const canProceedFromVerify = computed(() => {
+  if (verificationMethod.value === 'email') {
+    return verifyForm.value.emailCode.length === 6
+  }
+  return verifyForm.value.password.length > 0
+})
+
+// Generate QR code as base64 when setupData changes
+watch(
+  () => setupData.value?.qr_code_url,
+  async (url) => {
+    if (url) {
+      try {
+        qrCodeDataUrl.value = await QRCode.toDataURL(url, {
+          width: 200,
+          margin: 2,
+          color: {
+            dark: '#000000',
+            light: '#ffffff'
+          }
+        })
+      } catch (err) {
+        console.error('Failed to generate QR code:', err)
+      }
+    }
+  },
+  { immediate: true }
+)
+
+const setInputRef = (el: any, index: number) => {
+  inputRefs.value[index] = el as HTMLInputElement | null
+}
+
+const handleCodeInput = (event: Event, index: number) => {
+  const input = event.target as HTMLInputElement
+  const value = input.value.replace(/[^0-9]/g, '')
+  code.value[index] = value
+
+  if (value && index < 5) {
+    nextTick(() => {
+      inputRefs.value[index + 1]?.focus()
+    })
+  }
+}
+
+const handleKeydown = (event: KeyboardEvent, index: number) => {
+  if (event.key === 'Backspace') {
+    const input = event.target as HTMLInputElement
+    // If current cell is empty and not the first, move to previous cell
+    if (!input.value && index > 0) {
+      event.preventDefault()
+      inputRefs.value[index - 1]?.focus()
+    }
+    // Otherwise, let the browser handle the backspace naturally
+    // The input event will sync code.value via handleCodeInput
+  }
+}
+
+const handlePaste = (event: ClipboardEvent) => {
+  event.preventDefault()
+  const pastedData = event.clipboardData?.getData('text') || ''
+  const digits = pastedData.replace(/[^0-9]/g, '').slice(0, 6).split('')
+
+  // Update both the ref and the input elements
+  digits.forEach((digit, index) => {
+    code.value[index] = digit
+    if (inputRefs.value[index]) {
+      inputRefs.value[index]!.value = digit
+    }
+  })
+
+  // Clear remaining inputs if pasted less than 6 digits
+  for (let i = digits.length; i < 6; i++) {
+    code.value[i] = ''
+    if (inputRefs.value[i]) {
+      inputRefs.value[i]!.value = ''
+    }
+  }
+
+  const focusIndex = Math.min(digits.length, 5)
+  nextTick(() => {
+    inputRefs.value[focusIndex]?.focus()
+  })
+}
+
+const copySecret = async () => {
+  if (setupData.value) {
+    try {
+      await navigator.clipboard.writeText(setupData.value.secret)
+      appStore.showSuccess(t('common.copied'))
+    } catch {
+      appStore.showError(t('common.copyFailed'))
+    }
+  }
+}
+
+const loadVerificationMethod = async () => {
+  methodLoading.value = true
+  try {
+    const method = await totpAPI.getVerificationMethod()
+    verificationMethod.value = method.method
+  } catch (err: any) {
+    appStore.showError(err.response?.data?.message || t('common.error'))
+    emit('close')
+  } finally {
+    methodLoading.value = false
+  }
+}
+
+const handleSendCode = async () => {
+  sendingCode.value = true
+  try {
+    await totpAPI.sendVerifyCode()
+    appStore.showSuccess(t('profile.totp.codeSent'))
+    // Start cooldown
+    codeCooldown.value = 60
+    const timer = setInterval(() => {
+      codeCooldown.value--
+      if (codeCooldown.value <= 0) {
+        clearInterval(timer)
+      }
+    }, 1000)
+  } catch (err: any) {
+    appStore.showError(err.response?.data?.message || t('profile.totp.sendCodeFailed'))
+  } finally {
+    sendingCode.value = false
+  }
+}
+
+const handleVerifyAndSetup = async () => {
+  setupLoading.value = true
+  verifyError.value = ''
+
+  try {
+    const request = verificationMethod.value === 'email'
+      ? { email_code: verifyForm.value.emailCode }
+      : { password: verifyForm.value.password }
+
+    setupData.value = await totpAPI.initiateSetup(request)
+    step.value = 1
+  } catch (err: any) {
+    verifyError.value = err.response?.data?.message || t('profile.totp.setupFailed')
+  } finally {
+    setupLoading.value = false
+  }
+}
+
+const handleVerify = async () => {
+  const totpCode = code.value.join('')
+  if (totpCode.length !== 6 || !setupData.value) return
+
+  verifying.value = true
+  error.value = ''
+
+  try {
+    await totpAPI.enable({
+      totp_code: totpCode,
+      setup_token: setupData.value.setup_token
+    })
+    appStore.showSuccess(t('profile.totp.enableSuccess'))
+    emit('success')
+  } catch (err: any) {
+    error.value = err.response?.data?.message || t('profile.totp.verifyFailed')
+    code.value = ['', '', '', '', '', '']
+    nextTick(() => {
+      inputRefs.value[0]?.focus()
+    })
+  } finally {
+    verifying.value = false
+  }
+}
+
+onMounted(() => {
+  loadVerificationMethod()
+})
+</script>

frontend/src/i18n/locales/en.ts

@@ -146,7 +146,10 @@ export default {
     balance: 'Balance',
     available: 'Available',
     copiedToClipboard: 'Copied to clipboard',
+    copied: 'Copied',
     copyFailed: 'Failed to copy',
+    verifying: 'Verifying...',
+    processing: 'Processing...',
     contactSupport: 'Contact Support',
     add: 'Add',
     invalidEmail: 'Please enter a valid email address',
@@ -583,7 +586,46 @@ export default {
     passwordsNotMatch: 'New passwords do not match',
     passwordTooShort: 'Password must be at least 8 characters long',
     passwordChangeSuccess: 'Password changed successfully',
-    passwordChangeFailed: 'Failed to change password'
+    passwordChangeFailed: 'Failed to change password',
+    // TOTP 2FA
+    totp: {
+      title: 'Two-Factor Authentication (2FA)',
+      description: 'Enhance account security with Google Authenticator or similar apps',
+      enabled: 'Enabled',
+      enabledAt: 'Enabled at',
+      notEnabled: 'Not Enabled',
+      notEnabledHint: 'Enable two-factor authentication to enhance account security',
+      enable: 'Enable',
+      disable: 'Disable',
+      featureDisabled: 'Feature Unavailable',
+      featureDisabledHint: 'Two-factor authentication has not been enabled by the administrator',
+      setupTitle: 'Set Up Two-Factor Authentication',
+      setupStep1: 'Scan the QR code below with your authenticator app',
+      setupStep2: 'Enter the 6-digit code from your app',
+      manualEntry: "Can't scan? Enter the key manually:",
+      enterCode: 'Enter 6-digit code',
+      verify: 'Verify',
+      setupFailed: 'Failed to get setup information',
+      verifyFailed: 'Invalid code, please try again',
+      enableSuccess: 'Two-factor authentication enabled',
+      disableTitle: 'Disable Two-Factor Authentication',
+      disableWarning: 'After disabling, you will no longer need a verification code to log in. This may reduce your account security.',
+      enterPassword: 'Enter your current password to confirm',
+      confirmDisable: 'Confirm Disable',
+      disableSuccess: 'Two-factor authentication disabled',
+      disableFailed: 'Failed to disable, please check your password',
+      loginTitle: 'Two-Factor Authentication',
+      loginHint: 'Enter the 6-digit code from your authenticator app',
+      loginFailed: 'Verification failed, please try again',
+      // New translations for email verification
+      verifyEmailFirst: 'Please verify your email first',
+      verifyPasswordFirst: 'Please verify your identity first',
+      emailCode: 'Email Verification Code',
+      enterEmailCode: 'Enter 6-digit code',
+      sendCode: 'Send Code',
+      codeSent: 'Verification code sent to your email',
+      sendCodeFailed: 'Failed to send verification code'
+    }
   },
 
   // Empty States
@@ -2774,7 +2816,11 @@ export default {
         promoCode: 'Promo Code',
         promoCodeHint: 'Allow users to use promo codes during registration',
         passwordReset: 'Password Reset',
-        passwordResetHint: 'Allow users to reset their password via email'
+        passwordResetHint: 'Allow users to reset their password via email',
+        totp: 'Two-Factor Authentication (2FA)',
+        totpHint: 'Allow users to use authenticator apps like Google Authenticator',
+        totpKeyNotConfigured:
+          'Please configure TOTP_ENCRYPTION_KEY in environment variables first. Generate a key with: openssl rand -hex 32'
       },
       turnstile: {
         title: 'Cloudflare Turnstile',

frontend/src/i18n/locales/zh.ts

@@ -143,7 +143,10 @@ export default {
     balance: '余额',
     available: '可用',
     copiedToClipboard: '已复制到剪贴板',
+    copied: '已复制',
     copyFailed: '复制失败',
+    verifying: '验证中...',
+    processing: '处理中...',
     contactSupport: '联系客服',
     add: '添加',
     invalidEmail: '请输入有效的邮箱地址',
@@ -579,7 +582,46 @@ export default {
     passwordsNotMatch: '两次输入的密码不一致',
     passwordTooShort: '密码至少需要 8 个字符',
     passwordChangeSuccess: '密码修改成功',
-    passwordChangeFailed: '密码修改失败'
+    passwordChangeFailed: '密码修改失败',
+    // TOTP 2FA
+    totp: {
+      title: '双因素认证 (2FA)',
+      description: '使用 Google Authenticator 等应用增强账户安全',
+      enabled: '已启用',
+      enabledAt: '启用时间',
+      notEnabled: '未启用',
+      notEnabledHint: '启用双因素认证可以增强账户安全性',
+      enable: '启用',
+      disable: '禁用',
+      featureDisabled: '功能未开放',
+      featureDisabledHint: '管理员尚未开放双因素认证功能',
+      setupTitle: '设置双因素认证',
+      setupStep1: '使用认证器应用扫描下方二维码',
+      setupStep2: '输入应用显示的 6 位验证码',
+      manualEntry: '无法扫码？手动输入密钥：',
+      enterCode: '输入 6 位验证码',
+      verify: '验证',
+      setupFailed: '获取设置信息失败',
+      verifyFailed: '验证码错误，请重试',
+      enableSuccess: '双因素认证已启用',
+      disableTitle: '禁用双因素认证',
+      disableWarning: '禁用后，登录时将不再需要验证码。这可能会降低您的账户安全性。',
+      enterPassword: '请输入当前密码确认',
+      confirmDisable: '确认禁用',
+      disableSuccess: '双因素认证已禁用',
+      disableFailed: '禁用失败，请检查密码是否正确',
+      loginTitle: '双因素认证',
+      loginHint: '请输入您认证器应用显示的 6 位验证码',
+      loginFailed: '验证失败，请重试',
+      // New translations for email verification
+      verifyEmailFirst: '请先验证您的邮箱',
+      verifyPasswordFirst: '请先验证您的身份',
+      emailCode: '邮箱验证码',
+      enterEmailCode: '请输入 6 位验证码',
+      sendCode: '发送验证码',
+      codeSent: '验证码已发送到您的邮箱',
+      sendCodeFailed: '发送验证码失败'
+    }
   },
 
   // Empty States
@@ -2927,7 +2969,11 @@ export default {
         promoCode: '优惠码',
         promoCodeHint: '允许用户在注册时使用优惠码',
         passwordReset: '忘记密码',
-        passwordResetHint: '允许用户通过邮箱重置密码'
+        passwordResetHint: '允许用户通过邮箱重置密码',
+        totp: '双因素认证 (2FA)',
+        totpHint: '允许用户使用 Google Authenticator 等应用进行二次验证',
+        totpKeyNotConfigured:
+          '请先在环境变量中配置 TOTP_ENCRYPTION_KEY。使用命令 openssl rand -hex 32 生成密钥。'
       },
       turnstile: {
         title: 'Cloudflare Turnstile',

frontend/src/stores/auth.ts

@@ -5,8 +5,8 @@
 
 import { defineStore } from 'pinia'
 import { ref, computed, readonly } from 'vue'
-import { authAPI } from '@/api'
+import { authAPI, isTotp2FARequired, type LoginResponse } from '@/api'
-import type { User, LoginRequest, RegisterRequest } from '@/types'
+import type { User, LoginRequest, RegisterRequest, AuthResponse } from '@/types'
 
 const AUTH_TOKEN_KEY = 'auth_token'
 const AUTH_USER_KEY = 'auth_user'
@@ -91,14 +91,53 @@ export const useAuthStore = defineStore('auth', () => {
 
   /**
    * User login
-   * @param credentials - Login credentials (username and password)
+   * @param credentials - Login credentials (email and password)
-   * @returns Promise resolving to the authenticated user
+   * @returns Promise resolving to the login response (may require 2FA)
    * @throws Error if login fails
    */
-  async function login(credentials: LoginRequest): Promise<User> {
+  async function login(credentials: LoginRequest): Promise<LoginResponse> {
     try {
       const response = await authAPI.login(credentials)
 
+      // If 2FA is required, return the response without setting auth state
+      if (isTotp2FARequired(response)) {
+        return response
+      }
+
+      // Set auth state from the response
+      setAuthFromResponse(response)
+
+      return response
+    } catch (error) {
+      // Clear any partial state on error
+      clearAuth()
+      throw error
+    }
+  }
+
+  /**
+   * Complete login with 2FA code
+   * @param tempToken - Temporary token from initial login
+   * @param totpCode - 6-digit TOTP code
+   * @returns Promise resolving to the authenticated user
+   * @throws Error if 2FA verification fails
+   */
+  async function login2FA(tempToken: string, totpCode: string): Promise<User> {
+    try {
+      const response = await authAPI.login2FA({ temp_token: tempToken, totp_code: totpCode })
+      setAuthFromResponse(response)
+      return user.value!
+    } catch (error) {
+      clearAuth()
+      throw error
+    }
+  }
+
+  /**
+   * Set auth state from an AuthResponse
+   * Internal helper function
+   */
+  function setAuthFromResponse(response: AuthResponse): void {
     // Store token and user
     token.value = response.access_token
 
@@ -115,13 +154,6 @@ export const useAuthStore = defineStore('auth', () => {
 
     // Start auto-refresh interval
     startAutoRefresh()
-
-      return userData
-    } catch (error) {
-      // Clear any partial state on error
-      clearAuth()
-      throw error
-    }
   }
 
   /**
@@ -253,6 +285,7 @@ export const useAuthStore = defineStore('auth', () => {
 
     // Actions
     login,
+    login2FA,
     register,
     setToken,
     logout,

frontend/src/types/index.ts

@@ -1108,3 +1108,52 @@ export interface UpdatePromoCodeRequest {
   expires_at?: number | null
   notes?: string
 }
+
+// ==================== TOTP (2FA) Types ====================
+
+export interface TotpStatus {
+  enabled: boolean
+  enabled_at: number | null  // Unix timestamp in seconds
+  feature_enabled: boolean
+}
+
+export interface TotpSetupRequest {
+  email_code?: string
+  password?: string
+}
+
+export interface TotpSetupResponse {
+  secret: string
+  qr_code_url: string
+  setup_token: string
+  countdown: number
+}
+
+export interface TotpEnableRequest {
+  totp_code: string
+  setup_token: string
+}
+
+export interface TotpEnableResponse {
+  success: boolean
+}
+
+export interface TotpDisableRequest {
+  email_code?: string
+  password?: string
+}
+
+export interface TotpVerificationMethod {
+  method: 'email' | 'password'
+}
+
+export interface TotpLoginResponse {
+  requires_2fa: boolean
+  temp_token?: string
+  user_email_masked?: string
+}
+
+export interface TotpLogin2FARequest {
+  temp_token: string
+  totp_code: string
+}

frontend/src/views/admin/SettingsView.vue

@@ -354,6 +354,31 @@
               </div>
               <Toggle v-model="form.password_reset_enabled" />
             </div>
+
+            <!-- TOTP 2FA -->
+            <div
+              class="flex items-center justify-between border-t border-gray-100 pt-4 dark:border-dark-700"
+            >
+              <div>
+                <label class="font-medium text-gray-900 dark:text-white">{{
+                  t('admin.settings.registration.totp')
+                }}</label>
+                <p class="text-sm text-gray-500 dark:text-gray-400">
+                  {{ t('admin.settings.registration.totpHint') }}
+                </p>
+                <!-- Warning when encryption key not configured -->
+                <p
+                  v-if="!form.totp_encryption_key_configured"
+                  class="mt-2 text-sm text-amber-600 dark:text-amber-400"
+                >
+                  {{ t('admin.settings.registration.totpKeyNotConfigured') }}
+                </p>
+              </div>
+              <Toggle
+                v-model="form.totp_enabled"
+                :disabled="!form.totp_encryption_key_configured"
+              />
+            </div>
           </div>
         </div>
 
@@ -1046,6 +1071,8 @@ const form = reactive<SettingsForm>({
   email_verify_enabled: false,
   promo_code_enabled: true,
   password_reset_enabled: false,
+  totp_enabled: false,
+  totp_encryption_key_configured: false,
   default_balance: 0,
   default_concurrency: 1,
   site_name: 'Sub2API',
@@ -1170,6 +1197,7 @@ async function saveSettings() {
       email_verify_enabled: form.email_verify_enabled,
       promo_code_enabled: form.promo_code_enabled,
       password_reset_enabled: form.password_reset_enabled,
+      totp_enabled: form.totp_enabled,
       default_balance: form.default_balance,
       default_concurrency: form.default_concurrency,
       site_name: form.site_name,

frontend/src/views/auth/LoginView.vue

@@ -163,6 +163,16 @@
       </p>
     </template>
   </AuthLayout>
+
+  <!-- 2FA Modal -->
+  <TotpLoginModal
+    v-if="show2FAModal"
+    ref="totpModalRef"
+    :temp-token="totpTempToken"
+    :user-email-masked="totpUserEmailMasked"
+    @verify="handle2FAVerify"
+    @cancel="handle2FACancel"
+  />
 </template>
 
 <script setup lang="ts">
@@ -171,10 +181,12 @@ import { useRouter } from 'vue-router'
 import { useI18n } from 'vue-i18n'
 import { AuthLayout } from '@/components/layout'
 import LinuxDoOAuthSection from '@/components/auth/LinuxDoOAuthSection.vue'
+import TotpLoginModal from '@/components/auth/TotpLoginModal.vue'
 import Icon from '@/components/icons/Icon.vue'
 import TurnstileWidget from '@/components/TurnstileWidget.vue'
 import { useAuthStore, useAppStore } from '@/stores'
-import { getPublicSettings } from '@/api/auth'
+import { getPublicSettings, isTotp2FARequired } from '@/api/auth'
+import type { TotpLoginResponse } from '@/types'
 
 const { t } = useI18n()
 
@@ -200,6 +212,12 @@ const passwordResetEnabled = ref<boolean>(false)
 const turnstileRef = ref<InstanceType<typeof TurnstileWidget> | null>(null)
 const turnstileToken = ref<string>('')
 
+// 2FA state
+const show2FAModal = ref<boolean>(false)
+const totpTempToken = ref<string>('')
+const totpUserEmailMasked = ref<string>('')
+const totpModalRef = ref<InstanceType<typeof TotpLoginModal> | null>(null)
+
 const formData = reactive({
   email: '',
   password: ''
@@ -302,12 +320,22 @@ async function handleLogin(): Promise<void> {
 
   try {
     // Call auth store login
-    await authStore.login({
+    const response = await authStore.login({
       email: formData.email,
       password: formData.password,
       turnstile_token: turnstileEnabled.value ? turnstileToken.value : undefined
     })
 
+    // Check if 2FA is required
+    if (isTotp2FARequired(response)) {
+      const totpResponse = response as TotpLoginResponse
+      totpTempToken.value = totpResponse.temp_token || ''
+      totpUserEmailMasked.value = totpResponse.user_email_masked || ''
+      show2FAModal.value = true
+      isLoading.value = false
+      return
+    }
+
     // Show success toast
     appStore.showSuccess(t('auth.loginSuccess'))
 
@@ -338,6 +366,40 @@ async function handleLogin(): Promise<void> {
     isLoading.value = false
   }
 }
+
+// ==================== 2FA Handlers ====================
+
+async function handle2FAVerify(code: string): Promise<void> {
+  if (totpModalRef.value) {
+    totpModalRef.value.setVerifying(true)
+  }
+
+  try {
+    await authStore.login2FA(totpTempToken.value, code)
+
+    // Close modal and show success
+    show2FAModal.value = false
+    appStore.showSuccess(t('auth.loginSuccess'))
+
+    // Redirect to dashboard or intended route
+    const redirectTo = (router.currentRoute.value.query.redirect as string) || '/dashboard'
+    await router.push(redirectTo)
+  } catch (error: unknown) {
+    const err = error as { message?: string; response?: { data?: { message?: string } } }
+    const message = err.response?.data?.message || err.message || t('profile.totp.loginFailed')
+
+    if (totpModalRef.value) {
+      totpModalRef.value.setError(message)
+      totpModalRef.value.setVerifying(false)
+    }
+  }
+}
+
+function handle2FACancel(): void {
+  show2FAModal.value = false
+  totpTempToken.value = ''
+  totpUserEmailMasked.value = ''
+}
 </script>
 
 <style scoped>

frontend/src/views/user/ProfileView.vue

@@ -15,6 +15,7 @@
       </div>
       <ProfileEditForm :initial-username="user?.username || ''" />
       <ProfilePasswordForm />
+      <ProfileTotpCard />
     </div>
   </AppLayout>
 </template>
@@ -27,6 +28,7 @@ import StatCard from '@/components/common/StatCard.vue'
 import ProfileInfoCard from '@/components/user/profile/ProfileInfoCard.vue'
 import ProfileEditForm from '@/components/user/profile/ProfileEditForm.vue'
 import ProfilePasswordForm from '@/components/user/profile/ProfilePasswordForm.vue'
+import ProfileTotpCard from '@/components/user/profile/ProfileTotpCard.vue'
 import { Icon } from '@/components/icons'
 
 const { t } = useI18n(); const authStore = useAuthStore(); const user = computed(() => authStore.user)