@hed-hog/core 0.0.387 → 0.0.393

package/src/impersonation/impersonation.controller.ts

@@ -0,0 +1,109 @@
+import { Impersonation, ImpersonationContext, NoRole, Public, Role, User } from '@hed-hog/api';
+import { Locale } from '@hed-hog/api-locale';
+import { Pagination } from '@hed-hog/api-pagination';
+import {
+  Body,
+  Controller,
+  Get,
+  Headers,
+  Inject,
+  Ip,
+  Post,
+  Query,
+  UseGuards,
+  forwardRef,
+} from '@nestjs/common';
+import { Throttle, ThrottlerGuard } from '@nestjs/throttler';
+import { RedeemImpersonationDTO } from './dto/redeem-impersonation.dto';
+import { StartImpersonationDTO } from './dto/start-impersonation.dto';
+import { ImpersonationService } from './impersonation.service';
+
+/**
+ * Quem chama o quê:
+ * - `start` e `history`: a aba do OPERADOR, com papel administrativo;
+ * - `redeem`: a aba NOVA, que ainda nao tem sessao nenhuma — por isso @Public();
+ * - `stop` e `session`: a propria sessao SIMULADA, cujos papeis sao os do alvo
+ *   (um aluno, por exemplo) — por isso @NoRole(), e nao @Role().
+ */
+@Role()
+@Controller('impersonation')
+export class ImpersonationController {
+  constructor(
+    @Inject(forwardRef(() => ImpersonationService))
+    private readonly service: ImpersonationService,
+  ) {}
+
+  @UseGuards(ThrottlerGuard)
+  @Throttle({ default: { limit: 10, ttl: 60_000 } })
+  @Post('start')
+  async start(
+    @Locale() locale: string,
+    @User() operator,
+    @Impersonation() impersonation: ImpersonationContext,
+    @Body() body: StartImpersonationDTO & { targetUserId: number },
+    @Ip() ipAddress: string,
+    @Headers('user-agent') userAgent: string,
+  ) {
+    return this.service.start({
+      locale,
+      operatorUserId: operator.id,
+      targetUserId: Number(body.targetUserId),
+      app: body.app,
+      reason: body.reason,
+      isImpersonating: impersonation.active,
+      ipAddress,
+      userAgent,
+    });
+  }
+
+  @Public()
+  @UseGuards(ThrottlerGuard)
+  @Throttle({ default: { limit: 20, ttl: 60_000 } })
+  @Post('redeem')
+  async redeem(
+    @Locale() locale: string,
+    @Body() { code }: RedeemImpersonationDTO,
+    @Ip() ipAddress: string,
+    @Headers('user-agent') userAgent: string,
+  ) {
+    return this.service.redeem({ locale, code, ipAddress, userAgent });
+  }
+
+  @NoRole()
+  @Post('stop')
+  async stop(
+    @User() target,
+    @Impersonation() impersonation: ImpersonationContext,
+    @Ip() ipAddress: string,
+  ) {
+    return this.service.stop({
+      sessionId: impersonation.sessionId,
+      targetUserId: target.id,
+      operatorUserId: impersonation.operatorUserId,
+      ipAddress,
+    });
+  }
+
+  @NoRole()
+  @Get('session')
+  async session(@Impersonation() impersonation: ImpersonationContext) {
+    return this.service.currentSession(
+      impersonation.active ? impersonation.sessionId : null,
+    );
+  }
+
+  @Get('apps')
+  async apps() {
+    return { apps: await this.service.listRedeemableApps() };
+  }
+
+  @Get('history')
+  async history(
+    @Pagination() paginationParams,
+    @Query('targetUserId') targetUserId?: string,
+  ) {
+    return this.service.history(paginationParams, {
+      targetUserId: targetUserId ? Number(targetUserId) : undefined,
+    });
+  }
+}

package/src/impersonation/impersonation.module.ts

