Merge remote-tracking branch 'upstream/main' into feat/issue-976-logout-token-invalidation

Author: No-bodyq

backend/src/auth/guards/roles.guard.spec.ts

@@ -0,0 +1,56 @@
+import { ExecutionContext, ForbiddenException } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { RolesGuard } from './roles.guard.js';
+import { AuthRole } from '../../common/enums/auth-role.enum.js';
+
+describe('RolesGuard', () => {
+  let guard: RolesGuard;
+  let reflector: Reflector;
+
+  const createContext = (roles?: string[]): ExecutionContext =>
+    ({
+      getHandler: () => ({}),
+      getClass: () => ({}),
+      switchToHttp: () => ({
+        getRequest: () => ({ user: roles ? { roles } : undefined }),
+      }),
+    }) as unknown as ExecutionContext;
+
+  beforeEach(() => {
+    reflector = new Reflector();
+    guard = new RolesGuard(reflector);
+  });
+
+  it('should allow access when no roles are required', () => {
+    jest.spyOn(reflector, 'getAllAndOverride').mockReturnValue(undefined);
+    expect(guard.canActivate(createContext())).toBe(true);
+  });
+
+  it('should allow access when user has a required role', () => {
+    jest
+      .spyOn(reflector, 'getAllAndOverride')
+      .mockReturnValue([AuthRole.ADMIN]);
+    expect(guard.canActivate(createContext([AuthRole.ADMIN]))).toBe(true);
+  });
+
+  it('should throw ForbiddenException with a clear message when user lacks the role', () => {
+    jest
+      .spyOn(reflector, 'getAllAndOverride')
+      .mockReturnValue([AuthRole.ADMIN]);
+    expect(() => guard.canActivate(createContext([AuthRole.MENTEE]))).toThrow(
+      ForbiddenException,
+    );
+    expect(() => guard.canActivate(createContext([AuthRole.MENTEE]))).toThrow(
+      /Requires one of the following roles: admin/,
+    );
+  });
+
+  it('should throw ForbiddenException when there is no authenticated user', () => {
+    jest
+      .spyOn(reflector, 'getAllAndOverride')
+      .mockReturnValue([AuthRole.ADMIN]);
+    expect(() => guard.canActivate(createContext())).toThrow(
+      ForbiddenException,
+    );
+  });
+});

backend/src/auth/guards/roles.guard.ts

@@ -1,4 +1,9 @@
-import { CanActivate, ExecutionContext, Injectable } from '@nestjs/common';
+import {
+  CanActivate,
+  ExecutionContext,
+  ForbiddenException,
+  Injectable,
+} from '@nestjs/common';
 import { Reflector } from '@nestjs/core';
 import { AuthRole } from '../../common/enums/auth-role.enum.js';
 import { ROLES_KEY } from '../decorators/roles.decorator.js';
@@ -20,6 +25,16 @@ export class RolesGuard implements CanActivate {
     const { user } = context
       .switchToHttp()
       .getRequest<{ user?: JwtAccessTokenPayload }>();
-    return requiredRoles.some((role) => user?.roles?.includes(role));
+    const hasRequiredRole = requiredRoles.some((role) =>
+      user?.roles?.includes(role),
+    );
+
+    if (!hasRequiredRole) {
+      throw new ForbiddenException(
+        `Requires one of the following roles: ${requiredRoles.join(', ')}`,
+      );
+    }
+
+    return true;
   }
 }

backend/src/database/migrations/1722000000001-AddRoleDescription.ts

