Implement OTP/2FA with NestJS and Sinch: A Developer's Guide - code-examples -

Two-factor authentication (2FA) adds a critical layer of security beyond traditional username and password logins. By requiring a second verification step – often a time-based one-time password (TOTP) sent via SMS – you significantly reduce the risk of unauthorized account access.

This guide provides a step-by-step walkthrough for implementing a robust SMS-based OTP and 2FA system in your NestJS application using the Sinch SMS API for message delivery and Prisma for database interactions. We will build a secure authentication flow including user registration, login, phone number verification, and enabling/disabling 2FA.

Project Overview and Goals

What We'll Build:

  • A NestJS backend application with user authentication (signup/login).
  • SMS OTP functionality for phone number verification using Sinch.
  • The ability for users to enable or disable 2FA on their accounts.
  • An enhanced login flow that requires an SMS OTP if 2FA is enabled.
  • Secure storage and handling of user data and OTPs using Prisma and PostgreSQL.

Problem Solved:

This implementation addresses the need for enhanced application security by adding a second authentication factor, mitigating risks associated with compromised passwords. It provides a reliable way to verify user phone numbers before enabling sensitive features like 2FA.

Technologies Used:

  • NestJS: A progressive Node.js framework for building efficient, reliable, and scalable server-side applications using TypeScript. Its modular architecture is well-suited for this project.
  • Sinch: A cloud communications platform providing APIs for SMS, voice, and verification. We'll use its SMS API to send OTPs.
  • Prisma: A modern database toolkit (ORM) for Node.js and TypeScript, simplifying database access, migrations, and type safety.
  • PostgreSQL: A powerful, open-source object-relational database system.
  • TypeScript: Adds static typing to JavaScript, improving code quality and maintainability.
  • JWT (JSON Web Tokens): For managing stateless authentication sessions after login.
  • bcrypt: For securely hashing user passwords.
  • class-validator / class-transformer: For robust request validation and transformation.
  • moment: For date/time manipulation (OTP expiry).

System Architecture:

+-------------+       +-----------------+       +-----------------+       +-----------+
|   Client    | ----> | NestJS API      | ----> |  Prisma Client  | ----> | PostgreSQL|
| (Web/Mobile)|       | (Controllers,   |       | (ORM)           |       | Database  |
+-------------+       |  Services, Guards)|     +-----------------+       +-----------+
                      +-----------------+
                             |  ^
                             |  | (Send SMS OTP, Handle Callbacks)
                             v  |
                      +-----------------+
                      |   Sinch SMS API |
                      +-----------------+
  1. Client: Initiates requests (signup, login, verify OTP, etc.).
  2. NestJS API: Handles incoming requests, validates data, interacts with services, manages authentication logic (JWT, Guards), and calls external APIs (Sinch).
  3. Sinch Service (within NestJS): Encapsulates logic for interacting with the Sinch SMS API to send OTPs.
  4. Prisma Client: Provides a type-safe interface for database operations (reading/writing User and Otp records).
  5. PostgreSQL Database: Persists user data, hashed passwords, 2FA status, and OTP records.

Prerequisites:

  • Node.js (LTS version recommended) and npm/yarn installed.
  • PostgreSQL server installed and running.
  • A Sinch account with SMS API credentials.
  • Basic understanding of TypeScript, REST APIs, and async/await.
  • NestJS CLI installed globally: npm install -g @nestjs/cli

Expected Outcome:

By the end of this guide, you will have a fully functional NestJS backend with secure user authentication, phone verification via Sinch SMS OTPs, and optional 2FA for login.

1. Setting up the NestJS Project

Let's scaffold a new NestJS project and configure the essential components.

1.1 Create NestJS Project

Open your terminal and run:

bash
nest new sinch-otp-nestjs-app
cd sinch-otp-nestjs-app

This creates a new project with a standard structure.

1.2 Initial Cleanup

For a cleaner start, delete the default app.controller.ts, app.controller.spec.ts, and app.service.ts from the src directory. Remove their references from src/app.module.ts.

src/app.module.ts (Initial Cleanup):

typescript
// src/app.module.ts
import { Module } from '@nestjs/common';

@Module({
  imports: [],
  controllers: [], // Remove AppController
  providers: [],   // Remove AppService
})
export class AppModule {}

1.3 Set Global API Prefix

Define a global prefix (e.g., api/v1) for all your API routes.

src/main.ts:

