feat: add unrecognized device email alerts (#168)

.env.example

@@ -48,10 +48,10 @@ ACCOUNT_LOCK_DURATION=30
 ENCRYPTION_KEY=your-32-byte-secret-key-here
 
 LOGIN_RATE_LIMIT_MAX=5
-LOGIN_RATE_LIMIT_WINDOW=900000 //ms
+LOGIN_RATE_LIMIT_WINDOW=900000
 
 REGISTER_RATE_LIMIT_MAX=3
-REGISTER_RATE_LIMIT_WINDOW=3600000 //ms
+REGISTER_RATE_LIMIT_WINDOW=3600000
 
 FORGOT_RATE_LIMIT_MAX=3
-FORGOT_RATE_LIMIT_WINDOW=3600000 //ms
+FORGOT_RATE_LIMIT_WINDOW=3600000

Dockerfile

@@ -25,7 +25,7 @@ FROM alpine:latest
 WORKDIR /app
 
 # Install runtime dependencies (ca-certificates for HTTPS, tzdata for timezones)
-RUN apk add --no-cache ca-certificates tzdata
+RUN apk add --no-cache ca-certificates tzdata wget
 
 # Create a non-root user
 RUN addgroup -S authgroup && adduser -S authuser -G authgroup

cmd/server/main.go

@@ -52,7 +52,7 @@ func main() {
 	}
 	// Backfill existing tokens using their own ID as the family ID
 	if err := db.Exec("UPDATE refresh_tokens SET family_id = id WHERE family_id IS NULL").Error; err != nil {
-		log.Fatal("Failed to backfill family_id for existing refresh tokens:", err)
+		log.Printf("Warning: Failed to backfill family_id for existing refresh tokens (expected on fresh DB): %v", err)
 	}
 
 	// Auto-migrate database models
@@ -61,6 +61,7 @@ func main() {
 		&models.VerificationToken{},
 		&models.PasswordResetToken{},
 		&models.AuditLog{},
+		&models.DeviceFingerprint{},
 		// OAuth 2.0 Provider models
 		&models.OAuthClient{},
 		&models.AuthorizationCode{},

docker-compose.yml

@@ -12,6 +12,7 @@ services:
       - PORT=8080
       - DATABASE_URL=host=postgres user=postgres password=postgres dbname=auth_db port=5432 sslmode=disable
       - REDIS_URL=redis://auth-redis:6379
+      - SMTP_HOST=auth-mailpit
       - JWT_ACCESS_SECRET=${JWT_ACCESS_SECRET:-secret}
       - JWT_REFRESH_SECRET=${JWT_REFRESH_SECRET:-refresh}
     depends_on:
@@ -22,6 +23,13 @@ services:
     env_file:
       - .env      
 
+    healthcheck:
+      test: ["CMD", "wget", "--spider", "-q", "http://localhost:8080/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 15s
+
   postgres:
     image: postgres:15-alpine
     container_name: auth-postgres
@@ -48,6 +56,16 @@ services:
     networks:
       - auth-network
 
+  mailpit:
+    image: axllent/mailpit
+    container_name: auth-mailpit
+    restart: unless-stopped
+    ports:
+      - "8025:8025"
+      - "1025:1025"
+    networks:
+      - auth-network
+
 networks:
   auth-network:
     driver: bridge

internal/handler/auth_handler.go

@@ -160,6 +160,29 @@ func (h *AuthHandler) ResetPassword(c *gin.Context) {
 	c.JSON(http.StatusOK, utils.SuccessResponse("Password has been reset successfully. You can now login with your new password.", nil))
 }
 
+// LockAccount handles account locking via email link
+// @Summary Lock account
+// @Tags auth
+// @Accept json
+// @Produce json
+// @Param token query string true "Lock token"
+// @Success 200 {object} utils.Response
+// @Router /api/auth/lock-account [get]
+func (h *AuthHandler) LockAccount(c *gin.Context) {
+	token := c.Query("token")
+	if token == "" {
+		c.JSON(http.StatusBadRequest, utils.ValidationErrorResponse("Token is required"))
+		return
+	}
+
+	if err := h.authService.LockAccount(token); err != nil {
+		c.JSON(http.StatusBadRequest, utils.ErrorResponse("Failed to lock account", err))
+		return
+	}
+
+	c.JSON(http.StatusOK, utils.SuccessResponse("Your account has been locked to prevent unauthorized access. Please reset your password to regain access.", nil))
+}
+
 // UpdateProfile handles profile updates
 // @Summary Update user profile
 // @Tags auth

internal/models/device_fingerprint.go

@@ -0,0 +1,29 @@
+package models
+
+import (
+	"time"
+
+	"github.com/google/uuid"
+	"gorm.io/gorm"
+)
+
+type DeviceFingerprint struct {
+	ID              string    `gorm:"type:uuid;primary_key" json:"id"`
+	UserID          string    `gorm:"type:uuid;not null;index" json:"userId"`
+	FingerprintHash string    `gorm:"not null;index" json:"fingerprintHash"`
+	UserAgent       string    `gorm:"size:500" json:"userAgent"`
+	IPAddress       string    `gorm:"size:45" json:"ipAddress"`
+	LastSeenAt      time.Time `json:"lastSeenAt"`
+	CreatedAt       time.Time `json:"createdAt"`
+}
+
+func (d *DeviceFingerprint) BeforeCreate(tx *gorm.DB) error {
+	if d.ID == "" {
+		d.ID = uuid.New().String()
+	}
+	return nil
+}
+
+func (DeviceFingerprint) TableName() string {
+	return "device_fingerprints"
+}

internal/repository/device_repository.go

@@ -0,0 +1,37 @@
+package repository
+
+import (
+	"errors"
+	"time"
+
+	"github.com/roshankumar0036singh/auth-server/internal/models"
+	"gorm.io/gorm"
+)
+
+type DeviceRepository struct {
+	db *gorm.DB
+}
+
+func NewDeviceRepository(db *gorm.DB) *DeviceRepository {
+	return &DeviceRepository{db: db}
+}
+
+func (r *DeviceRepository) FindByFingerprint(userID, hash string) (*models.DeviceFingerprint, error) {
+	var device models.DeviceFingerprint
+	err := r.db.Where("user_id = ? AND fingerprint_hash = ?", userID, hash).First(&device).Error
+	if err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return nil, nil // Return nil if not found, instead of error
+		}
+		return nil, err
+	}
+	return &device, nil
+}
+
+func (r *DeviceRepository) Create(device *models.DeviceFingerprint) error {
+	return r.db.Create(device).Error
+}
+
+func (r *DeviceRepository) UpdateLastSeen(id string, lastSeen time.Time) error {
+	return r.db.Model(&models.DeviceFingerprint{}).Where("id = ?", id).Update("last_seen_at", lastSeen).Error
+}

internal/routes/routes.go

@@ -29,6 +29,7 @@ func SetupRoutes(router *gin.Engine, db *gorm.DB, redisClient *redis.Client, cfg
 	oauthTokenRepo := repository.NewOAuthTokenRepository(db)
 	userConsentRepo := repository.NewUserConsentRepository(db)
 	oauthProviderConfigRepo := repository.NewOAuthProviderConfigRepository(db)
+	deviceRepo := repository.NewDeviceRepository(db)
 
 	// Initialize services
 	tokenService := service.NewTokenService(cfg)
@@ -53,6 +54,7 @@ func SetupRoutes(router *gin.Engine, db *gorm.DB, redisClient *redis.Client, cfg
 		emailService,
 		auditService,
 		mfaService,
+		deviceRepo,
 		cfg,
 	)
 
@@ -151,6 +153,7 @@ func SetupRoutes(router *gin.Engine, db *gorm.DB, redisClient *redis.Client, cfg
 			auth.POST("/resend-verification", authHandler.ResendVerification)
 			auth.POST("/forgot-password", authHandler.ForgotPassword)
 			auth.POST("/reset-password", authHandler.ResetPassword)
+			auth.GET("/lock-account", authHandler.LockAccount)
 
 			// WebAuthn Login
 			auth.POST("/webauthn/login/begin", webAuthnHandler.BeginLogin)

internal/service/auth_service.go

@@ -47,6 +47,7 @@ type AuthService struct {
 	emailService      EmailSender
 	auditService      *AuditService
 	mfaService        *MFAService
+	deviceRepo        *repository.DeviceRepository
 	config            *config.Config
 }
 
@@ -60,6 +61,7 @@ func NewAuthService(
 	emailService EmailSender,
 	auditService *AuditService,
 	mfaService *MFAService,
+	deviceRepo *repository.DeviceRepository,
 	cfg *config.Config,
 ) *AuthService {
 	return &AuthService{
@@ -72,6 +74,7 @@ func NewAuthService(
 		emailService:      emailService,
 		auditService:      auditService,
 		mfaService:        mfaService,
+		deviceRepo:        deviceRepo,
 		config:            cfg,
 	}
 }
@@ -299,6 +302,28 @@ func (s *AuthService) DeleteAccount(userID string) error {
 	return nil
 }
 
+// LockAccount locks the user account indefinitely using a valid lock token
+func (s *AuthService) LockAccount(tokenString string) error {
+	userID, err := s.tokenService.ValidateLockToken(tokenString)
+	if err != nil {
+		return errors.New("invalid or expired lock token")
+	}
+
+	// Lock the account (100 years)
+	lockedUntil := time.Now().Add(100 * 365 * 24 * time.Hour)
+	if err := s.userRepo.LockUser(userID, lockedUntil); err != nil {
+		return errors.New("failed to lock account")
+	}
+
+	// Revoke all existing sessions for security
+	s.tokenRepo.RevokeAllUserTokens(userID)
+
+	// Audit Log
+	s.auditService.LogEvent(&userID, "ACCOUNT_LOCKED_BY_USER", "USER", userID, "", "", map[string]interface{}{"reason": "unrecognized_device_alert"})
+
+	return nil
+}
+
 // EnableMFA generates a secret and returns it with QR code URL
 func (s *AuthService) EnableMFA(userID string) (*dto.MFAEnableResponse, error) {
 	user, err := s.userRepo.FindByID(userID)
@@ -616,6 +641,9 @@ func (s *AuthService) ProcessPostLogin(ctx context.Context, user *models.User, i
 		log.Printf("Failed to update last login for user %s: %v", user.ID, err)
 	}
 
+	// Check device fingerprint
+	s.handleDeviceFingerprint(user, ipAddress, userAgent)
+
 	response, err := s.CreateLoginResponse(user, ipAddress, userAgent)
 	if err != nil {
 		return nil, err
@@ -629,6 +657,44 @@ func (s *AuthService) ProcessPostLogin(ctx context.Context, user *models.User, i
 	return response, nil
 }
 
+func (s *AuthService) handleDeviceFingerprint(user *models.User, ipAddress, userAgent string) {
+	fingerprintHash := utils.GenerateDeviceFingerprint(userAgent, ipAddress)
+	device, err := s.deviceRepo.FindByFingerprint(user.ID, fingerprintHash)
+	if err != nil {
+		log.Printf("Error checking device fingerprint: %v", err)
+	}
+
+	if device == nil {
+		// Unrecognized device
+		newDevice := &models.DeviceFingerprint{
+			UserID:          user.ID,
+			FingerprintHash: fingerprintHash,
+			UserAgent:       userAgent,
+			IPAddress:       ipAddress,
+			LastSeenAt:      time.Now(),
+		}
+		if err := s.deviceRepo.Create(newDevice); err != nil {
+			log.Printf("Failed to save device fingerprint: %v", err)
+		}
+
+		// Generate lock token and send alert email asynchronously
+		go func(u *models.User, ip, agent string) {
+			lockToken, err := s.tokenService.GenerateLockToken(u.ID)
+			if err != nil {
+				log.Printf("Failed to generate lock token for unrecognized login alert: %v", err)
+				return
+			}
+			err = s.emailService.SendUnrecognizedLoginAlert(u.Email, ip, agent, lockToken, s.config.App.URL)
+			if err != nil {
+				log.Printf("Failed to send unrecognized login alert to %s: %v", u.Email, err)
+			}
+		}(user, ipAddress, userAgent)
+	} else {
+		// Update last seen
+		s.deviceRepo.UpdateLastSeen(device.ID, time.Now())
+	}
+}
+
 // LoginWithOAuth handles login or registration via OAuth provider
 func (s *AuthService) LoginWithOAuth(email, oauthID, firstName, lastName, provider, ipAddress, userAgent string) (*dto.LoginResponse, error) {
 	user, err := s.userRepo.FindByEmail(email)

internal/service/email_service.go

@@ -10,9 +10,12 @@ import (
 	"github.com/roshankumar0036singh/auth-server/internal/config"
 )
 
+const appName = "Auth Server"
+
 type EmailSender interface {
 	SendVerificationEmail(email, token, appURL string) error
 	SendPasswordResetEmail(email, token, appURL string) error
+	SendUnrecognizedLoginAlert(email, ip, userAgent, lockToken, appURL string) error
 }
 
 type EmailService struct {
@@ -55,7 +58,10 @@ func (s *EmailService) SendEmail(to []string, subject string, templateName strin
 	message += "\r\n" + body.String()
 
 	// Authenticate
-	auth := smtp.PlainAuth("", s.config.SMTPUser, s.config.SMTPPassword, s.config.SMTPHost)
+	var auth smtp.Auth
+	if s.config.SMTPUser != "" && s.config.SMTPPassword != "" {
+		auth = smtp.PlainAuth("", s.config.SMTPUser, s.config.SMTPPassword, s.config.SMTPHost)
+	}
 
 	// Send email
 	addr := fmt.Sprintf("%s:%d", s.config.SMTPHost, s.config.SMTPPort)
@@ -76,7 +82,7 @@ func (s *EmailService) SendVerificationEmail(email, token, appURL string) error
 		AppName   string
 	}{
 		VerifyURL: verifyURL,
-		AppName:   "Auth Server",
+		AppName:   appName,
 	}
 
 	return s.SendEmail([]string{email}, "Verify your email", "verify_email.html", data)
@@ -92,8 +98,27 @@ func (s *EmailService) SendPasswordResetEmail(email, token, appURL string) error
 		AppName  string
 	}{
 		ResetURL: resetURL,
-		AppName:  "Auth Server",
+		AppName:  appName,
 	}
 
 	return s.SendEmail([]string{email}, "Reset your password", "reset_password.html", data)
+}
+
+// SendUnrecognizedLoginAlert sends an alert for an unfamiliar device login
+func (s *EmailService) SendUnrecognizedLoginAlert(email, ip, userAgent, lockToken, appURL string) error {
+	lockURL := fmt.Sprintf("%s/api/auth/lock-account?token=%s", appURL, lockToken)
+
+	data := struct {
+		IPAddress string
+		UserAgent string
+		LockURL   string
+		AppName   string
+	}{
+		IPAddress: ip,
+		UserAgent: userAgent,
+		LockURL:   lockURL,
+		AppName:   appName,
+	}
+
+	return s.SendEmail([]string{email}, "Security Alert: Unrecognized Login", "unrecognized_login.html", data)
 }