@ackplus/nest-auth 0.1.51 → 1.1.0

package/src/lib/auth/auth.module.ts

@@ -0,0 +1,58 @@
+import { Module, forwardRef } from '@nestjs/common';
+import { AuthService } from './services/auth.service';
+import { CookieService } from './services/cookie.service';
+import { MfaService } from './services/mfa.service';
+import { ClientConfigService } from './services/client-config.service';
+import { NestAuthAuthGuard } from './guards/auth.guard';
+import { RefreshTokenInterceptor } from './interceptors/refresh-token.interceptor';
+import { AuthController } from './controllers/auth.controller';
+import { MfaController } from './controllers/mfa.controller';
+import { NestAuthIdentity } from '../user/entities/identity.entity';
+import { TypeOrmModule } from '@nestjs/typeorm';
+import { NestAuthUser } from '../user/entities/user.entity';
+import { NestAuthOTP } from './entities/otp.entity';
+import { NestAuthMFASecret } from './entities/mfa-secret.entity';
+import { NestAuthAccessKey } from '../user/entities/access-key.entity';
+import { EventEmitterModule } from '@nestjs/event-emitter';
+import { UserModule } from '../user/user.module';
+import { CoreModule } from '../core/core.module';
+import { SessionModule } from '../session/session.module';
+import { TenantModule } from '../tenant/tenant.module';
+import { RoleModule } from '../role/role.module';
+
+@Module({
+    imports: [
+        EventEmitterModule,
+        TypeOrmModule.forFeature([
+            NestAuthUser,
+            NestAuthOTP,
+            NestAuthMFASecret,
+            NestAuthAccessKey,
+            NestAuthIdentity,
+        ]),
+        forwardRef(() => CoreModule),
+        forwardRef(() => UserModule),
+        forwardRef(() => SessionModule),
+        forwardRef(() => TenantModule),
+        forwardRef(() => RoleModule),
+    ],
+    providers: [
+        AuthService,
+        CookieService,
+        MfaService,
+        ClientConfigService,
+        NestAuthAuthGuard,
+        RefreshTokenInterceptor,
+    ],
+    controllers: [AuthController, MfaController],
+    exports: [
+        AuthService,
+        CookieService,
+        MfaService,
+        ClientConfigService,
+        NestAuthAuthGuard,
+        RefreshTokenInterceptor,
+    ],
+})
+export class AuthModule {
+}

package/src/lib/auth/controllers/auth.controller.ts