typescript
// src/main.ts
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { ValidationPipe, Logger } from '@nestjs/common'; // Import ValidationPipe and Logger

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  const logger = new Logger('Bootstrap'); // Create a logger instance

  // Set global prefix
  app.setGlobalPrefix('api/v1');

  // Enable global validation pipe (using class-validator DTOs)
  app.useGlobalPipes(new ValidationPipe({ whitelist: true, transform: true }));

  const port = process.env.APP_PORT || 3000; // Use environment variable or default
  await app.listen(port);
  logger.log(`Application is running on: ${await app.getUrl()}`);
}
bootstrap();

1.4 Environment Variables Setup

We need a secure way to manage configuration like database URLs and API keys.

Install the necessary package:

bash
npm install @nestjs/config

Configure it in AppModule.

src/app.module.ts:

typescript
// src/app.module.ts
import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config'; // Import ConfigModule

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true, // Make ConfigModule available globally
      envFilePath: '.env', // Specify the env file
    }),
    // Other modules will be added here
  ],
  controllers: [],
  providers: [],
})
export class AppModule {}

Create a .env file in the project root:

.env:

bash
# PostgreSQL Database
DATABASE_URL=postgresql://YOUR_DB_USER:YOUR_DB_PASSWORD@localhost:5432/sinch_otp_demo?schema=public

# JWT Configuration
JWT_SECRET=YOUR_STRONG_JWT_SECRET # Change this in production!
JWT_EXPIRATION_TIME=2d # Example: 2 days

# Sinch API Credentials (Get these from your Sinch Dashboard)
SINCH_SERVICE_PLAN_ID=YOUR_SINCH_SERVICE_PLAN_ID
SINCH_API_TOKEN=YOUR_SINCH_API_TOKEN
SINCH_PHONE_NUMBER=+YOUR_SINCH_VIRTUAL_NUMBER # Optional: If you specify a sender ID/number

# Application Settings
APP_PORT=3000 # Optional: Define app port
  • DATABASE_URL: Replace placeholders with your actual PostgreSQL username, password, host (if not localhost), and desired database name (sinch_otp_demo).
  • JWT_SECRET: Generate a strong, random secret for signing JWTs.
  • JWT_EXPIRATION_TIME: Define how long JWTs should be valid.
  • Sinch Credentials: You'll obtain these from your Sinch account dashboard.
  • SINCH_PHONE_NUMBER: Optional virtual number or sender ID. Crucially, check the official Sinch documentation for sender ID requirements in your target countries, as rules (including whether this is optional or allowed) vary significantly by country and plan type.

1.5 Database Setup with Prisma

Install Prisma CLI and Client:

bash
npm install -D prisma
npm install @prisma/client

Initialize Prisma:

bash
npx prisma init --datasource-provider postgresql

