Merge pull request #563 from BigBen-7/feat/health-2fa-queue-websocket

feat: health check, 2FA TOTP, Bull queue, and WebSocket gateway

Author: yusuftomilola

backend/package.json

@@ -22,6 +22,8 @@
   "dependencies": {
     "@aws-sdk/client-s3": "^3.975.0",
     "@nestjs/bull": "^11.0.4",
+    "@nestjs/platform-socket.io": "^10.4.15",
+    "@nestjs/terminus": "^10.2.3",
     "@nestjs/cache-manager": "^3.1.0",
     "@nestjs/common": "^10.0.0",
     "@nestjs/config": "^4.0.2",

backend/src/app.module.ts

@@ -72,6 +72,10 @@ import { ReportsModule } from './reports/reports.module';
     AssetsModule,
     ReportsModule,
     LocationsModule,
+    HealthModule,
+    AuthModule,
+    QueueModule,
+    NotificationsModule,
   ],
   controllers: [AppController],
   providers: [AppService, RolesGuard],

backend/src/assets/assets.service.ts

@@ -21,6 +21,7 @@ import { DepartmentsService } from '../departments/departments.service';
 import { CategoriesService } from '../categories/categories.service';
 import { UsersService } from '../users/users.service';
 import { StellarService } from '../stellar/stellar.service';
+import { NotificationsService } from '../notifications/notifications.service';
 import { User } from '../users/user.entity';
 import { StorageService } from '../storage/storage.service';
 import { Express } from 'express';
@@ -128,6 +129,7 @@ export class AssetsService {
     const saved = await this.assetsRepo.save(asset);
 
     await this.logHistory(saved, AssetHistoryAction.CREATED, 'Asset registered', null, null, currentUser);
+    this.notificationsService.emit('asset:created', { assetId: saved.id, assetCode: saved.assetId });
 
     // Derive on-chain ID deterministically and mark PENDING (only if Stellar enabled)
     if (this.stellarService.isEnabled) {
@@ -175,6 +177,7 @@ export class AssetsService {
 
     await this.assetsRepo.save(asset);
     await this.logHistory(asset, AssetHistoryAction.UPDATED, 'Asset updated', before as unknown as Record<string, unknown>, dto as unknown as Record<string, unknown>, currentUser);
+    this.notificationsService.emit('asset:updated', { assetId: id });
 
     return this.findOne(id);
   }
@@ -195,6 +198,7 @@ export class AssetsService {
       { status: dto.status },
       currentUser,
     );
+    this.notificationsService.emit('asset:status_changed', { assetId: id, from: prevStatus, to: dto.status });
 
     return this.findOne(id);
   }
@@ -219,6 +223,7 @@ export class AssetsService {
       { departmentId: asset.department.name },
       currentUser,
     );
+    this.notificationsService.emit('asset:transferred', { assetId: id, from: prevDept, to: asset.department.name });
 
     return this.findOne(id);
   }
@@ -302,6 +307,7 @@ export class AssetsService {
       { type: dto.type, scheduledDate: dto.scheduledDate },
       currentUser,
     );
+    this.notificationsService.emit('maintenance:scheduled', { assetId, maintenanceId: saved.id, type: dto.type });
     return saved;
   }
 

backend/src/auth/auth.controller.ts

@@ -134,7 +134,50 @@ export class AuthController {
       firstName: user.firstName,
       lastName: user.lastName,
       role: user.role,
+      twoFactorEnabled: user.twoFactorEnabled,
       createdAt: user.createdAt,
     };
   }
+
+  // ── 2FA endpoints ────────────────────────────────────────────────
+
+  @Post('2fa/setup')
+  @UseGuards(JwtAuthGuard)
+  @ApiBearerAuth('JWT-auth')
+  @ApiOperation({ summary: 'Generate TOTP secret and QR code for 2FA setup' })
+  @ApiResponse({ status: 201, description: 'Returns otpauthUrl and qrCodeDataUrl' })
+  twoFactorSetup(@CurrentUser() user: User) {
+    return this.authService.twoFactorSetup(user.id);
+  }
+
+  @Post('2fa/enable')
+  @HttpCode(HttpStatus.OK)
+  @UseGuards(JwtAuthGuard)
+  @ApiBearerAuth('JWT-auth')
+  @ApiOperation({ summary: 'Enable 2FA after verifying TOTP code' })
+  @ApiResponse({ status: 200, description: '2FA enabled' })
+  @ApiResponse({ status: 401, description: 'Invalid TOTP code' })
+  twoFactorEnable(@CurrentUser() user: User, @Body() dto: TwoFactorCodeDto) {
+    return this.authService.twoFactorEnable(user.id, dto.code);
+  }
+
+  @Post('2fa/disable')
+  @HttpCode(HttpStatus.OK)
+  @UseGuards(JwtAuthGuard)
+  @ApiBearerAuth('JWT-auth')
+  @ApiOperation({ summary: 'Disable 2FA after verifying TOTP code' })
+  @ApiResponse({ status: 200, description: '2FA disabled' })
+  @ApiResponse({ status: 401, description: 'Invalid TOTP code' })
+  twoFactorDisable(@CurrentUser() user: User, @Body() dto: TwoFactorCodeDto) {
+    return this.authService.twoFactorDisable(user.id, dto.code);
+  }
+
+  @Post('2fa/verify')
+  @HttpCode(HttpStatus.OK)
+  @ApiOperation({ summary: 'Complete login by verifying TOTP code against temp token' })
+  @ApiResponse({ status: 200, description: 'Returns full access and refresh tokens' })
+  @ApiResponse({ status: 401, description: 'Invalid code or token' })
+  twoFactorVerify(@Body() dto: TwoFactorVerifyDto) {
+    return this.authService.twoFactorVerify(dto.tempToken, dto.code);
+  }
 }

