chore(email): Email Authentication and User Management Improvements

[LucienShui]

Summary

This PR introduces a comprehensive overhaul of the email-based authentication system, replacing the traditional token-based signup flow with a modern OTP (One-Time Password) verification system. It also significantly improves the user invitation and email change workflows with better security, personalization, and user experience.

Key Changes

1. OTP-Based Authentication System

• New OTP Service (otp.service.ts): Centralized service for generating and verifying OTPs with Redis-based storage

  • 6-digit numeric codes with 5-minute expiration
  • Rate limiting: max 3 OTP requests per 15-minute window
  • Attempt limiting: max 5 verification attempts per code
  • Magic link support as an alternative to manual code entry

• New Authentication Endpoints:

  • POST /api/v1/auth/send-otp - Send OTP for login (existing users only)
  • POST /api/v1/auth/send-signup-otp - Send OTP for new user registration
  • POST /api/v1/auth/verify-otp - Verify OTP code
  • POST /api/v1/auth/verify-magic - Verify magic link token
  • POST /api/v1/auth/accept-invite - Accept invitation via magic link

• Automatic Account Creation: Users can now sign up using only their email through OTP verification

  • Auto-generates username from email prefix
  • Handles username conflicts automatically
  • Creates user namespace automatically
  • Generates secure random password for OTP-registered accounts

2. Enhanced Invitation Flow

• Streamlined Process: Invitations now automatically create accounts for new users

  • Single-click acceptance via magic link
  • 7-day token expiration (extended from 1 hour)
  • Auto-registration on acceptance for new users

• Personalized Invitations:

  • Email subjects now include sender name and namespace name
  • Differentiated messaging for new vs. existing users
  • Uses recipient's language preference for existing users

• Security Improvements:

  • Validates that logged-in user matches invited user (inviteConfirm)
  • New error message: INVITE_USER_MISMATCH for authorization conflicts

3. Email Change Verification

• Dual Notification System:

  • Verification email sent to new address with OTP code
  • Notification email sent to old address about the change

• Templates:

  • emailVerification: Sends OTP to new email address
  • emailChangeNotification: Notifies old email address of change
  • Includes security warnings if change was unauthorized

4. Improved Email Templates

• OTP Email Template: Clean, modern design with:

  • Large, centered verification code
  • Alternative magic link button
  • Clear expiration notice (5 minutes)

• Invitation Email Updates:

  • Dynamic subject line: {senderUsername} invites you to join the space {namespaceName}
  • Personalized body text based on user status (new vs. existing)
  • Uses recipient's username in greeting when available

5. API Improvements

• New DTOs:

  • SendEmailOtpDto: Email validation for OTP requests
  • VerifyEmailOtpDto: Email + 6-digit code validation
  • SendEmailOtpResponseDto: Response with exists and sent flags

• Removed Deprecated Endpoints:

  • POST /api/v1/sign-up (replaced by OTP flow)
  • POST /api/v1/sign-up/confirm (replaced by OTP verification)

6. Cache Service Integration

• OTP codes and rate limit data stored in Redis via CacheService
• Automatic TTL (Time-To-Live) management for expiration
• One-time use tokens (deleted after verification)

7. Internationalization

• New translation keys for:
  • Email change notifications
  • OTP verification emails
  • Invitation emails with sender/namespace details
  • Error messages (inviteUserMismatch)

Technical Details

Migration Path

• Backward Compatibility: Existing password-based login remains unchanged
• Social Login: WeChat and Google OAuth flows unaffected
• Existing Users: Can now use OTP for passwordless login

Security Enhancements

1. Rate limiting prevents abuse (3 requests per 15 minutes)
2. Attempt limiting prevents brute force (5 attempts per code)
3. Short expiration times (5 minutes for OTP)
4. One-time use tokens (consumed after verification)
5. Magic links bound to specific email + code pairs
6. User validation on invitation acceptance

Database Changes

• No schema migrations required
• Uses existing Redis cache infrastructure
• Maintains existing user/namespace relationships

Testing

• E2E tests updated to reflect new authentication flow
• Removed obsolete /sign-up/confirm tests
• Password reset flow tests maintained

Version Bump

• Version updated from 0.1.4 to 0.1.10

Breaking Changes

• POST /api/v1/sign-up endpoint removed
• POST /api/v1/sign-up/confirm endpoint removed
• /invite/confirm endpoint now requires user validation (checks logged-in user matches invited user)

Migration Guide for Clients

1. Replace signup flow with OTP verification:

   • Call /api/v1/auth/send-signup-otp instead of /api/v1/sign-up
   • Call /api/v1/auth/verify-otp instead of /api/v1/sign-up/confirm

2. Invitation acceptance:

   • Existing users: Continue using /invite/confirm (ensure user is logged in as invited user)
   • New users: Use /api/v1/auth/accept-invite with magic link token

3. Login flow for existing users:

   • Option 1: Continue using password-based /login
   • Option 2: Use new OTP flow via /api/v1/auth/send-otp + /api/v1/auth/verify-otp