This command:

  • Creates a prisma directory with a schema.prisma file.
  • Creates the .env file (if it doesn't exist) and adds DATABASE_URL.
  • Updates your .gitignore.

Ensure your prisma/schema.prisma file reflects the .env configuration:

prisma/schema.prisma:

sql
// This is your Prisma schema file,
// learn more about it in the docs: https://pris.ly/d/prisma-schema

generator client {
  provider = prisma-client-js
}

datasource db {
  provider = postgresql
  url      = env(""DATABASE_URL"") // Reads from .env
}

// Models will be defined below

Define the User and Otp models:

prisma/schema.prisma:

sql
// ... (generator and datasource definitions above)

model User {
  id               String    @id @default(uuid())
  email            String    @unique
  phone            String?   @unique // Optional initially, required for 2FA
  password         String
  firstName        String
  lastName         String
  isPhoneVerified  Boolean   @default(false)
  twoFactorEnabled Boolean   @default(false)
  createdAt        DateTime  @default(now())
  updatedAt        DateTime  @updatedAt

  otps Otp[] // Relation to Otp model
}

model Otp {
  id        String     @id @default(uuid())
  code      String
  expiresAt DateTime   @db.Timestamp(6) // Using Timestamp with precision
  useCase   OtpUseCase
  userId    String
  createdAt DateTime   @default(now())
  updatedAt DateTime   @updatedAt

  user User @relation(fields: [userId], references: [id], onDelete: Cascade) // Relation field

  @@index([userId, useCase]) // Index for faster lookups
}

enum OtpUseCase {
  PHONE_VERIFICATION // For verifying the phone number itself
  TWO_FACTOR_AUTH    // For verifying login when 2FA is enabled
}
  • User: Stores standard user info, plus flags for phone verification (isPhoneVerified) and 2FA status (twoFactorEnabled). The phone is initially optional.
  • Otp: Stores the OTP code, its expiry time, the use case (why it was generated), and links back to the User. onDelete: Cascade ensures OTPs are deleted if the user is deleted.
  • OtpUseCase: An enum to distinguish between OTPs for initial phone verification and those for 2FA login.

Generate and apply the initial migration:

bash
npx prisma migrate dev --name init-user-otp-schema

This command:

  1. Creates SQL migration files in prisma/migrations.
  2. Applies the migration to your database, creating the User and Otp tables.
  3. Generates the Prisma Client tailored to your schema (@prisma/client).

Create a Prisma service module for database interactions:

bash
nest generate module prisma
nest generate service prisma --no-spec # Skip spec file for this example

Implement the PrismaService:

src/prisma/prisma.service.ts:

typescript
// src/prisma/prisma.service.ts
import { Injectable, OnModuleInit, INestApplication } from '@nestjs/common';
import { PrismaClient } from '@prisma/client';

@Injectable()
export class PrismaService extends PrismaClient implements OnModuleInit {
  async onModuleInit() {
    // Connect to the database when the module is initialized
    await this.$connect();
  }

  async enableShutdownHooks(app: INestApplication) {
    // Ensure Prisma disconnects gracefully on application shutdown
    process.on('beforeExit', async () => {
      await app.close();
    });
  }
}

Make the service available within its module and globally:

src/prisma/prisma.module.ts:

typescript
// src/prisma/prisma.module.ts
import { Module, Global } from '@nestjs/common';
import { PrismaService } from './prisma.service';

@Global() // Make PrismaService available globally
@Module({
  providers: [PrismaService],
  exports: [PrismaService], // Export PrismaService so other modules can use it
})
export class PrismaModule {}

Import PrismaModule into AppModule:

src/app.module.ts:

typescript
// src/app.module.ts
import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { PrismaModule } from './prisma/prisma.module'; // Import PrismaModule
// Other imports will be added here

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
      envFilePath: '.env',
    }),
    PrismaModule, // Add PrismaModule here
    // Other modules
  ],
  controllers: [],
  providers: [],
})
export class AppModule {}
  • Logging: NestJS has a built-in logger (Logger from @nestjs/common). We will use this throughout the services.
  • Exception Filter: NestJS has a base exception filter. We'll rely on this and standard HttpException types.

2. Implementing Core User Authentication

Let's build the signup and basic login functionality (without 2FA initially).

2.1 Install Dependencies

bash
npm install @nestjs/jwt passport passport-jwt bcrypt class-validator class-transformer moment
npm install -D @types/passport-jwt @types/bcrypt
  • @nestjs/jwt, passport, passport-jwt: For handling JWT authentication.
  • bcrypt: For hashing passwords.
  • class-validator, class-transformer: For validating request DTOs (Data Transfer Objects).
  • moment: For easy date/time manipulation (OTP expiry).

2.2 Create Auth Module

bash
nest generate module auth
nest generate controller auth --no-spec
nest generate service auth --no-spec

2.3 Configure JWT Module

Register the JwtModule within the AuthModule. We'll use ConfigService to read the secret and expiration time from .env.

src/auth/auth.module.ts:

typescript
// src/auth/auth.module.ts
import { Module } from '@nestjs/common';
import { AuthService } from './auth.service';
import { AuthController } from './auth.controller';
import { PrismaModule } from '../prisma/prisma.module'; // Import PrismaModule if needed by AuthService
import { PassportModule } from '@nestjs/passport';
import { JwtModule } from '@nestjs/jwt';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { JwtStrategy } from './strategies/jwt.strategy'; // We'll create this next
import { UsersModule } from '../users/users.module'; // We'll create Users module/service

@Module({
  imports: [
    PrismaModule, // Needed if AuthService directly uses PrismaService
    UsersModule,  // Import UsersModule to use UsersService
    PassportModule.register({ defaultStrategy: 'jwt' }),
    JwtModule.registerAsync({
      imports: [ConfigModule], // Import ConfigModule to use ConfigService
      useFactory: async (configService: ConfigService) => ({
        secret: configService.get<string&gt;('JWT_SECRET'),
        signOptions: {
          expiresIn: configService.get<string&gt;('JWT_EXPIRATION_TIME'),
        },
      }),
      inject: [ConfigService], // Inject ConfigService into the factory
    }),
    ConfigModule, // Ensure ConfigModule is imported if not global or imported elsewhere
  ],
  controllers: [AuthController],
  providers: [AuthService, JwtStrategy], // Add JwtStrategy
  exports: [AuthService, JwtModule, PassportModule], // Export if needed elsewhere
})
export class AuthModule {}

