feat: add MFA backup recovery codes

internal/dto/auth_dto.go

@@ -85,6 +85,7 @@ type SessionResponse struct {
 type MFAEnableResponse struct {
 	Secret    string `json:"secret"`
 	QRCodeURL string `json:"qrCodeUrl"`
+	BackupCodes []string `json:"backupCodes,omitempty"`
 }
 
 // MFAVerifyRequest represents the request to verify/enable MFA
@@ -106,6 +107,7 @@ type MFADisableRequest struct {
 type MFALoginRequest struct {
 	MFAToken string `json:"mfaToken" binding:"required"`
 	Code     string `json:"code" binding:"required,len=6"`
+	BackupCode string `json:"backupCode,omitempty"`
 }
 
 // LoginResponse represents the login response (updated for MFA)

internal/handler/auth_handler.go

@@ -904,6 +904,7 @@ func (h *AuthHandler) VerifyMFA(c *gin.Context) {
 		c.JSON(http.StatusBadRequest, utils.ErrorResponse("MFA verification failed", err))
 		return
 	}
+
 
 	c.JSON(http.StatusOK, utils.SuccessResponse("MFA enabled successfully", nil))
 }

internal/models/backup_code.go

@@ -0,0 +1,28 @@
+package models
+
+import (
+	"time"
+
+	"github.com/google/uuid"
+	"gorm.io/gorm"
+)
+
+type BackupCode struct {
+	ID        string         `gorm:"type:uuid;primaryKey"`
+	UserID    string         `gorm:"type:uuid;not null;index"`
+	CodeHash  string         `gorm:"not null"`
+	Used      bool           `gorm:"default:false"`
+	CreatedAt time.Time
+	DeletedAt gorm.DeletedAt `gorm:"index"`
+}
+
+func (b *BackupCode) BeforeCreate(tx *gorm.DB) error {
+	if b.ID == "" {
+		b.ID = uuid.New().String()
+	}
+	return nil
+}
+
+func (BackupCode) TableName() string {
+	return "backup_codes"
+}

internal/repository/backup_code_repository.go

@@ -0,0 +1,38 @@
+package repository
+
+import (
+	"errors"
+
+	"github.com/roshankumar0036singh/auth-server/internal/models"
+	"gorm.io/gorm"
+)
+
+var ErrBackupCodeNotFound = errors.New("backup code not found")
+
+type BackupCodeRepository struct {
+	db *gorm.DB
+}
+
+func NewBackupCodeRepository(db *gorm.DB) *BackupCodeRepository {
+	return &BackupCodeRepository{db: db}
+}
+
+func (r *BackupCodeRepository) Create(code *models.BackupCode) error {
+	return r.db.Create(code).Error
+}
+
+func (r *BackupCodeRepository) FindByUserID(userID string) ([]models.BackupCode, error) {
+	var codes []models.BackupCode
+
+	err := r.db.
+		Where("user_id = ? AND used = ?", userID, false).
+		Find(&codes).Error
+
+	return codes, err
+}
+
+func (r *BackupCodeRepository) MarkUsed(id string) error {
+	return r.db.Model(&models.BackupCode{}).
+		Where("id = ?", id).
+		Update("used", true).Error
+}

internal/routes/routes.go

@@ -54,6 +54,7 @@ func SetupRoutes(router *gin.Engine, db *gorm.DB, redisClient *redis.Client, cfg
 		auditService,
 		mfaService,
 		cfg,
+		backupCodeRepo    *repository.BackupCodeRepository
 	)
 
 	// OAuth Provider service

internal/service/auth_service.go

@@ -48,6 +48,7 @@
 	auditService      *AuditService
 	mfaService        *MFAService
 	config            *config.Config
+	backupCodeRepo    *repository.BackupCodeRepository
 }
 
 func NewAuthService(
@@ -61,6 +62,7 @@
 	auditService *AuditService,
 	mfaService *MFAService,
 	cfg *config.Config,
+	backupCodeRepo *repository.BackupCodeRepository,
 ) *AuthService {
 	return &AuthService{
 		userRepo:          userRepo,
@@ -73,6 +75,7 @@
 		auditService:      auditService,
 		mfaService:        mfaService,
 		config:            cfg,
+		backupCodeRepo: backupCodeRepo,
 	}
 }
 func (s *AuthService) getRefreshTokenExpiry() time.Duration {
@@ -346,6 +349,27 @@
 	if !s.mfaService.ValidateMFA(user.MFASecret, code) {
 		return ErrInvalidMFACode
 	}
+	for i := 0; i < 10; i++ {
+	code := s.tokenService.GenerateRandomString(8)
+
+	hash, err := bcrypt.GenerateFromPassword(
+		[]byte(code),
+		bcrypt.DefaultCost,
+	)
+	if err != nil {
+		return err
+	}
+
+	backup := &models.BackupCode{
+		UserID:   userID,
+		CodeHash: string(hash),
+		Used:     false,
+	}
+
+	if err := s.backupCodeRepo.Create(backup); err != nil {
+		return err
+	}
+}
 
 	// Enable MFA
 	if err := s.userRepo.Update(userID, map[string]interface{}{
@@ -399,7 +423,7 @@
 // short-lived MFA-pending token issued by the password step (Login), so the
 // password cannot be bypassed, and rate-limits code attempts to prevent
 // brute-forcing the 6-digit TOTP.
 func (s *AuthService) VerifyLoginMFA(mfaToken, code, ipAddress, userAgent string) (*dto.LoginResponse, error) {
 	ctx := context.Background()
 
 	userID, err := s.tokenService.ValidateMFAToken(mfaToken)
@@ -425,13 +449,33 @@
 		return nil, errors.New("MFA not enabled for this user")
 	}
 
-	if !s.mfaService.ValidateMFA(user.MFASecret, code) {
-		s.cacheService.IncrementMFAAttempts(ctx, userID)
-		if err := s.auditService.LogEvent(&user.ID, "MFA_LOGIN_FAILED", "USER", user.ID, ipAddress, userAgent, nil); err != nil {
-			log.Printf("failed to write MFA_LOGIN_FAILED audit log for user %s: %v", user.ID, err)
+	valid := s.mfaService.ValidateMFA(user.MFASecret, code)
+
+if !valid {
+	codes, err := s.backupCodeRepo.FindByUserID(userID)
+
+	if err == nil {
+		for _, bc := range codes {
+			if bcrypt.CompareHashAndPassword(
+				[]byte(bc.CodeHash),
+				[]byte(code),
+			) == nil {
+
+				valid = true
+				_ = s.backupCodeRepo.MarkUsed(bc.ID)
+				break
+			}
 		}
-		return nil, ErrInvalidMFACode
 	}
+}
+
+if !valid {
+	s.cacheService.IncrementMFAAttempts(ctx, userID)
+	if err := s.auditService.LogEvent(&user.ID, "MFA_LOGIN_FAILED", "USER", user.ID, ipAddress, userAgent, nil); err != nil {
+		log.Printf("failed to write MFA_LOGIN_FAILED audit log for user %s: %v", user.ID, err)
+	}
+	return nil, ErrInvalidMFACode
+}
 
 	s.cacheService.ResetMFAAttempts(ctx, userID)
 

internal/testutils/setup.go

@@ -48,7 +48,11 @@ func SetupIntegrationTest(t *testing.T) (*service.AuthService, *gorm.DB, *minire
 		&models.PasswordResetToken{},
 		&models.AuditLog{},
 		&models.OAuthAccessToken{},
+		&models.BackupCode{}, 
 	)
+
+
+
         assert.NoError(t, err)
         assert.NoError(t, db.Exec("DELETE FROM oauth_access_tokens").Error)
 
@@ -117,6 +121,7 @@ func SetupIntegrationTest(t *testing.T) (*service.AuthService, *gorm.DB, *minire
 	verificationRepo := repository.NewVerificationRepository(db)
 	passwordResetRepo := repository.NewPasswordResetRepository(db)
 	auditRepo := repository.NewAuditRepository(db)
+	backupCodeRepo := repository.NewBackupCodeRepository(db)
 
 	// 4. Services
 	cfg := &config.Config{
@@ -141,6 +146,7 @@ func SetupIntegrationTest(t *testing.T) (*service.AuthService, *gorm.DB, *minire
 		auditService,
 		mfaService,
 		cfg,
+		backupCodeRepo,
 	)
 
 	return authService, db, mr