@@ -0,0 +1,393 @@
+import { Controller, Post, Body, Get, UseGuards, Res, HttpCode, Query, Param } from '@nestjs/common';
+import { AuthService } from '../services/auth.service';
+import { Verify2faRequestDto } from '../dto/requests/verify-2fa.request.dto';
+import { RefreshTokenRequestDto } from '../dto/requests/refresh-token.request.dto';
+import { Response } from 'express';
+import { ApiResponse } from '@nestjs/swagger';
+import { ApiOperation } from '@nestjs/swagger';
+import { CookieService } from '../services/cookie.service';
+import { AuthConfigService } from '../../core/services/auth-config.service';
+import { AuthWithTokensResponseDto, UserResponseDto, Verify2faWithTokensResponseDto } from '../dto/responses/auth.response.dto';
+import { AuthCookieResponseDto } from '../dto/responses/auth-cookie.response.dto';
+import { SignupRequestDto } from '../dto/requests/signup.request.dto';
+import { LoginRequestDto } from '../dto/requests/login.request.dto';
+import { RequestContext } from '../../request-context/request-context';
+import { MessageResponseDto, MFAMethodEnum, SkipMfa } from '../../core';
+import { ForgotPasswordRequestDto } from '../dto/requests/forgot-password.request.dto';
+import { ResetPasswordRequestDto } from '../dto/requests/reset-password.request.dto';
+import { NestAuthAuthGuard } from '../guards/auth.guard';
+import { VerifyForgotPasswordOtpRequestDto } from '../dto/requests/verify-forgot-password-otp-request-dto';
+import { ResetPasswordWithTokenRequestDto } from '../dto/requests/reset-password-with-token.request.dto';
+import { VerifyOtpResponseDto } from '../dto/responses/verify-otp.response.dto';
+import { ChangePasswordRequestDto } from '../dto/requests/change-password.request.dto';
+import { SendEmailVerificationRequestDto } from '../dto/requests/send-email-verification.request.dto';
+import { VerifyEmailRequestDto } from '../dto/requests/verify-email.request.dto';
+import { ClientConfigService } from '../services/client-config.service';
+import { ClientConfigResponseDto } from '../dto/responses/client-config.response.dto';
+
+
+@Controller('auth')
+export class AuthController {
+    constructor(
+        private readonly authService: AuthService,
+        private readonly cookieService: CookieService,
+        private readonly authConfig: AuthConfigService,
+        private readonly clientConfigService: ClientConfigService,
+    ) { }
+
+    /**
+     * Check if using cookie-based authentication
+     */
+    protected isUsingCookies(): boolean {
+        const config = this.authConfig.getConfig();
+        return config.accessTokenType === 'cookie';
+    }
+
+    /**
+     * Handle auth response based on configuration
+     * - If cookie mode: Sets tokens in cookies, returns success message
+     * - If header mode: Returns tokens in response body
+     */
+    protected handleAuthResponse(
+        res: Response,
+        authResult: { accessToken: string; refreshToken: string; isRequiresMfa: boolean },
+        successMessage: string = 'Authentication successful'
+    ): void {
+        if (this.isUsingCookies()) {
+            // Cookie mode: Set tokens in cookies, return success message
+            this.cookieService.setTokens(res, authResult.accessToken, authResult.refreshToken);
+            res.status(200).json({
+                message: successMessage,
+                isRequiresMfa: authResult.isRequiresMfa
+            } as AuthCookieResponseDto);
+        } else {
+            // Header mode: Return tokens in response body
+            res.status(200).json({
+                message: successMessage,
+                accessToken: authResult.accessToken,
+                refreshToken: authResult.refreshToken,
+                isRequiresMfa: authResult.isRequiresMfa
+            } as AuthWithTokensResponseDto);
+        }
+    }
+
+    /**
+     * Handle 2FA verification response based on configuration
+     */
+    protected handle2faResponse(
+        res: Response,
+        authResult: { accessToken: string; refreshToken: string }
+    ): void {
+        if (this.isUsingCookies()) {
+            // Cookie mode: Set tokens in cookies, return success message
+            this.cookieService.setTokens(res, authResult.accessToken, authResult.refreshToken);
+            res.status(200).json({
+                message: '2FA verification successful'
+                // Note: No isRequiresMfa for 2FA verification (it's already verified)
+            } as AuthCookieResponseDto);
+        } else {
+            // Header mode: Return message AND tokens in response body
+            res.status(200).json({
+                message: '2FA verification successful',
+                accessToken: authResult.accessToken,
+                refreshToken: authResult.refreshToken
+            } as Verify2faWithTokensResponseDto);
+        }
+    }
+
+    @ApiOperation({
+        summary: 'Signup',
+        description: 'Register a new user. Response format depends on accessTokenType configuration:\n' +
+            '- Header mode (default): Returns tokens in response body\n' +
+            '- Cookie mode: Sets tokens in HTTP-only cookies and returns success message'
+    })
+    @ApiResponse({ status: 200, type: AuthWithTokensResponseDto, description: 'Header mode: Returns message + tokens in body' })
+    @ApiResponse({ status: 200, type: AuthCookieResponseDto, description: 'Cookie mode: Returns message only, tokens in cookies' })
+    @HttpCode(200)
+    @Post('signup')
+    async signup(@Body() input: SignupRequestDto, @Res() res: Response) {
+        const response = await this.authService.signup(input);
+        this.handleAuthResponse(res, response, 'Signup successful');
+    }
+
+    @ApiOperation({
+        summary: 'Login',
+        description: 'Authenticate user. Response format depends on accessTokenType configuration:\n' +
+            '- Header mode (default): Returns tokens in response body\n' +
+            '- Cookie mode: Sets tokens in HTTP-only cookies and returns success message'
+    })
+    @ApiResponse({ status: 200, type: AuthWithTokensResponseDto, description: 'Header mode: Returns message + tokens in body' })
+    @ApiResponse({ status: 200, type: AuthCookieResponseDto, description: 'Cookie mode: Returns message only, tokens in cookies' })
+    @HttpCode(200)
+    @Post('login')
+    async login(@Body() input: LoginRequestDto, @Res() res: Response) {
+        const response = await this.authService.login(input);
+        this.handleAuthResponse(res, response, 'Login successful');
+    }
+
+    @ApiOperation({
+        summary: 'Refresh Token',
+        description: 'Refresh access token. Response format depends on accessTokenType configuration:\n' +
+            '- Header mode (default): Returns new tokens in response body\n' +
+            '- Cookie mode: Sets new tokens in HTTP-only cookies and returns success message'
+    })
+    @ApiResponse({ status: 200, type: AuthWithTokensResponseDto, description: 'Header mode: Returns message + tokens in body' })
+    @ApiResponse({ status: 200, type: AuthCookieResponseDto, description: 'Cookie mode: Returns message only, tokens in cookies' })
+    @HttpCode(200)
+    @Post('refresh-token')
+    async refreshToken(@Body() input: RefreshTokenRequestDto, @Res() res: Response) {
+        const response = await this.authService.refreshToken(input.refreshToken);
+        // Note: Refresh response doesn't have isRequiresMfa, so we create a compatible object
+        this.handleAuthResponse(res, { ...response, isRequiresMfa: false }, 'Token refreshed successfully');
+    }
+
+
+    @ApiOperation({ summary: 'Send 2FA Code' })
+    @ApiResponse({ status: 200, type: MessageResponseDto })
+    @HttpCode(200)
+    @Post('send-2fa-code')
+    @SkipMfa()
+    @UseGuards(NestAuthAuthGuard)
+    async send2faCode(@Body('method') method: MFAMethodEnum) {
+        const user = RequestContext.currentUser();
+        await this.authService.send2faCode(user.id, method);
+        return { message: '2FA code sent successfully' }
+    }
+
+    @ApiOperation({
+        summary: 'Verify 2FA',
+        description: 'Verify two-factor authentication. Response format depends on accessTokenType configuration:\n' +
+            '- Header mode (default): Returns tokens in response body\n' +
+            '- Cookie mode: Sets tokens in HTTP-only cookies and returns success message'
+    })
+    @ApiResponse({ status: 200, type: Verify2faWithTokensResponseDto, description: 'Header mode: Returns message + tokens in body' })
+    @ApiResponse({ status: 200, type: AuthCookieResponseDto, description: 'Cookie mode: Returns message only, tokens in cookies' })
+    @HttpCode(200)
+    @Post('verify-2fa')
+    @SkipMfa()
+    @UseGuards(NestAuthAuthGuard)
+    async verify2fa(@Body() input: Verify2faRequestDto, @Res() res: Response) {
+        const response = await this.authService.verify2fa(input);
+        this.handle2faResponse(res, response);
+    }
+
+    @ApiOperation({ summary: 'Logout' })
+    @ApiResponse({ status: 200, type: MessageResponseDto })
+    @HttpCode(200)
+    @Post('logout')
+    @SkipMfa()
+    @UseGuards(NestAuthAuthGuard)
+    async logout(@Res() res: Response) {
+        await this.authService.logout();
+
+        // Only clear cookies if using cookie-based auth
+        if (this.isUsingCookies()) {
+            this.cookieService.clearCookies(res);
+        }
+
+        res.status(200).json({ message: 'Logged out successfully' });
+    }
+
+    @ApiOperation({ summary: 'Logout All' })
+    @ApiResponse({ status: 200, type: MessageResponseDto })
+    @HttpCode(200)
+    @Post('logout-all')
+    @SkipMfa()
+    @UseGuards(NestAuthAuthGuard)
+    async logoutAll(): Promise<MessageResponseDto> {
+        const user = RequestContext.currentUser();
+        await this.authService.logoutAll(user.id);
+        return { message: 'Logged out from all devices successfully' };
+    }
+
+    @ApiOperation({ summary: 'Change Password' })
+    @ApiResponse({ status: 200, type: AuthWithTokensResponseDto })
+    @HttpCode(200)
+    @Post('change-password')
+    @SkipMfa()
+    @UseGuards(NestAuthAuthGuard)
+    async changePassword(@Body() input: ChangePasswordRequestDto, @Res() res: Response) {
+        const response = await this.authService.changePassword(input);
+        this.handleAuthResponse(res, response, 'Password updated successfully');
+    }
+
+    @ApiOperation({ summary: 'Forgot Password' })
+    @ApiResponse({ status: 200, type: MessageResponseDto })
+    @HttpCode(200)
+    @Post('forgot-password')
+    @SkipMfa()
+    async forgotPassword(@Body() input: ForgotPasswordRequestDto): Promise<MessageResponseDto> {
+        await this.authService.forgotPassword(input);
+        return { message: 'If the account exists, a password reset code has been sent' }
+    }
+
+    @ApiOperation({ summary: 'Verify Forgot Password OTP and get reset token' })
+    @ApiResponse({ status: 200, type: VerifyOtpResponseDto })
+    @HttpCode(200)
+    @Post('verify-forgot-password-otp')
+    @SkipMfa()
+    async verifyForgotPasswordOtp(@Body() input: VerifyForgotPasswordOtpRequestDto): Promise<VerifyOtpResponseDto> {
+        return await this.authService.verifyForgotPasswordOtp(input);
+    }
+
+    @ApiOperation({ summary: 'Reset Password (Legacy - using OTP)' })
+    @ApiResponse({ status: 200, type: MessageResponseDto })
+    @HttpCode(200)
+    @Post('reset-password')
+    @SkipMfa()
+    async resetPassword(@Body() input: ResetPasswordRequestDto): Promise<MessageResponseDto> {
+        await this.authService.resetPassword(input);
+        return { message: 'Password reset successfully' }
+    }
+
+    @ApiOperation({ summary: 'Reset Password with Token' })
+    @ApiResponse({ status: 200, type: MessageResponseDto })
+    @HttpCode(200)
+    @Post('reset-password-with-token')
+    @SkipMfa()
+    async resetPasswordWithToken(@Body() input: ResetPasswordWithTokenRequestDto): Promise<MessageResponseDto> {
+        await this.authService.resetPasswordWithToken(input);
+        return { message: 'Password reset successfully' }
+    }
+
+    @ApiOperation({ summary: 'Get Logged In User' })
+    @ApiResponse({ status: 200, type: UserResponseDto })
+    @UseGuards(NestAuthAuthGuard)
+    @Get('user')
+    async getUser() {
+        return await this.authService.getUser();
+    }
+
+    @ApiOperation({ summary: 'Send Email Verification' })
+    @ApiResponse({ status: 200, type: MessageResponseDto })
+    @HttpCode(200)
+    @Post('send-email-verification')
+    @SkipMfa()
+    @UseGuards(NestAuthAuthGuard)
+    async sendEmailVerification(@Body() input: SendEmailVerificationRequestDto): Promise<MessageResponseDto> {
+        return await this.authService.sendEmailVerification(input);
+    }
+
+    @ApiOperation({ summary: 'Verify Email' })
+    @ApiResponse({ status: 200, type: MessageResponseDto })
+    @HttpCode(200)
+    @Post('verify-email')
+    @SkipMfa()
+    @UseGuards(NestAuthAuthGuard)
+    async verifyEmail(@Body() input: VerifyEmailRequestDto): Promise<MessageResponseDto> {
+        return await this.authService.verifyEmail(input);
+    }
+
+    @ApiOperation({
+        summary: 'Get Client Configuration',
+        description: 'Returns backend configuration for frontend clients. Includes enabled auth methods, registration settings, MFA options, tenant configuration, and SSO providers. Can be customized via clientConfig.factory in AuthModuleOptions.',
+    })
+    @ApiResponse({ status: 200, type: ClientConfigResponseDto })
+    @HttpCode(200)
+    @Get('client-config')
+    async getClientConfig(): Promise<ClientConfigResponseDto> {
+        return await this.clientConfigService.getClientConfig();
+    }
+
+    @ApiOperation({
+        summary: 'SSO Callback',
+        description: 'OAuth callback endpoint for SSO providers. Exchanges authorization code for access token and returns raw SSO user info. Returns HTML page that posts SSO data to parent window and auto-closes.',
+    })
+    @Get('callback/:provider')
+    async ssoCallback(
+        @Param('provider') provider: string,
+        @Query() data: any,
+        @Res() res: Response,
+    ) {
+
+        const jsonData = JSON.stringify(data);
+        const escapedData = jsonData.replace(/</g, '\\u003c').replace(/>/g, '\\u003e');
+
+        const html = `<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>SSO Callback</title>
+    <style>
+        body {
+            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, sans-serif;
+            display: flex;
+            justify-content: center;
+            align-items: center;
+            min-height: 100vh;
+            margin: 0;
+            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+        }
+        .container {
+            background: white;
+            padding: 2rem;
+            border-radius: 8px;
+            box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
+            text-align: center;
+            max-width: 400px;
+        }
+        .spinner {
+            border: 3px solid #f3f3f3;
+            border-top: 3px solid #667eea;
+            border-radius: 50%;
+            width: 40px;
+            height: 40px;
+            animation: spin 1s linear infinite;
+            margin: 0 auto 1rem;
+        }
+        @keyframes spin {
+            0% { transform: rotate(0deg); }
+            100% { transform: rotate(360deg); }
+        }
+        .message {
+            color: #333;
+            margin-top: 1rem;
+        }
+        .error {
+            color: #dc3545;
+        }
+    </style>
+</head>
+<body>
+    <div class="container">
+        <div class="spinner"></div>
+        <div class="message" id="message">Processing...</div>
+    </div>
+    <script>
+        (function() {
+            const data = ${escapedData};
+
+            // Post message to parent window
+            if (window.opener) {
+                window.opener.postMessage({
+                    type: 'nest-auth-sso-callback',
+                    ...data
+                }, '*');
+
+                // Auto-close immediately
+                window.close();
+            } else if (window.parent && window.parent !== window) {
+                // Iframe context
+                window.parent.postMessage({
+                    type: 'nest-auth-sso-callback',
+                    ...data
+                }, '*');
+                // Note: Can't close iframe from inside
+            } else {
+                // No parent window, show message
+                document.getElementById('message').textContent = data.success
+                    ? 'Success! You can close this window.'
+                    : 'Error: ' + (data.errorDescription || data.error);
+                document.getElementById('message').className = data.success ? 'message' : 'message error';
+            }
+        })();
+    </script>
+</body>
+</html>`;
+
+        res.setHeader('Content-Type', 'text/html');
+        res.status(200).send(html);
+    }
+
+}