2.4 Create Users Module/Service

It's good practice to separate user data access logic.

bash
nest generate module users
nest generate service users --no-spec

src/users/users.service.ts:

typescript
// src/users/users.service.ts
import { Injectable, NotFoundException, Logger } from '@nestjs/common';
import { PrismaService } from '../prisma/prisma.service';
import { User, Prisma } from '@prisma/client';

@Injectable()
export class UsersService {
  private readonly logger = new Logger(UsersService.name);

  constructor(private prisma: PrismaService) {}

  async findOneById(id: string): Promise<User | null&gt; {
    return this.prisma.user.findUnique({ where: { id } });
  }

  async findOneByEmail(email: string): Promise<User | null&gt; {
    return this.prisma.user.findUnique({ where: { email } });
  }

  async createUser(data: Prisma.UserCreateInput): Promise<User&gt; {
    this.logger.log(`Attempting to create user with email: ${data.email}`);
    return this.prisma.user.create({ data });
  }

  async updateUser(id: string, data: Prisma.UserUpdateInput): Promise<User&gt; {
    this.logger.log(`Attempting to update user with ID: ${id}`);
    try {
      return await this.prisma.user.update({
        where: { id },
        data,
      });
    } catch (error) {
      // Handle potential errors, e.g., user not found
      if (error instanceof Prisma.PrismaClientKnownRequestError && error.code === 'P2025') {
        this.logger.error(`User with ID ${id} not found for update.`);
        throw new NotFoundException(`User with ID ${id} not found`);
      }
      this.logger.error(`Error updating user ${id}:`, error);
      throw error; // Re-throw other errors
    }
  }
  // For improved separation of concerns, consider delegating all direct `User` model updates
  // (like setting flags) to this `UsersService`, even if called from `AuthService`.
}

src/users/users.module.ts:

typescript
// src/users/users.module.ts
import { Module } from '@nestjs/common';
import { UsersService } from './users.service';
import { PrismaModule } from '../prisma/prisma.module'; // Import PrismaModule

@Module({
  imports: [PrismaModule], // PrismaService is needed by UsersService
  providers: [UsersService],
  exports: [UsersService], // Export UsersService to be used in other modules (like AuthModule)
})
export class UsersModule {}

Remember to import UsersModule into AppModule as well.

src/app.module.ts (Updated):

typescript
// src/app.module.ts
import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { PrismaModule } from './prisma/prisma.module';
import { AuthModule } from './auth/auth.module'; // Import AuthModule
import { UsersModule } from './users/users.module'; // Import UsersModule
// Sinch module will be added later

@Module({
  imports: [
    ConfigModule.forRoot({ isGlobal: true, envFilePath: '.env' }),
    PrismaModule,
    UsersModule, // Add UsersModule
    AuthModule,  // Add AuthModule
    // Sinch module will be added later
  ],
  controllers: [],
  providers: [],
})
export class AppModule {}

2.5 Implement JWT Strategy

This strategy validates incoming JWTs in protected routes.

Create src/auth/strategies/jwt.strategy.ts:

typescript
// src/auth/strategies/jwt.strategy.ts
import { Injectable, UnauthorizedException, Logger } from '@nestjs/common';
import { PassportStrategy } from '@nestjs/passport';
import { Strategy, ExtractJwt } from 'passport-jwt';
import { ConfigService } from '@nestjs/config';
import { UsersService } from '../../users/users.service'; // Correct path
import { JwtPayload } from '../interfaces/jwt-payload.interface'; // We'll create this

@Injectable()
export class JwtStrategy extends PassportStrategy(Strategy) {
  private readonly logger = new Logger(JwtStrategy.name);

  constructor(
    private readonly configService: ConfigService,
    private readonly usersService: UsersService,
  ) {
    super({
      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
      ignoreExpiration: false,
      secretOrKey: configService.get<string&gt;('JWT_SECRET'),
    });
    this.logger.log('JwtStrategy initialized');
  }