@@ -0,0 +1,17 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+export class AddRoleDescription1722000000001 implements MigrationInterface {
+  name = 'AddRoleDescription1722000000001';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE "roles" ADD COLUMN "description" varchar
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE "roles" DROP COLUMN IF EXISTS "description"
+    `);
+  }
+}

backend/src/users/admin-roles.controller.spec.ts

@@ -0,0 +1,63 @@
+import { Test, TestingModule } from '@nestjs/testing';
+import { AdminRolesController } from './admin-roles.controller.js';
+import { UsersService } from './users.service.js';
+import { JwtAuthGuard } from '../auth/guards/jwt-auth.guard.js';
+import { RolesGuard } from '../auth/guards/roles.guard.js';
+import { AuthRole } from '../common/enums/auth-role.enum.js';
+
+describe('AdminRolesController', () => {
+  let controller: AdminRolesController;
+
+  const mockUsersService = {
+    assignRole: jest.fn(),
+    revokeRole: jest.fn(),
+  };
+
+  beforeEach(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      controllers: [AdminRolesController],
+      providers: [{ provide: UsersService, useValue: mockUsersService }],
+    })
+      .overrideGuard(JwtAuthGuard)
+      .useValue({ canActivate: () => true })
+      .overrideGuard(RolesGuard)
+      .useValue({ canActivate: () => true })
+      .compile();
+
+    controller = module.get<AdminRolesController>(AdminRolesController);
+  });
+
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  describe('assignRole', () => {
+    it('should delegate to usersService.assignRole', async () => {
+      mockUsersService.assignRole.mockResolvedValue({ id: 'user-1' });
+
+      const result = await controller.assignRole('user-1', {
+        role: AuthRole.MENTOR,
+      });
+
+      expect(mockUsersService.assignRole).toHaveBeenCalledWith(
+        'user-1',
+        AuthRole.MENTOR,
+      );
+      expect(result).toEqual({ id: 'user-1' });
+    });
+  });
+
+  describe('revokeRole', () => {
+    it('should delegate to usersService.revokeRole', async () => {
+      mockUsersService.revokeRole.mockResolvedValue({ id: 'user-1' });
+
+      const result = await controller.revokeRole('user-1', AuthRole.MENTOR);
+
+      expect(mockUsersService.revokeRole).toHaveBeenCalledWith(
+        'user-1',
+        AuthRole.MENTOR,
+      );
+      expect(result).toEqual({ id: 'user-1' });
+    });
+  });
+});

backend/src/users/admin-roles.controller.ts

@@ -0,0 +1,42 @@
+import {
+  Body,
+  Controller,
+  Delete,
+  HttpCode,
+  HttpStatus,
+  Param,
+  ParseEnumPipe,
+  Post,
+  UseGuards,
+} from '@nestjs/common';
+import { UsersService } from './users.service.js';
+import { AssignRoleDto } from './dto/assign-role.dto.js';
+import { JwtAuthGuard } from '../auth/guards/jwt-auth.guard.js';
+import { RolesGuard } from '../auth/guards/roles.guard.js';
+import { Roles } from '../auth/decorators/roles.decorator.js';
+import { AuthRole } from '../common/enums/auth-role.enum.js';
+
+@Controller('admin/users/:userId/roles')
+@UseGuards(JwtAuthGuard, RolesGuard)
+@Roles(AuthRole.ADMIN)
+export class AdminRolesController {
+  constructor(private readonly usersService: UsersService) {}
+
+  @Post()
+  @HttpCode(HttpStatus.CREATED)
+  async assignRole(
+    @Param('userId') userId: string,
+    @Body() dto: AssignRoleDto,
+  ) {
+    return this.usersService.assignRole(userId, dto.role);
+  }
+
+  @Delete(':role')
+  @HttpCode(HttpStatus.OK)
+  async revokeRole(
+    @Param('userId') userId: string,
+    @Param('role', new ParseEnumPipe(AuthRole)) role: AuthRole,
+  ) {
+    return this.usersService.revokeRole(userId, role);
+  }
+}

backend/src/users/dto/assign-role.dto.ts

@@ -0,0 +1,7 @@
+import { IsEnum } from 'class-validator';
+import { AuthRole } from '../../common/enums/auth-role.enum.js';
+
+export class AssignRoleDto {
+  @IsEnum(AuthRole)
+  role: AuthRole;
+}

backend/src/users/entities/role.entity.ts

@@ -16,6 +16,9 @@ export class Role {
   @Column({ type: 'enum', enum: AuthRole })
   name: AuthRole;
 
+  @Column({ type: 'varchar', nullable: true })
+  description: string | null;
+
   @ManyToOne(() => User, (user) => user.roles, { onDelete: 'CASCADE' })
   user: User;
 

backend/src/users/users.module.ts

@@ -3,6 +3,7 @@ import { TypeOrmModule } from '@nestjs/typeorm';
 import { JwtModule } from '@nestjs/jwt';
 import { ConfigModule } from '@nestjs/config';
 import { UsersController } from './users.controller.js';
+import { AdminRolesController } from './admin-roles.controller.js';
 import { ProfilesController } from './profiles.controller.js';
 import { UsersService } from './users.service.js';
 import { AvatarController } from './avatar.controller.js';
@@ -34,7 +35,12 @@ import { ProfileCompletenessService } from './profile-completeness.service.js';
     StorageModule,
     AvailabilityModule,
   ],
-  controllers: [UsersController, ProfilesController, AvatarController],
+  controllers: [
+    UsersController,
+    AdminRolesController,
+    ProfilesController,
+    AvatarController,
+  ],
   providers: [
     UsersService,
     JwtAuthGuard,

backend/src/users/users.service.spec.ts

@@ -21,12 +21,14 @@ describe('UsersService', () => {
     findOne: jest.fn(),
     create: jest.fn(),
     save: jest.fn(),
+    increment: jest.fn(),
     findAndCount: jest.fn(),
   };
 
   const mockRoleRepo = {
     create: jest.fn(),
     save: jest.fn(),
+    delete: jest.fn(),
   };
 
   const mockMentorProfileRepo = {
@@ -387,6 +389,98 @@ describe('UsersService', () => {
     });
   });
 
+  describe('createUser', () => {
+    it('should create a user with a default mentee role', async () => {
+      const createdUser = { ...mockUser, id: 'user-2' };
+      mockUserRepo.create.mockReturnValue(createdUser);
+      mockUserRepo.save.mockResolvedValue(createdUser);
+      mockRoleRepo.create.mockReturnValue({
+        name: AuthRole.MENTEE,
+        user: createdUser,
+      });
+      mockRoleRepo.save.mockResolvedValue({});
+      mockUserRepo.findOne.mockResolvedValue({
+        ...createdUser,
+        roles: [{ name: AuthRole.MENTEE }],
+      });
+
+      const result = await service.createUser('new-wallet');
+
+      expect(mockUserRepo.create).toHaveBeenCalledWith({
+        walletAddress: 'new-wallet',
+      });
+      expect(mockRoleRepo.create).toHaveBeenCalledWith({
+        name: AuthRole.MENTEE,
+        user: createdUser,
+      });
+      expect(result.roles).toEqual([{ name: AuthRole.MENTEE }]);
+    });
+  });
+
+  describe('assignRole', () => {
+    it('should assign a new role and bump the token version', async () => {
+      mockUserRepo.findOne.mockResolvedValue({ ...mockUser, roles: [] });
+      mockRoleRepo.create.mockReturnValue({
+        name: AuthRole.ADMIN,
+        user: mockUser,
+      });
+      mockRoleRepo.save.mockResolvedValue({});
+      mockUserRepo.increment.mockResolvedValue({});
+
+      await service.assignRole('user-1', AuthRole.ADMIN);
+
+      expect(mockRoleRepo.create).toHaveBeenCalledWith({
+        name: AuthRole.ADMIN,
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        user: expect.objectContaining({ id: 'user-1' }),
+      });
+      expect(mockUserRepo.increment).toHaveBeenCalledWith(
+        { id: 'user-1' },
+        'tokenVersion',
+        1,
+      );
+    });
+
+    it('should throw ConflictException when user already has the role', async () => {
+      mockUserRepo.findOne.mockResolvedValue({
+        ...mockUser,
+        roles: [{ name: AuthRole.ADMIN }],
+      });
+
+      await expect(
+        service.assignRole('user-1', AuthRole.ADMIN),
+      ).rejects.toThrow(ConflictException);
+    });
+  });
+
+  describe('revokeRole', () => {
+    it('should revoke an existing role and bump the token version', async () => {
+      mockUserRepo.findOne.mockResolvedValue({
+        ...mockUser,
+        roles: [{ id: 'role-1', name: AuthRole.ADMIN }],
+      });
+      mockRoleRepo.delete.mockResolvedValue({});
+      mockUserRepo.increment.mockResolvedValue({});
+
+      await service.revokeRole('user-1', AuthRole.ADMIN);
+
+      expect(mockRoleRepo.delete).toHaveBeenCalledWith({ id: 'role-1' });
+      expect(mockUserRepo.increment).toHaveBeenCalledWith(
+        { id: 'user-1' },
+        'tokenVersion',
+        1,
+      );
+    });
+
+    it('should throw NotFoundException when user does not have the role', async () => {
+      mockUserRepo.findOne.mockResolvedValue({ ...mockUser, roles: [] });
+
+      await expect(
+        service.revokeRole('user-1', AuthRole.ADMIN),
+      ).rejects.toThrow(NotFoundException);
+    });
+  });
+
   describe('updateUser', () => {
     it('should update user fields and save', async () => {
       const existingUser = { ...mockUser, email: undefined };
@@ -428,6 +522,25 @@ describe('UsersService', () => {
     });
   });
 
+  describe('getTokenVersion', () => {
+    it('should return the token version for an existing user', async () => {
+      mockUserRepo.findOne.mockResolvedValue({
+        id: 'user-1',
+        tokenVersion: 3,
+      });
+
+      const result = await service.getTokenVersion('user-1');
+      expect(result).toBe(3);
+    });
+
+    it('should return null when the user does not exist', async () => {
+      mockUserRepo.findOne.mockResolvedValue(null);
+
+      const result = await service.getTokenVersion('missing');
+      expect(result).toBeNull();
+    });
+  });
+
   describe('deactivateUser', () => {
     it('should set status to deleted and save', async () => {
       const existingUser = { ...mockUser, status: UserStatus.ACTIVE };