v4.0.0

🚀 Release v4.0.0

Major Release - This version includes breaking changes.

🎯 Overview

Version 4.0.0 represents a significant evolution of the authentication module, introducing refresh token support, enhanced security, and a more flexible architecture. This release focuses on production-readiness and security best practices.

---

✨ New Features

🔄 Refresh Token Support

The headline feature of v4.0.0 is full refresh token support with a secure, production-ready implementation.

Key Features:

• One-time use tokens - Refresh tokens are automatically deleted after use, preventing replay attacks
• SHA-256 hashing - Tokens are stored as hashes for additional security
• Configurable expiration - Set custom lifetimes for refresh tokens
• Token rotation - New refresh token issued with each refresh operation
• Revocation support - Revoke specific tokens or all tokens for a user (logout all devices)

Implementation:

// Enable by providing a refresh token repository
AuthModule.forRootAsync({
  refreshTokenRepository: RefreshTokenRepositoryService,
  useFactory: (config: ConfigService) => ({
    jwt: {
      accessToken: createSymmetricTokenConfig({ /* ... */ }),
      refreshToken: {
        expiresIn: 7 * 24 * 60 * 60, // 7 days in seconds
        tokenLength: 32, // Optional, defaults to 32 bytes
      },
    },
  }),
  // ...
})

New Service Methods:

// AuthJwtService
await authJwt.generateTokens(userId);        // Generate access + refresh
await authJwt.refreshTokens(refreshToken);   // Rotate tokens
await authJwt.revokeToken(tokenId);          // Revoke single token
await authJwt.revokeAllTokens(userId);       // Logout all devices

🏗️ Refactored Service Architecture

Services have been reorganized for better separation of concerns:

New Service: AuthJwtService

• Central service for all JWT operations
• Handles both access and refresh tokens
• Optional refresh token support (gracefully degrades if not configured)

Enhanced: CredentialsAuthService

• Now handles all email/password operations
• Added verifyEmail() method
• Added validateUser() method for token refresh flows
• Improved error messages

Enhanced: GoogleAuthService

• Added unlinkGoogleAccount() method
• Added isGoogleLinked() method
• Better error handling for OAuth flows

🔐 Enhanced Security

Improved Password Handling:

• Extracted HashService for reusable hashing logic
• Both passwords and refresh tokens use Argon2
• Timing-safe comparison for refresh token validation
• Prevention of password reuse in changePassword()

JWT Configuration Requirements:

• expiresIn is now required in signOptions to prevent immortal tokens
• Support for both symmetric (HS256) and asymmetric (RS256) keys
• Explicit key type configuration

---

💥 Breaking Changes

1. JWT Configuration Changes

v4.0.0:

jwt: {
  accessToken: createSymmetricTokenConfig({
    secret: 'my-secret',
    signOptions: {
      expiresIn: '15m', // Now required
      algorithm: 'HS256',
    },
  }),
  refreshToken: { // Optional
    expiresIn: 7 * 24 * 60 * 60,
  },
}

Migration:

• Wrap existing JWT config under accessToken key
• Ensure expiresIn is specified in signOptions
• Add algorithm to signOptions
• Optionally add refreshToken configuration

2. Module Configuration Structure

Before (v3.x):

AuthModule.forRootAsync({
  useFactory: (config: ConfigService) => ({
    jwt: { /* ... */ },
    credentials: { /* ... */ },
    google: { /* ... */ },
  }),
  userRepository: UserRepositoryService,
})

After (v4.0.0):

AuthModule.forRootAsync({
  useFactory: (config: ConfigService) => ({
    jwt: { /* ... */ },
    credentials: { /* ... */ },
    google: { /* ... */ },
  }),
  userRepository: UserRepositoryService,
  refreshTokenRepository: RefreshTokenRepositoryService, // New
  enabledCapabilities: ['credentials', 'google'], // New
})

Migration:

• Add enabledCapabilities array to specify which auth methods to enable
• Optionally add refreshTokenRepository for refresh token support

---

Full Changelog: v3.0.1...v4.0.0