  async validate(payload: JwtPayload) {
    // Passport first verifies the JWT's signature and expiration based on the secret/options
    // Then, this validate function is called with the decoded payload
    this.logger.debug(`Validating JWT for user sub: ${payload.sub}`);

    // You can add extra validation here, e.g., check if user still exists
    const user = await this.usersService.findOneById(payload.sub);
    if (!user) {
      this.logger.warn(`JWT validation failed: User ${payload.sub} not found.`);
      throw new UnauthorizedException('User not found or token invalid.');
    }

    // The return value is attached to the request object as request.user
    // Return minimal, non-sensitive user info needed for request context
    return { userId: payload.sub, email: payload.email, firstName: user.firstName, lastName: user.lastName };
  }
}

Create the JwtPayload interface:

src/auth/interfaces/jwt-payload.interface.ts:

typescript
// src/auth/interfaces/jwt-payload.interface.ts
export interface JwtPayload {
  email: string;
  sub: string; // Standard JWT field for subject (usually user ID)
  firstName: string; // Included during signing
  lastName: string; // Included during signing
  // Add any other fields you included when signing the token
  // Standard fields like 'iat' and 'exp' are handled automatically
}

2.6 Implement Signup

Create DTO for signup request validation:

src/auth/dto/signup.dto.ts:

typescript
// src/auth/dto/signup.dto.ts
import { IsEmail, IsString, MinLength, IsNotEmpty } from 'class-validator';

export class SignUpDto {
  @IsNotEmpty()
  @IsEmail()
  email: string;

  @IsNotEmpty()
  @IsString()
  @MinLength(8, { message: 'Password must be at least 8 characters long' })
  password: string;

  @IsNotEmpty()
  @IsString()
  firstName: string;

  @IsNotEmpty()
  @IsString()
  lastName: string;

  // Phone number is optional at signup, added later for verification
}

Update AuthService for signup logic:

src/auth/auth.service.ts:

typescript
// src/auth/auth.service.ts
import { Injectable, ConflictException, InternalServerErrorException, UnauthorizedException, BadRequestException, Logger } from '@nestjs/common'; // Added Logger
import { JwtService } from '@nestjs/jwt';
import { UsersService } from '../users/users.service';
import { PrismaService } from '../prisma/prisma.service'; // Or inject directly if needed
import * as bcrypt from 'bcrypt';
import { SignUpDto } from './dto/signup.dto';
import { LoginDto } from './dto/login.dto'; // We'll create this
import { JwtPayload } from './interfaces/jwt-payload.interface';
import { User, Prisma } from '@prisma/client'; // Import Prisma namespace
import { ConfigService } from '@nestjs/config'; // If needed for JWT signing

@Injectable()
export class AuthService {
  private readonly logger = new Logger(AuthService.name); // Instantiate Logger

  constructor(
    private usersService: UsersService,
    private jwtService: JwtService,
    private prisma: PrismaService, // Inject Prisma if needed for transactions or specific queries
    private configService: ConfigService, // Inject if reading JWT details here
  ) {}

  async signUp(signUpDto: SignUpDto): Promise&lt;{ message: string }&gt; {
    const { email, password, firstName, lastName } = signUpDto;
    this.logger.log(`Signup attempt for email: ${email}`);

    // 1. Check if user already exists
    const existingUser = await this.usersService.findOneByEmail(email);
    if (existingUser) {
      this.logger.warn(`Signup failed: Email ${email} already registered.`);
      throw new ConflictException('Email already registered');
    }

    // 2. Hash password
    const saltRounds = 10; // Standard practice
    const hashedPassword = await bcrypt.hash(password, saltRounds);
    this.logger.debug(`Password hashed for email: ${email}`);

    // 3. Create user
    try {
      await this.usersService.createUser({
        email,
        password: hashedPassword,
        firstName,
        lastName,
        // phone is not set here
      });
      this.logger.log(`User registered successfully: ${email}`);
      return { message: 'User registered successfully. Please log in.' };
    } catch (error) {
      // Handle potential database errors (e.g., unique constraint violation if check failed somehow)
      this.logger.error(`Signup Error for email ${email}:`, error);
      if (error instanceof Prisma.PrismaClientKnownRequestError && error.code === 'P2002') {
           // This shouldn't happen due to the check above, but handle defensively
           throw new ConflictException('Email already registered.');
      }
      throw new InternalServerErrorException('Could not register user.');
    }
  }

  // Login method will be added next
}

Update AuthController for the signup endpoint:

src/auth/auth.controller.ts:

