alpha

Release Notes - alpha

🎉 Major Architecture Redesign

We're excited to announce a complete redesign of the NestJS Auth Module! This release introduces a modern, modular architecture that provides better separation of concerns, improved security, and greater flexibility.

⚠️ BREAKING CHANGES

This is a major breaking release. The authentication system has been completely restructured from a monolithic module to a capability-based modular architecture.

Migration Required

• Old approach: Single AuthModule with all features bundled
• New approach: Explicit configuration via AuthModule.forRootAsync() with capability selection

You must now:

1. Explicitly configure and import the auth capabilities you need (JWT, Credentials, Google OAuth)
2. Provide required configuration objects for each capability
3. Implement and provide user repository providers

✨ What's New

Modular Architecture

The authentication system is now split into three independent, composable modules:

• 🔐 JWT Authentication Module - Token generation, validation, guards, and decorators
• 👤 Credentials Authentication - Registration, login, and password management
• 🔑 Google OAuth Module - Third-party authentication with Passport integration

Standardized Interfaces

New shared contracts provide consistency across the entire authentication flow:

• Authentication responses and token structures
• JWT payload definitions
• User data interfaces (with separation of safe vs. sensitive fields)
• Operation contracts for login, registration, OAuth callbacks, token refresh, and password changes
• Extensible configuration interfaces for each auth strategy
• Repository interfaces to decouple persistence layer

Enhanced Security

• Argon2 Password Hashing - Industry-standard secure password storage
• Improved Token Handling - Clearer error semantics for expired and invalid tokens
• Better Access Control - Enhanced role-based guards and decorators
• Reduced Exposure Risk - Explicit separation of sensitive user data

Better Developer Experience

• Clearer API Surface - Narrowed public exports to prevent accidental coupling
• Explicit Error Handling - Better error messages for invalid credentials, OAuth issues, and token problems
• Decoupled Components - Each module can be used independently or combined as needed
• Type Safety - Comprehensive TypeScript interfaces for all auth operations

Request-Level Improvements

Centralized request handling in the JWT module includes:

• Public route decorators
• Current user injection
• Role-based access control guards
• Standardized JWT payload validation

📋 Full Changelog

Added

• JWT authentication module with guards and token utilities
• Credentials authentication with secure Argon2 password hashing
• Google OAuth integration with strategy and services
• Shared authentication and configuration interfaces
• Dependency injection tokens for clear capability separation
• User and repository interface contracts
• Reusable decorators for public routes and role-based access

Changed

• Complete architectural redesign from monolithic to modular approach
• Centralized request-level concerns in auth-jwt module
• Improved error handling across all auth flows
• Updated documentation to reflect new architecture
• Narrowed public API surface to reduce coupling

Removed

• Legacy monolithic AuthService
• Tightly coupled auth logic
• Direct export of internal injection tokens
• Old DTOs and service implementations
• Password policy configuration from core (moved to validation layer)

🚀 Getting Started

import { AuthModule } from '@nahnah/nestjs-auth-module';

@Module({
  imports: [
    AuthModule.forRootAsync({
      imports: [ConfigModule],
      inject: [ConfigService],
      useFactory: (config: ConfigService) => ({
        jwt: {
          secret: config.get('JWT_SECRET'),
          expiresIn: '15m',
        },
        credentials: {
          enabled: true,
        },
        googleOauth: {
          clientID: config.get('GOOGLE_CLIENT_ID'),
          clientSecret: config.get('GOOGLE_CLIENT_SECRET'),
          callbackURL: config.get('GOOGLE_CALLBACK_URL'),
        },
      }),
    }),
  ],
  providers: [
    {
      provide: USER_REPOSITORY,
      useClass: YourUserRepository,
    },
  ],
})
export class AppModule {}

📝 Migration Guide

See our Migration Guide for detailed instructions on upgrading from v1.x to alpha.

🔮 What's Next

We have several improvements planned for upcoming releases:

• Enhanced refresh token management
• Email verification flows
• Two-factor authentication support
• Additional OAuth providers
• Session management utilities

📚 Documentation

For complete documentation, visit our README.

---

Questions or issues? Please open an issue on GitHub or reach out to the maintainers.