@@ -0,0 +1,31 @@
+import { PaginationModule } from '@hed-hog/api-pagination';
+import { PrismaModule } from '@hed-hog/api-prisma';
+import { Module, forwardRef } from '@nestjs/common';
+import { SecurityModule } from '../security/security.module';
+import { SessionModule } from '../session/session.module';
+import { SettingModule } from '../setting/setting.module';
+import { TokenModule } from '../token/token.module';
+import { UserModule } from '../user/user.module';
+import { ImpersonationController } from './impersonation.controller';
+import { ImpersonationService } from './impersonation.service';
+
+/**
+ * Modulo proprio, e nao mais um endpoint no AuthModule, porque a simulacao tem
+ * um ciclo de vida completo (emitir → resgatar → encerrar → auditar) e uma
+ * denylist de rotas que o RoleGuard consulta.
+ */
+@Module({
+  imports: [
+    forwardRef(() => PrismaModule),
+    forwardRef(() => SecurityModule),
+    forwardRef(() => SettingModule),
+    forwardRef(() => TokenModule),
+    forwardRef(() => SessionModule),
+    forwardRef(() => UserModule),
+    forwardRef(() => PaginationModule),
+  ],
+  controllers: [ImpersonationController],
+  providers: [ImpersonationService],
+  exports: [ImpersonationService],
+})
+export class ImpersonationModule {}

package/src/impersonation/impersonation.service.spec.ts