typescript
// src/auth/auth.controller.ts
import { Controller, Post, Body, HttpCode, HttpStatus, UsePipes, ValidationPipe } from '@nestjs/common';
import { AuthService } from './auth.service';
import { SignUpDto } from './dto/signup.dto';
import { LoginDto } from './dto/login.dto'; // We'll create this

@Controller('auth')
export class AuthController {
  constructor(private readonly authService: AuthService) {}

  @Post('signup')
  @HttpCode(HttpStatus.CREATED)
  @UsePipes(new ValidationPipe({ whitelist: true, transform: true })) // Ensure DTO validation runs
  async signUp(@Body() signUpDto: SignUpDto): Promise&lt;{ message: string }&gt; {
    return this.authService.signUp(signUpDto);
  }

  // Login endpoint will be added next
}

2.7 Implement Basic Login

Create DTO for login request validation:

src/auth/dto/login.dto.ts:

typescript
// src/auth/dto/login.dto.ts
import { IsEmail, IsString, MinLength, IsNotEmpty } from 'class-validator';

export class LoginDto {
  @IsNotEmpty()
  @IsEmail()
  email: string;

  @IsNotEmpty()
  @IsString()
  @MinLength(8) // Match signup or enforce minimum
  password: string;
}

Add login logic to AuthService:

src/auth/auth.service.ts (Additions):

typescript
// ... (imports and existing methods)

@Injectable()
export class AuthService {
  private readonly logger = new Logger(AuthService.name);
  // ... (constructor and signUp method)

  async login(loginDto: LoginDto): Promise&lt;{ accessToken: string } | { twoFactorRequired: boolean_ message: string_ email?: string }&gt; {
    const { email, password } = loginDto;
    this.logger.log(`Login attempt for email: ${email}`);

    // 1. Find user by email
    const user = await this.usersService.findOneByEmail(email);
    if (!user) {
      this.logger.warn(`Login failed: User not found for email ${email}`);
      throw new UnauthorizedException('Invalid credentials'); // Keep messages generic
    }

    // 2. Compare password
    const isPasswordMatching = await bcrypt.compare(password, user.password);
    if (!isPasswordMatching) {
      this.logger.warn(`Login failed: Invalid password for email ${email}`);
      throw new UnauthorizedException('Invalid credentials');
    }

    // 3. Check if 2FA is enabled (We'll handle the 2FA flow later)
    if (user.twoFactorEnabled) {
      if (!user.isPhoneVerified || !user.phone) {
         // This case should ideally not happen if UI enforces phone verification before enabling 2FA
         this.logger.warn(`User ${user.id} has 2FA enabled but no verified phone.`);
         throw new BadRequestException('Two-factor authentication setup incomplete. Please verify your phone number or contact support.');
      }
      // --- Placeholder for 2FA OTP sending logic ---
      // In a real 2FA flow, we would *not* issue the JWT here.
      // Instead, we'd generate/send an OTP and return a response indicating
      // that the next step (OTP verification) is required.
      // We will implement this properly in section 6.
      this.logger.log(`User ${user.id} (${email}) requires 2FA. OTP sending logic needed here.`);
      // For now, let's simulate the need for 2FA - THIS WILL BE REPLACED
       return { twoFactorRequired: true, message: 'OTP verification required.', email: user.email }; // Return email for the next step
      // --- End Placeholder ---
    }

    // 4. Generate JWT (Only if 2FA is NOT enabled or already passed)
    this.logger.log(`Standard login successful for user ${user.id} (${email}). Issuing JWT.`);
    const accessToken = await this.signJwtToken(user); // Use helper method

    return { accessToken };
  }

   // --- Helper to sign JWT (can be reused) ---
  async signJwtToken(user: User): Promise<string&gt; {
    const payload: JwtPayload = {
        email: user.email,
        sub: user.id,
        firstName: user.firstName,
        lastName: user.lastName,
    };
    return this.jwtService.signAsync(payload);
  }

  // OTP methods will be added later
}

Add the login endpoint to AuthController:

src/auth/auth.controller.ts (Additions):

typescript
// ... (imports and existing methods)

@Controller('auth')
export class AuthController {
  // ... (constructor and signUp method)

  @Post('login')
  @HttpCode(HttpStatus.OK)
  @UsePipes(new ValidationPipe({ whitelist: true, transform: true }))
  async login(@Body() loginDto: LoginDto): Promise&lt;{ accessToken: string } | { twoFactorRequired: boolean_ message: string_ email?: string }&gt; {
    // The service now handles the logic for 2FA check
    return this.authService.login(loginDto);
  }