backend/src/auth/auth.service.ts

@@ -7,6 +7,8 @@ import {
 import { JwtService } from '@nestjs/jwt';
 import { ConfigService } from '@nestjs/config';
 import * as bcrypt from 'bcrypt';
+import * as speakeasy from 'speakeasy';
+import * as qrcode from 'qrcode';
 import { UsersService } from '../users/users.service';
 import { RegisterDto } from './dto/register.dto';
 import { LoginDto } from './dto/login.dto';
@@ -49,7 +51,12 @@ export class AuthService {
     return { user, tokens };
   }
 
-  async login(dto: LoginDto): Promise<{ user: User; tokens: AuthTokens }> {
+  async login(
+    dto: LoginDto,
+  ): Promise<
+    | { user: User; tokens: AuthTokens }
+    | { requiresTwoFactor: true; tempToken: string }
+  > {
     const user = await this.usersService.findByEmail(dto.email.toLowerCase());
     if (!user) {
       throw new UnauthorizedException('Invalid email or password');
@@ -60,6 +67,17 @@ export class AuthService {
       throw new UnauthorizedException('Invalid email or password');
     }
 
+    if (user.twoFactorEnabled) {
+      const tempToken = await this.jwtService.signAsync(
+        { sub: user.id, twoFactorPending: true },
+        {
+          secret: this.configService.get<string>('JWT_SECRET', 'change-me-in-env'),
+          expiresIn: '5m',
+        },
+      );
+      return { requiresTwoFactor: true, tempToken };
+    }
+
     const tokens = await this.signTokens(user);
     await this.storeRefreshToken(user.id, tokens.refreshToken);
 
@@ -136,4 +154,84 @@ export class AuthService {
     const hashed = await bcrypt.hash(token, 10);
     await this.usersService.updateRefreshToken(userId, hashed);
   }
+
+  // ── 2FA ──────────────────────────────────────────────────────────
+
+  async twoFactorSetup(userId: string): Promise<{ otpauthUrl: string; qrCodeDataUrl: string }> {
+    const user = await this.usersService.findById(userId);
+    const secret = speakeasy.generateSecret({
+      name: `ManageAssets (${user.email})`,
+    });
+
+    await this.usersService.updateTwoFactor(userId, secret.base32, false);
+
+    const qrCodeDataUrl = await qrcode.toDataURL(secret.otpauth_url!);
+    return { otpauthUrl: secret.otpauth_url!, qrCodeDataUrl };
+  }
+
+  async twoFactorEnable(userId: string, code: string): Promise<void> {
+    const user = await this.usersService.findByIdWithTwoFactor(userId);
+    if (!user?.twoFactorSecret) {
+      throw new BadRequestException('2FA setup not initiated. Call /auth/2fa/setup first.');
+    }
+
+    const valid = speakeasy.totp.verify({
+      secret: user.twoFactorSecret,
+      encoding: 'base32',
+      token: code,
+      window: 1,
+    });
+    if (!valid) throw new UnauthorizedException('Invalid TOTP code');
+
+    await this.usersService.updateTwoFactor(userId, user.twoFactorSecret, true);
+  }
+
+  async twoFactorDisable(userId: string, code: string): Promise<void> {
+    const user = await this.usersService.findByIdWithTwoFactor(userId);
+    if (!user?.twoFactorSecret) {
+      throw new BadRequestException('2FA is not set up for this account.');
+    }
+
+    const valid = speakeasy.totp.verify({
+      secret: user.twoFactorSecret,
+      encoding: 'base32',
+      token: code,
+      window: 1,
+    });
+    if (!valid) throw new UnauthorizedException('Invalid TOTP code');
+
+    await this.usersService.updateTwoFactor(userId, null, false);
+  }
+
+  async twoFactorVerify(tempToken: string, code: string): Promise<AuthTokens> {
+    let payload: { sub: string; twoFactorPending?: boolean };
+    try {
+      payload = await this.jwtService.verifyAsync(tempToken, {
+        secret: this.configService.get<string>('JWT_SECRET', 'change-me-in-env'),
+      });
+    } catch {
+      throw new UnauthorizedException('Invalid or expired temp token');
+    }
+
+    if (!payload.twoFactorPending) {
+      throw new UnauthorizedException('Token is not a 2FA pending token');
+    }
+
+    const user = await this.usersService.findByIdWithTwoFactor(payload.sub);
+    if (!user?.twoFactorSecret) {
+      throw new UnauthorizedException('2FA not configured');
+    }
+
+    const valid = speakeasy.totp.verify({
+      secret: user.twoFactorSecret,
+      encoding: 'base32',
+      token: code,
+      window: 1,
+    });
+    if (!valid) throw new UnauthorizedException('Invalid TOTP code');
+
+    const tokens = await this.signTokens(user);
+    await this.storeRefreshToken(user.id, tokens.refreshToken);
+    return tokens;
+  }
 }

backend/src/auth/dto/two-factor.dto.ts

@@ -0,0 +1,20 @@
+import { IsString, Length } from 'class-validator';
+import { ApiProperty } from '@nestjs/swagger';
+
+export class TwoFactorCodeDto {
+  @ApiProperty({ example: '123456', description: '6-digit TOTP code' })
+  @IsString()
+  @Length(6, 6)
+  code: string;
+}
+
+export class TwoFactorVerifyDto {
+  @ApiProperty({ description: 'Temporary token from login response' })
+  @IsString()
+  tempToken: string;
+
+  @ApiProperty({ example: '123456', description: '6-digit TOTP code' })
+  @IsString()
+  @Length(6, 6)
+  code: string;
+}

backend/src/health/health.controller.ts

@@ -0,0 +1,25 @@
+import { Controller, Get } from '@nestjs/common';
+import { ApiOperation, ApiResponse, ApiTags } from '@nestjs/swagger';
+import {
+  HealthCheck,
+  HealthCheckService,
+  TypeOrmHealthIndicator,
+} from '@nestjs/terminus';
+
+@ApiTags('Health')
+@Controller('health')
+export class HealthController {
+  constructor(
+    private readonly health: HealthCheckService,
+    private readonly db: TypeOrmHealthIndicator,
+  ) {}
+
+  @Get()
+  @HealthCheck()
+  @ApiOperation({ summary: 'Check service health and database connectivity' })
+  @ApiResponse({ status: 200, description: 'Service is healthy' })
+  @ApiResponse({ status: 503, description: 'Service unavailable' })
+  check() {
+    return this.health.check([() => this.db.pingCheck('database')]);
+  }
+}

backend/src/health/health.module.ts

@@ -0,0 +1,9 @@
+import { Module } from '@nestjs/common';
+import { TerminusModule } from '@nestjs/terminus';
+import { HealthController } from './health.controller';
+
+@Module({
+  imports: [TerminusModule],
+  controllers: [HealthController],
+})
+export class HealthModule {}

backend/src/notifications/notifications.gateway.ts

@@ -0,0 +1,59 @@
+import {
+  WebSocketGateway,
+  OnGatewayInit,
+  OnGatewayConnection,
+  OnGatewayDisconnect,
+  WebSocketServer,
+} from '@nestjs/websockets';
+import { Logger, UnauthorizedException } from '@nestjs/common';
+import { JwtService } from '@nestjs/jwt';
+import { ConfigService } from '@nestjs/config';
+import { Server, Socket } from 'socket.io';
+import { NotificationsService } from './notifications.service';
+
+@WebSocketGateway({ cors: true, namespace: '/notifications' })
+export class NotificationsGateway
+  implements OnGatewayInit, OnGatewayConnection, OnGatewayDisconnect
+{
+  @WebSocketServer()
+  server: Server;
+
+  private readonly logger = new Logger(NotificationsGateway.name);
+
+  constructor(
+    private readonly notificationsService: NotificationsService,
+    private readonly jwtService: JwtService,
+    private readonly configService: ConfigService,
+  ) {}
+
+  afterInit(server: Server): void {
+    this.notificationsService.setServer(server);
+    this.logger.log('WebSocket gateway initialized');
+  }
+
+  async handleConnection(client: Socket): Promise<void> {
+    const token =
+      (client.handshake.auth?.token as string | undefined) ??
+      (client.handshake.headers?.authorization as string | undefined)?.replace('Bearer ', '');
+
+    if (!token) {
+      this.logger.warn(`Client ${client.id} disconnected: no token`);
+      client.disconnect();
+      return;
+    }
+
+    try {
+      await this.jwtService.verifyAsync(token, {
+        secret: this.configService.get<string>('JWT_SECRET', 'change-me-in-env'),
+      });
+      this.logger.log(`Client connected: ${client.id}`);
+    } catch {
+      this.logger.warn(`Client ${client.id} disconnected: invalid token`);
+      client.disconnect();
+    }
+  }
+
+  handleDisconnect(client: Socket): void {
+    this.logger.log(`Client disconnected: ${client.id}`);
+  }
+}

backend/src/notifications/notifications.module.ts

@@ -0,0 +1,11 @@
+import { Module } from '@nestjs/common';
+import { JwtModule } from '@nestjs/jwt';
+import { NotificationsGateway } from './notifications.gateway';
+import { NotificationsService } from './notifications.service';
+
+@Module({
+  imports: [JwtModule.register({})],
+  providers: [NotificationsGateway, NotificationsService],
+  exports: [NotificationsService],
+})
+export class NotificationsModule {}