package/src/lib/auth/controllers/mfa.controller.ts

@@ -0,0 +1,200 @@
+import { Controller, Post, Body, UnauthorizedException, UseGuards, HttpCode, Get, Delete, Param } from '@nestjs/common';
+import { SkipMfa, MessageResponseDto, MFAMethodEnum, NestAuthUser } from '../../core';
+import { MfaService } from '../services/mfa.service';
+import { RequestContext } from '../../request-context/request-context';
+import { SendMfaCodeRequestDto } from '../dto/requests/send-mfa-code.request.dto';
+import { VerifyTotpSetupRequestDto } from '../dto/requests/verify-totp-setup.request.dto';
+import { ApiOperation, ApiResponse } from '@nestjs/swagger';
+import { INVALID_MFA_EXCEPTION_CODE, USER_NOT_FOUND_EXCEPTION_CODE } from '../../auth.constants';
+import { NestAuthAuthGuard } from '../guards/auth.guard';
+import { ToggleMfaRequestDto } from '../dto/requests/toggle-mfa.request.dto';
+import { MfaStatusResponseDto, MfaDeviceDto } from '../dto/responses/mfa-status.response.dto';
+import { AuthConfigService } from '../../core/services/auth-config.service';
+
+@Controller('auth/mfa')
+export class MfaController {
+    constructor(
+        private readonly mfaService: MfaService,
+        private readonly authConfig: AuthConfigService,
+    ) { }
+
+    private getCurrentUserOrThrow() {
+        const user = RequestContext.currentUser();
+        if (!user) {
+            throw new UnauthorizedException('User not found');
+        }
+        return user;
+    }
+
+    @ApiOperation({ summary: 'Get MFA status for the current user' })
+    @ApiResponse({ status: 200, type: MfaStatusResponseDto })
+    @HttpCode(200)
+    @Get('status')
+    @SkipMfa()
+    @UseGuards(NestAuthAuthGuard)
+    async getStatus(): Promise<MfaStatusResponseDto> {
+        const user = this.getCurrentUserOrThrow();
+
+        const config = this.mfaService.mfaConfig;
+        const globallyEnabled = config?.enabled ?? false;
+
+        let enabledMethods: MFAMethodEnum[] = [];
+        let totpDevices: MfaDeviceDto[] = [];
+        let hasRecoveryCode = false;
+        let isEnabled = false;
+
+        if (globallyEnabled) {
+            [enabledMethods, totpDevices, hasRecoveryCode, isEnabled] = await Promise.all([
+                this.mfaService.getEnabledMethods(user.id),
+                this.mfaService.getTotpDevices(user.id),
+                this.mfaService.hasRecoveryCode(user.id),
+                this.mfaService.isMfaEnabled(user.id),
+            ]);
+        }
+
+        return {
+            isEnabled,
+            enabledMethods,
+            availableMethods: this.mfaService.getAvailableMethods(),
+            allowUserToggle: config?.allowUserToggle ?? false,
+            allowMethodSelection: config?.allowMethodSelection ?? false,
+            totpDevices,
+            hasRecoveryCode,
+        };
+    }
+
+    @ApiOperation({ summary: 'Enable or disable MFA for the current user' })
+    @ApiResponse({ status: 200, type: MessageResponseDto })
+    @HttpCode(200)
+    @Post('toggle')
+    @SkipMfa()
+    @UseGuards(NestAuthAuthGuard)
+    async toggleMfa(@Body() input: ToggleMfaRequestDto): Promise<MessageResponseDto> {
+        const user = this.getCurrentUserOrThrow();
+
+        this.mfaService.requireMfaEnabledForApp(true);
+
+        if (input.enabled) {
+            await this.mfaService.enableMFA(user.id);
+            return { message: 'MFA enabled successfully' };
+        }
+
+        await this.mfaService.disableMFA(user.id);
+        return { message: 'MFA disabled successfully' };
+    }
+
+    @ApiOperation({ summary: 'List registered MFA devices' })
+    @ApiResponse({ status: 200, type: [MfaDeviceDto] })
+    @HttpCode(200)
+    @Get('devices')
+    @SkipMfa()
+    @UseGuards(NestAuthAuthGuard)
+    async listDevices(): Promise<MfaDeviceDto[]> {
+        const user = this.getCurrentUserOrThrow();
+
+        this.mfaService.requireMfaEnabledForApp(true);
+        return await this.mfaService.getTotpDevices(user.id);
+    }
+
+    @ApiOperation({ summary: 'Remove a registered MFA device' })
+    @ApiResponse({ status: 200, type: MessageResponseDto })
+    @HttpCode(200)
+    @Delete('devices/:deviceId')
+    @SkipMfa()
+    @UseGuards(NestAuthAuthGuard)
+    async removeDevice(@Param('deviceId') deviceId: string): Promise<MessageResponseDto> {
+        const user = this.getCurrentUserOrThrow();
+
+        this.mfaService.requireMfaEnabledForApp(true);
+        await this.mfaService.removeTotpDevice(deviceId);
+        return { message: 'MFA device removed successfully' };
+    }
+
+    @ApiOperation({ summary: 'Send MFA Code' })
+    @ApiResponse({ status: 200, type: MessageResponseDto })
+    @HttpCode(200)
+    @Post('send-mfa-code')
+    @SkipMfa()
+    @UseGuards(NestAuthAuthGuard)
+    async sendMfaCode(@Body() input: SendMfaCodeRequestDto) {
+        const user = this.getCurrentUserOrThrow();
+
+        await this.mfaService.sendMfaCode(user.id, input.method);
+
+        return { message: 'MFA code sent' };
+    }
+
+    // These routes skip MFA verification
+    @ApiOperation({ summary: 'Setup TOTP Device' })
+    @ApiResponse({ status: 200, type: MessageResponseDto })
+    @HttpCode(200)
+    @Post('setup-totp')
+    @SkipMfa()
+    @UseGuards(NestAuthAuthGuard)
+    async setupTotp() {
+        const user = this.getCurrentUserOrThrow();
+
+        const config = this.authConfig.getConfig();
+
+        // Get app name from config, fallback to default
+        const appName = config.appName;
+
+        // Get user email - try from JWT token first, then from database
+        let userEmail = user.email;
+        if (!userEmail) {
+            const fullUser = await NestAuthUser.findOne({ where: { id: user.id } });
+            userEmail = fullUser?.email || 'User';
+        }
+
+        // Generate meaningful device name: {APP_NAME} : {email}
+        const deviceName = `${appName} : ${userEmail}`;
+
+        const { secret, qrCode } = await this.mfaService.setupTotpDevice(user.id, deviceName);
+        return { secret, qrCode };
+    }
+
+    @ApiOperation({ summary: 'Verify TOTP Setup' })
+    @ApiResponse({ status: 200, type: MessageResponseDto })
+    @HttpCode(200)
+    @Post('verify-totp-setup')
+    @SkipMfa()
+    @UseGuards(NestAuthAuthGuard)
+    async verifyTotpSetup(@Body() input: VerifyTotpSetupRequestDto) {
+        const user = this.getCurrentUserOrThrow();
+
+        const isVerified = await this.mfaService.verifyTotpSetup(user.id, input.secret, input.otp);
+        if (!isVerified) {
+            throw new UnauthorizedException({
+                message: 'Invalid OTP',
+                code: INVALID_MFA_EXCEPTION_CODE
+            });
+        }
+        return { message: 'Device setup successfully' };
+    }
+
+    @ApiOperation({ summary: 'Generate Recovery Codes' })
+    @ApiResponse({ status: 200, type: MessageResponseDto })
+    @HttpCode(200)
+    @Post('generate-recovery-code')
+    @SkipMfa()
+    @UseGuards(NestAuthAuthGuard)
+    async generateRecoveryCodes() {
+        const user = this.getCurrentUserOrThrow();
+
+        // Generate recovery codes
+        const code = await this.mfaService.generateRecoveryCode(user.id);
+        return { code };
+    }
+
+    @ApiOperation({ summary: 'Reset TOTP Device' })
+    @ApiResponse({ status: 200, type: MessageResponseDto })
+    @HttpCode(200)
+    @Post('reset-totp')
+    @SkipMfa()
+    @UseGuards(NestAuthAuthGuard)
+    async resetTotp(@Body('code') code: string) {
+        const user = this.getCurrentUserOrThrow();
+        await this.mfaService.resetMfa(user.id, code);
+        return { message: 'MFA reset successfully' };
+    }
+}

package/src/lib/auth/dto/credentials/email-credentials.dto.ts

@@ -0,0 +1,24 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { IsEmail, IsString, IsNotEmpty } from 'class-validator';
+
+/**
+ * Email-based login credentials
+ */
+export class EmailCredentialsDto {
+    @ApiProperty({
+        description: 'User email address',
+        example: 'user@example.com',
+    })
+    @IsEmail()
+    @IsNotEmpty()
+    email: string;
+
+    @ApiProperty({
+        description: 'User password',
+        example: 'SecurePass123!',
+        minLength: 8,
+    })
+    @IsString()
+    @IsNotEmpty()
+    password: string;
+}