  // Other endpoints (verify-2fa, etc.) will be added later
}

At this point, you have basic user registration and login without 2FA fully implemented.

3. Integrating Sinch for SMS OTP

Now, let's integrate Sinch to send SMS messages.

3.1 Install Sinch SDK

Choose the appropriate Sinch SDK package. Check Sinch's official documentation for the latest recommended packages (e.g., @sinch/sdk-core, @sinch/sms).

bash
npm install @sinch/sdk-core @sinch/sms # Adjust package names based on current Sinch docs

3.2 Create Sinch Module and Service

Encapsulate Sinch logic within its own module.

bash
nest generate module sinch
nest generate service sinch --no-spec

3.3 Implement Sinch Service

This service will initialize the Sinch client and provide a method to send SMS.

src/sinch/sinch.service.ts:

typescript
// src/sinch/sinch.service.ts
import { Injectable, OnModuleInit, Logger } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
// Adjust import based on actual package structure and chosen SDK
import { SinchClient, SmsRegion } from '@sinch/sdk-core'; // Example import
import { Sms } from '@sinch/sms'; // Example import for SMS product

@Injectable()
export class SinchService implements OnModuleInit {
  private readonly logger = new Logger(SinchService.name);
  private sinchClient: SinchClient | null = null; // Use type from SDK
  private sms: Sms | null = null; // Use type from SDK

  constructor(private configService: ConfigService) {}

  onModuleInit() {
    const projectId = this.configService.get<string&gt;('SINCH_SERVICE_PLAN_ID'); // Or Project ID, check Sinch terminology
    const keyId = this.configService.get<string&gt;('SINCH_KEY_ID'); // Often Key ID and Secret are used
    const keySecret = this.configService.get<string&gt;('SINCH_API_TOKEN'); // Or Key Secret

    if (!projectId || !keyId || !keySecret) {
      this.logger.error('Sinch Project ID, Key ID, or Key Secret missing in environment variables. SMS sending disabled.');
      // Decide how to handle this - throw error, disable service?
      // For now, we log the error. Sending SMS will fail.
      return;
    }

    try {
      // **Critical:** The Sinch SDK initialization shown here is an *example*
      // and highly dependent on the specific SDK version you install.
      // **Always consult the official Sinch Node.js SDK documentation**
      // for the correct initialization method corresponding to your SDK version.
      this.sinchClient = new SinchClient({
        projectId,
        keyId,
        keySecret,
        // smsRegion: SmsRegion.US, // Example: Specify region if needed/supported
      });
      // Get the SMS product instance from the client
      this.sms = this.sinchClient.sms;

      this.logger.log('Sinch Client Initialized Successfully.');
    } catch (error) {
        this.logger.error('Failed to initialize Sinch Client', error);
        // Prevent application from crashing, but log the critical failure
        this.sinchClient = null;
        this.sms = null;
    }
  }

  async sendSms(to: string, body: string): Promise<boolean&gt; {
    if (!this.sinchClient || !this.sms) {
      this.logger.error('Sinch client or SMS service not initialized. Cannot send SMS.');
      return false;
    }

    const fromNumber = this.configService.get<string&gt;('SINCH_PHONE_NUMBER'); // Optional: Sender ID/Number

    // Ensure 'to' number is in E.164 format if required by Sinch
    const formattedTo = to.startsWith('+') ? to : `+${to}`; // Basic assumption, may need better validation

    // Construct the request payload according to the Sinch SMS API SDK
    // This structure is an EXAMPLE and might differ. Refer to official docs.
    const sendBatchRequest = { // Replace with actual Request type from SDK if different
        to: [formattedTo],
        from: fromNumber,
        body: body,
        // Add other parameters as needed (e.g., delivery reports, type)
    };

    try {
      this.logger.log(`Attempting to send SMS via Sinch to: ${formattedTo}`);
      // **Critical:** The actual method call depends on the SDK version.
      // This is an EXAMPLE. It might be `this.sms.batches.send(...)` or similar.
      // Consult the Sinch SDK documentation for the correct method.
      const response = await this.sms.batches.send(sendBatchRequest); // EXAMPLE CALL

      // Log success based on the actual response structure from the SDK
      this.logger.log(`Sinch SMS sent successfully. Response ID (example): ${response?.id}`); // Adjust logging based on actual response
      return true;
    } catch (error) {
      // Log the specific error from the Sinch SDK
      this.logger.error(`Failed to send Sinch SMS to ${formattedTo}:`, error?.response?.data || error?.message || error);
      return false;
    }
  }
}