@@ -0,0 +1,427 @@
+import { beforeEach, describe, expect, it, jest } from '@jest/globals';
+import {
+  BadRequestException,
+  ForbiddenException,
+  NotFoundException,
+} from '@nestjs/common';
+import { createHash, randomBytes } from 'crypto';
+
+// Mocka o MESMO modulo de onde o service importa (@hed-hog/api-prisma). Mockar
+// '@prisma/client' deixaria o teste verde com um import que quebra em runtime.
+jest.mock('@hed-hog/api-prisma', () => ({
+  PrismaService: class {},
+  Prisma: {
+    sql: (strings: TemplateStringsArray, ...values: unknown[]) => ({
+      strings: [...strings],
+      values,
+    }),
+  },
+}));
+
+// eslint-disable-next-line import/first
+import { ImpersonationService } from './impersonation.service';
+
+const OPERATOR_ID = 7;
+const TARGET_ID = 42;
+
+const sha256b64url = (value: string) =>
+  createHash('sha256').update(value).digest('base64url');
+
+const makeDeps = () => {
+  const prisma = {
+    impersonation_grant: {
+      create: jest.fn(async () => ({ id: 100 })),
+      update: jest.fn(async () => ({})),
+      updateMany: jest.fn(async () => ({ count: 1 })),
+      deleteMany: jest.fn(async () => ({ count: 0 })),
+    },
+    user_session: {
+      updateMany: jest.fn(async () => ({ count: 1 })),
+      findUnique: jest.fn(async () => null),
+    },
+    user: {
+      findUnique: jest.fn(async () => ({
+        id: TARGET_ID,
+        deactivated_at: null,
+        role_user: [{ role: { slug: 'user' } }],
+      })),
+      findMany: jest.fn(async () => [
+        { id: OPERATOR_ID, name: 'Operadora' },
+        { id: TARGET_ID, name: 'Aluna' },
+      ]),
+    },
+    $queryRaw: jest.fn(),
+  };
+
+  // Cripto real: e justamente o que estes testes precisam exercitar.
+  const security = {
+    randomOpaque: (size = 32) => randomBytes(size).toString('base64url'),
+    hashSha256: (value: string) => sha256b64url(value),
+  };
+
+  const setting = {
+    getSettingValues: jest.fn(async () => ({
+      'app-urls': ['admin=https://admin.example.com', 'class=https://class.example.com/'],
+      'impersonation-session-minutes': 30,
+    })),
+  };
+
+  const token = {
+    createAccessToken: jest.fn(async () => 'ACCESS'),
+  };
+
+  const session = {
+    createImpersonation: jest.fn(async () => ({
+      id: 555,
+      expires_at: new Date('2026-08-22T12:30:00.000Z'),
+    })),
+  };
+
+  const user = {
+    recordUserChange: jest.fn(async () => ({})),
+    registerUserActivity: jest.fn(async () => ({})),
+  };
+
+  const pagination = { paginatePrismaModel: jest.fn() };
+
+  return { prisma, security, setting, token, session, user, pagination };
+};
+
+const makeService = (deps: ReturnType<typeof makeDeps>) =>
+  new ImpersonationService(
+    deps.prisma as never,
+    deps.security as never,
+    deps.setting as never,
+    deps.token as never,
+    deps.session as never,
+    deps.user as never,
+    deps.pagination as never,
+  );
+
+const startParams = (overrides: Record<string, unknown> = {}) => ({
+  locale: 'pt',
+  operatorUserId: OPERATOR_ID,
+  targetUserId: TARGET_ID,
+  app: 'class',
+  reason: 'chamado 123',
+  isImpersonating: false,
+  ipAddress: '1.2.3.4',
+  userAgent: 'UA',
+  ...overrides,
+});
+
+describe('ImpersonationService', () => {
+  let deps: ReturnType<typeof makeDeps>;
+  let service: ImpersonationService;
+
+  beforeEach(() => {
+    deps = makeDeps();
+    service = makeService(deps);
+  });
+
+  describe('start', () => {
+    it('recusa simulação aninhada', async () => {
+      await expect(
+        service.start(startParams({ isImpersonating: true }) as never),
+      ).rejects.toThrow(ForbiddenException);
+      expect(deps.prisma.impersonation_grant.create).not.toHaveBeenCalled();
+    });
+
+    it('recusa auto-simulação', async () => {
+      await expect(
+        service.start(startParams({ targetUserId: OPERATOR_ID }) as never),
+      ).rejects.toThrow(BadRequestException);
+    });
+
+    it('recusa alvo inexistente', async () => {
+      deps.prisma.user.findUnique.mockResolvedValue(null as never);
+      await expect(service.start(startParams() as never)).rejects.toThrow(
+        NotFoundException,
+      );
+    });
+
+    it('recusa alvo desativado', async () => {
+      deps.prisma.user.findUnique.mockResolvedValue({
+        id: TARGET_ID,
+        deactivated_at: new Date(),
+        role_user: [],
+      } as never);
+      await expect(service.start(startParams() as never)).rejects.toThrow(
+        BadRequestException,
+      );
+    });
+
+    it('recusa alvo administrador', async () => {
+      deps.prisma.user.findUnique.mockResolvedValue({
+        id: TARGET_ID,
+        deactivated_at: null,
+        role_user: [{ role: { slug: 'admin' } }],
+      } as never);
+      await expect(service.start(startParams() as never)).rejects.toThrow(
+        ForbiddenException,
+      );
+    });
+
+    it('recusa alvo que detém o próprio papel de simulação', async () => {
+      deps.prisma.user.findUnique.mockResolvedValue({
+        id: TARGET_ID,
+        deactivated_at: null,
+        role_user: [{ role: { slug: 'admin-impersonation' } }],
+      } as never);
+      await expect(service.start(startParams() as never)).rejects.toThrow(
+        ForbiddenException,
+      );
+    });
+
+    it('PERMITE alvo suspenso — é o chamado de suporte mais comum', async () => {
+      deps.prisma.user.findUnique.mockResolvedValue({
+        id: TARGET_ID,
+        deactivated_at: null,
+        suspended_until: new Date('2030-01-01'),
+        role_user: [{ role: { slug: 'user' } }],
+      } as never);
+
+      await expect(service.start(startParams() as never)).resolves.toMatchObject({
+        url: expect.stringContaining('https://class.example.com/simulacao#code='),
+      });
+    });
+
+    it('recusa app sem tela de resgate', async () => {
+      await expect(
+        service.start(startParams({ app: 'training' }) as never),
+      ).rejects.toThrow(BadRequestException);
+    });
+
+    it('recusa app sem URL configurada em app-urls', async () => {
+      await expect(
+        service.start(startParams({ app: 'partners' }) as never),
+      ).rejects.toThrow(BadRequestException);
+    });
+
+    it('persiste apenas o hash do código, nunca o código em claro', async () => {
+      const result = await service.start(startParams() as never);
+
+      const code = result.url.split('#code=')[1];
+      const persisted = (deps.prisma.impersonation_grant.create as any).mock
+        .calls[0][0].data;
+
+      expect(code).toBeTruthy();
+      expect(persisted.code_hash).toBe(sha256b64url(code));
+      expect(persisted.code_hash).not.toBe(code);
+      expect(JSON.stringify(persisted)).not.toContain(code);
+    });
+
+    it('entrega o código no fragment da URL, nunca na query string', async () => {
+      const { url } = await service.start(startParams() as never);
+
+      expect(url).toContain('/simulacao#code=');
+      expect(url.split('#')[0]).not.toContain('code');
+    });
+
+    it('audita a TENTATIVA, mesmo antes de qualquer resgate', async () => {
+      await service.start(startParams() as never);
+
+      expect(deps.user.recordUserChange).toHaveBeenCalledWith(
+        expect.objectContaining({
+          targetUserId: TARGET_ID,
+          actorUserId: OPERATOR_ID,
+          action: 'impersonation_requested',
+          ipAddress: '1.2.3.4',
+        }),
+      );
+    });
+  });
+
+  describe('redeem', () => {
+    const redeemParams = {
+      locale: 'pt',
+      code: 'x'.repeat(32),
+      ipAddress: '9.9.9.9',
+      userAgent: 'UA-destino',
+    };
+
+    const grantRow = {
+      id: 100,
+      impersonator_user_id: OPERATOR_ID,
+      target_user_id: TARGET_ID,
+      app: 'class',
+      reason: 'chamado 123',
+    };
+
+    it('recusa código inválido, expirado ou já usado com a mesma mensagem', async () => {
+      deps.prisma.$queryRaw.mockResolvedValue([] as never);
+
+      await expect(service.redeem(redeemParams)).rejects.toThrow(BadRequestException);
+      expect(deps.session.createImpersonation).not.toHaveBeenCalled();
+    });
+
+    it('é de uso único: o segundo resgate não encontra mais a concessão', async () => {
+      deps.prisma.$queryRaw
+        .mockResolvedValueOnce([grantRow] as never)
+        .mockResolvedValueOnce([] as never);
+
+      await expect(service.redeem(redeemParams)).resolves.toMatchObject({
+        accessToken: 'ACCESS',
+      });
+      await expect(service.redeem(redeemParams)).rejects.toThrow(BadRequestException);
+    });
+
+    it('revalida o alvo dentro da janela do código', async () => {
+      deps.prisma.$queryRaw.mockResolvedValue([grantRow] as never);
+      deps.prisma.user.findUnique.mockResolvedValue({
+        id: TARGET_ID,
+        deactivated_at: new Date(),
+        role_user: [],
+      } as never);
+
+      await expect(service.redeem(redeemParams)).rejects.toThrow(BadRequestException);
+      expect(deps.session.createImpersonation).not.toHaveBeenCalled();
+    });
+
+    it('assina o token com sub=alvo, act=operador e expiração igual à janela', async () => {
+      deps.prisma.$queryRaw.mockResolvedValue([grantRow] as never);
+
+      await service.redeem(redeemParams);
+
+      expect(deps.token.createAccessToken).toHaveBeenCalledWith(
+        { sub: TARGET_ID, sessionId: 555, act: OPERATOR_ID, imp: true },
+        { expiresIn: 30 * 60 },
+      );
+    });
+
+    it('registra a atividade nos dois lados e o change log', async () => {
+      deps.prisma.$queryRaw.mockResolvedValue([grantRow] as never);
+
+      await service.redeem(redeemParams);
+
+      expect(deps.user.registerUserActivity).toHaveBeenCalledWith(
+        TARGET_ID,
+        'impersonationStarted',
+        OPERATOR_ID,
+      );
+      expect(deps.user.registerUserActivity).toHaveBeenCalledWith(
+        OPERATOR_ID,
+        'impersonationPerformed',
+        TARGET_ID,
+      );
+      expect(deps.user.recordUserChange).toHaveBeenCalledWith(
+        expect.objectContaining({ action: 'impersonation_started' }),
+      );
+    });
+
+    it('não devolve refresh token nem qualquer segredo renovável', async () => {
+      deps.prisma.$queryRaw.mockResolvedValue([grantRow] as never);
+
+      const result = await service.redeem(redeemParams);
+
+      expect(result).not.toHaveProperty('refreshToken');
+      expect(JSON.stringify(result)).not.toContain('refresh');
+    });
+  });
+
+  describe('stop', () => {
+    it('só revoga sessão que é de fato simulada', async () => {
+      await service.stop({
+        sessionId: 555,
+        targetUserId: TARGET_ID,
+        operatorUserId: OPERATOR_ID,
+        ipAddress: '9.9.9.9',
+      });
+
+      expect(deps.prisma.user_session.updateMany).toHaveBeenCalledWith({
+        where: {
+          id: 555,
+          revoked_at: null,
+          impersonator_user_id: { not: null },
+        },
+        data: { revoked_at: expect.any(Date) },
+      });
+    });
+
+    it('fecha a concessão e audita nos dois lados', async () => {
+      await service.stop({
+        sessionId: 555,
+        targetUserId: TARGET_ID,
+        operatorUserId: OPERATOR_ID,
+      });
+
+      expect(deps.prisma.impersonation_grant.updateMany).toHaveBeenCalledWith({
+        where: { session_id: 555, ended_at: null },
+        data: { ended_at: expect.any(Date) },
+      });
+      expect(deps.user.registerUserActivity).toHaveBeenCalledWith(
+        TARGET_ID,
+        'impersonationEnded',
+        OPERATOR_ID,
+      );
+      expect(deps.user.recordUserChange).toHaveBeenCalledWith(
+        expect.objectContaining({ action: 'impersonation_ended' }),
+      );
+    });
+
+    it('não faz nada sem sessão de simulação no contexto', async () => {
+      const result = await service.stop({
+        sessionId: null,
+        targetUserId: TARGET_ID,
+        operatorUserId: null,
+      });
+
+      expect(result).toEqual({ ended: false });
+      expect(deps.prisma.user_session.updateMany).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('currentSession', () => {
+    it('devolve inativo para sessão normal', async () => {
+      deps.prisma.user_session.findUnique.mockResolvedValue({
+        user_id: TARGET_ID,
+        impersonator_user_id: null,
+        impersonation_reason: null,
+        expires_at: new Date(),
+        revoked_at: null,
+      } as never);
+
+      await expect(service.currentSession(555)).resolves.toEqual({ active: false });
+    });
+
+    it('devolve inativo para sessão simulada já revogada', async () => {
+      deps.prisma.user_session.findUnique.mockResolvedValue({
+        user_id: TARGET_ID,
+        impersonator_user_id: OPERATOR_ID,
+        impersonation_reason: null,
+        expires_at: new Date(),
+        revoked_at: new Date(),
+      } as never);
+
+      await expect(service.currentSession(555)).resolves.toEqual({ active: false });
+    });
+
+    it('descreve a simulação ativa com operador e alvo', async () => {
+      deps.prisma.user_session.findUnique.mockResolvedValue({
+        user_id: TARGET_ID,
+        impersonator_user_id: OPERATOR_ID,
+        impersonation_reason: 'chamado 123',
+        expires_at: new Date('2026-08-22T12:30:00.000Z'),
+        revoked_at: null,
+      } as never);
+
+      await expect(service.currentSession(555)).resolves.toEqual({
+        active: true,
+        operator: { id: OPERATOR_ID, name: 'Operadora' },
+        target: { id: TARGET_ID, name: 'Aluna' },
+        reason: 'chamado 123',
+        expiresAt: '2026-08-22T12:30:00.000Z',
+      });
+    });
+  });
+
+  describe('listRedeemableApps', () => {
+    it('devolve só os apps configurados que têm tela de resgate', async () => {
+      await expect(service.listRedeemableApps()).resolves.toEqual([
+        { key: 'admin', url: 'https://admin.example.com' },
+        // A barra final de app-urls e normalizada.
+        { key: 'class', url: 'https://class.example.com' },
+      ]);
+    });
+  });
+});