Auth Module Documentation

Overview

The auth module provides authentication, user registration, login, email verification, and JWT token management for the multi-tenant NestJS application. It is designed to be secure, extensible, and fully tenant-aware.

Main Components

• Controllers

  • AuthController: Exposes endpoints for signup, login, getting current user, email verification, and token refresh.

• Services

  • AuthService: Handles core authentication logic, including user creation, login, token issuance, and user lookup.
  • EmailVerificationService: Manages email verification tokens and status.
  • CurrentUserService: Provides utility methods to fetch or process the current user from the request context.

• Entities

  • AuthEntity: Mongoose schema for user authentication data (email, password, verified status, tenantId).
  • EmailVerifyEntity: Schema for email verification tokens.

• DTOs

  • SignupDto: Validates signup requests (enforces strong password, matching confirmation, etc).
  • LoginDto: Validates login requests.
  • RefreshTokenDto: Validates refresh token requests.

• Events & Handlers

  • NewTenantCreatedEventHandler: Handles tenant creation, triggers admin user signup and role assignment.
  • GetEmailVerificationLinkQueryHandler: Handles queries for generating email verification links.

• Strategy

  • JwtStrategy: Passport strategy for validating JWT tokens.

• Decorators

  • @CurrentUser(): Custom parameter decorator to extract the current user object from the request. Use in controller methods to access the authenticated user.

Authentication Flow

1. Signup

   • Validates input via SignupDto.
   • Creates a new user in the database.
   • Publishes a NewUserCreatedEvent for further processing.

2. Login

   • Validates credentials.
   • Issues JWT tokens via GetTokenSet.

3. Email Verification

   • Generates a verification token and link.
   • Verifies token and updates user status.

4. Token Refresh

   • Validates refresh token.
   • Issues new access tokens.

5. Multi-Tenancy

   • All entities and queries are tenant-aware (see tenantId usage).
   • Tenant admin creation and role assignment are handled via events.

Security

• Uses JWT for authentication.
• Guards and decorators enforce authentication on endpoints.
• Passwords are hashed using bcrypt.

Extensibility

• Event-driven architecture for user and tenant lifecycle.
• Modular design for easy extension and maintenance.

File-Level Code Comments

All files in the auth module have been updated with clear code comments explaining:

• The purpose of each class and method
• The flow of authentication, registration, and verification
• The role of DTOs, entities, and event handlers

For further details, refer to the code comments in each file.

Installation

npm install @nestdevx/auth
# or
yarn add @nestdevx/auth
# or
pnpm add @nestdevx/auth

CurrentUser Decorator & Service

@CurrentUser() Decorator

Extracts the current user object from the request and injects it into your controller method parameters.

Usage Example:

import { Controller, Get } from '@nestjs/common';
import { CurrentUser } from '@app/auth';

@Protected()
@Controller('profile')
export class ProfileController {
  @Get()
  getProfile(@CurrentUser() user) {
    return user;
  }
}

CurrentUserService

Provides utility methods to fetch or process the current user from the request context. Import and inject this service where you need advanced user context logic.

@Injectable()
export class ProfileService {
  constructor(private readonly currentUser: CurrentUserService,
  private readonly db: SomeDbservice,
    
  ) {}

  async getProfileInformation() {
    return await this.db.profile.findByUserId(this.currentUser.sub);
  }
}

Its up to you to decide how to use.

How to Use AuthModule

Import the AuthModule into your feature module. If using the dynamic register() method, do:

import { Module } from '@nestjs/common';
import { AuthModule } from '@app/auth';

@Module({
  imports: [AuthModule.register()],
})
export class MyFeatureModule {}

You can now use all exported services, controllers, and decorators from the auth module in your feature module.