Make the SinchService available and import ConfigModule:

src/sinch/sinch.module.ts:

typescript
// src/sinch/sinch.module.ts
import { Module } from '@nestjs/common';
import { SinchService } from './sinch.service';
import { ConfigModule } from '@nestjs/config'; // Import ConfigModule

@Module({
  imports: [ConfigModule], // SinchService needs ConfigService
  providers: [SinchService],
  exports: [SinchService], // Export SinchService for use in other modules
})
export class SinchModule {}

Import SinchModule into AppModule:

src/app.module.ts (Updated):

typescript
// src/app.module.ts
import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { PrismaModule } from './prisma/prisma.module';
import { AuthModule } from './auth/auth.module';
import { UsersModule } from './users/users.module';
import { SinchModule } from './sinch/sinch.module'; // Import SinchModule

@Module({
  imports: [
    ConfigModule.forRoot({ isGlobal: true, envFilePath: '.env' }),
    PrismaModule,
    UsersModule,
    AuthModule,
    SinchModule, // Add SinchModule
  ],
  controllers: [],
  providers: [],
})
export class AppModule {}

Now you have a dedicated service for sending SMS via Sinch, configured using environment variables. The next steps would involve creating OTP generation logic, endpoints for requesting/verifying OTPs, and integrating this with the user profile and login flow.

Frequently Asked Questions

Implement 2FA by first setting up a NestJS project, integrating Sinch for SMS, and then building the authentication flow with phone verification and OTP delivery. The Sinch SMS API is used for sending OTPs, while Prisma handles database interactions for secure storage of user data and OTPs. This guide provides step-by-step instructions for setting up the entire process.

Prisma is used as an ORM (Object-Relational Mapper) to simplify database operations. It provides a type-safe interface for interacting with the PostgreSQL database, managing database migrations, and ensuring data integrity. This makes it easier to manage user data, OTP records, and other information related to authentication securely.

NestJS provides a robust and modular architecture well-suited for building scalable server-side applications. Its TypeScript support enhances code quality and maintainability. The modular structure helps organize code into controllers, services, and modules, improving code reusability and maintainability.

Enable 2FA after a user has successfully registered and verified their phone number. This adds an extra layer of security to the login process, protecting against unauthorized access even if the user's password is compromised. It's usually presented as an optional feature for users to activate.

While this guide focuses on Sinch, you can adapt the principles to integrate other SMS API providers. You'll need to adjust the SinchService to interact with your chosen provider's API and ensure it's compatible with the rest of the architecture. Key adjustments would involve modifying the service to make requests to the new provider's API endpoints and handle their specific response format.

PostgreSQL serves as the persistent data store for user information, including hashed passwords, phone numbers, 2FA status, and OTP records. It is a robust and reliable database solution chosen for its stability and open-source nature.

Create a .env file in the project root and add your Sinch Service Plan ID, API token, and optional Sinch phone number. The values for SINCH_SERVICE_PLAN_ID and SINCH_API_TOKEN are obtained from your Sinch account dashboard. The SINCH_PHONE_NUMBER is the virtual number or shortcode you use to send SMS.

You need Node.js, npm or yarn, a running PostgreSQL server, a Sinch account with SMS API credentials, and a basic understanding of TypeScript, REST APIs, and async/await. The NestJS CLI should also be installed globally to manage the project effectively.

bcrypt is used to securely hash user passwords before they are stored in the database. This ensures that even if the database is compromised, the raw passwords are not exposed, making it significantly harder for attackers to gain access to user accounts.

Class-validator and class-transformer are used for validating and transforming request data using Data Transfer Objects (DTOs). This helps ensure that data conforms to expected formats and types, improving the security and robustness of the API endpoints.

JSON Web Tokens (JWTs) are used for managing stateless authentication sessions after a user successfully logs in. Once authenticated, a JWT is issued to the client, which can be used to access protected routes without needing to send credentials each time.

The architecture consists of a Client, NestJS API, Prisma Client, PostgreSQL Database and the Sinch SMS API. The client interacts with the NestJS API, which handles the logic and communication with other services, like the Sinch API for SMS and Prisma for database interactions.

Use the NestJS CLI to create a new project: nest new sinch-otp-nestjs-app and navigate into the directory cd sinch-otp-nestjs-app. This command sets up the basic structure of your NestJS project.