@hed-hog/core 0.0.390 → 0.0.393

package/src/impersonation/impersonation.service.ts

@@ -0,0 +1,577 @@
+// `Prisma` vem de @hed-hog/api-prisma, nao de '@prisma/client': o tsconfig do
+// monorepo mapeia '@prisma/client' para o client gerado, que nao expoe
+// `Prisma.sql`. E a convencao do repo inteiro.
+import { Prisma, PrismaService } from '@hed-hog/api-prisma';
+import { getLocaleText } from '@hed-hog/api-locale';
+import { PaginationDTO, PaginationService } from '@hed-hog/api-pagination';
+import {
+  BadRequestException,
+  ForbiddenException,
+  Inject,
+  Injectable,
+  Logger,
+  NotFoundException,
+  forwardRef,
+} from '@nestjs/common';
+import { Cron, CronExpression } from '@nestjs/schedule';
+import { SecurityService } from '../security/security.service';
+import { SessionService } from '../session/session.service';
+import { SettingService } from '../setting/setting.service';
+import { TokenService } from '../token/token.service';
+import { UserService } from '../user/user.service';
+
+type StartParams = {
+  locale: string;
+  operatorUserId: number;
+  targetUserId: number;
+  app: string;
+  reason?: string | null;
+  isImpersonating: boolean;
+  ipAddress: string;
+  userAgent: string;
+};
+
+type RedeemParams = {
+  locale: string;
+  code: string;
+  ipAddress: string;
+  userAgent: string;
+};
+
+type GrantRow = {
+  id: number;
+  impersonator_user_id: number;
+  target_user_id: number;
+  app: string;
+  reason: string | null;
+};
+
+/**
+ * Simulacao de acesso: um operador ve o sistema como outro usuario, por uma
+ * janela curta, com tudo marcado como simulado.
+ *
+ * DESENHO EM DUAS ETAPAS. `start` nao devolve token nenhum — devolve um codigo
+ * de uso unico com TTL de 60s, que viaja no FRAGMENT da URL da aba nova
+ * (fragment nao chega ao servidor, entao nao entra em log de acesso nem em
+ * Referer). Quem cria a sessao e o `redeem`, na aba de destino. Assim a sessao
+ * do operador nunca e tocada: nenhum cookie `rt` e emitido, nenhum
+ * `localStorage` compartilhado e sobrescrito.
+ *
+ * A SESSAO E NAO RENOVAVEL POR CONSTRUCAO. `SessionService.createImpersonation`
+ * gera o token opaco e o descarta, entao nao existe refresh token para ela em
+ * lugar nenhum — e nao apenas "e proibido renovar".
+ */
+@Injectable()
+export class ImpersonationService {
+  private readonly logger = new Logger(ImpersonationService.name);
+
+  /** Curto: o codigo so precisa sobreviver ao carregamento da aba nova. */
+  private readonly codeTtlMs = 60_000;
+
+  /** Caminho da tela de resgate, igual nos tres apps. */
+  static readonly REDEEM_PATH = '/simulacao';
+
+  /**
+   * Simular quem ja e administrador nao ajuda em nada no suporte e transformaria
+   * o papel `admin-impersonation` num atalho para virar `admin`.
+   */
+  private static readonly BLOCKED_TARGET_ROLES = ['admin', 'admin-impersonation'];
+
+  /**
+   * Apps com tela de resgate. `training` tem autenticacao propria e nao usa o
+   * @hed-hog/next-app-provider, entao ficou fora desta fase.
+   */
+  private static readonly REDEEMABLE_APPS = ['admin', 'class', 'partners'];
+
+  constructor(
+    @Inject(forwardRef(() => PrismaService))
+    private readonly prisma: PrismaService,
+    @Inject(forwardRef(() => SecurityService))
+    private readonly security: SecurityService,
+    @Inject(forwardRef(() => SettingService))
+    private readonly setting: SettingService,
+    @Inject(forwardRef(() => TokenService))
+    private readonly token: TokenService,
+    @Inject(forwardRef(() => SessionService))
+    private readonly session: SessionService,
+    @Inject(forwardRef(() => UserService))
+    private readonly user: UserService,
+    @Inject(forwardRef(() => PaginationService))
+    private readonly pagination: PaginationService,
+  ) {}
+
+  // ==========================================
+  // Etapa 1 — emissao do codigo
+  // ==========================================
+
+  async start(params: StartParams) {
+    const { locale, operatorUserId, targetUserId } = params;
+
+    if (params.isImpersonating) {
+      throw new ForbiddenException(
+        getLocaleText(
+          'impersonation.nested',
+          locale,
+          'You cannot start an access simulation from inside another one.',
+        ),
+      );
+    }
+
+    if (operatorUserId === targetUserId) {
+      throw new BadRequestException(
+        getLocaleText(
+          'impersonation.self',
+          locale,
+          'You cannot simulate your own access.',
+        ),
+      );
+    }
+
+    await this.assertTargetIsEligible(locale, targetUserId);
+
+    const origin = await this.resolveAppOrigin(locale, params.app);
+
+    const code = this.security.randomOpaque(32);
+    const codeHash = this.security.hashSha256(code);
+    const reason = params.reason?.trim() ? params.reason.trim().slice(0, 255) : null;
+    const expiresAt = new Date(Date.now() + this.codeTtlMs);
+
+    const grant = await this.prisma.impersonation_grant.create({
+      data: {
+        code_hash: codeHash,
+        impersonator_user_id: operatorUserId,
+        target_user_id: targetUserId,
+        app: params.app,
+        reason,
+        issued_ip: params.ipAddress || null,
+        issued_user_agent: params.userAgent || null,
+        expires_at: expiresAt,
+      },
+      select: { id: true },
+    });
+
+    // A TENTATIVA ja vira auditoria, mesmo que o codigo nunca seja resgatado —
+    // pedir acesso a conta de alguem e o evento relevante, nao so consumi-lo.
+    await this.user.recordUserChange({
+      targetUserId,
+      actorUserId: operatorUserId,
+      action: 'impersonation_requested',
+      summary: `app=${params.app} grant=#${grant.id}${reason ? ` reason=${reason}` : ''}`,
+      ipAddress: params.ipAddress || null,
+    });
+
+    this.logger.log(
+      `[Impersonation] grant=#${grant.id} operator=${operatorUserId} target=${targetUserId} app=${params.app} ip=${params.ipAddress}`,
+    );
+
+    return {
+      // O codigo vai no fragment: nunca chega ao servidor de destino, nao entra
+      // em access_log nem em Referer, e a tela de resgate o apaga com
+      // history.replaceState logo apos ler.
+      url: `${origin}${ImpersonationService.REDEEM_PATH}#code=${code}`,
+      expiresAt: expiresAt.toISOString(),
+    };
+  }
+
+  // ==========================================
+  // Etapa 2 — resgate na aba de destino
+  // ==========================================
+
+  async redeem(params: RedeemParams) {
+    const { locale } = params;
+    const codeHash = this.security.hashSha256(params.code ?? '');
+
+    // Consumo atomico: dois requests com o mesmo codigo — o caso de replay — so
+    // podem ter um vencedor, decidido pelo banco.
+    const rows = await this.prisma.$queryRaw<GrantRow[]>(
+      Prisma.sql`
+        UPDATE impersonation_grant
+        SET consumed_at = NOW(),
+            redeemed_ip = ${params.ipAddress || null},
+            redeemed_user_agent = ${params.userAgent || null}
+        WHERE code_hash = ${codeHash}
+          AND expires_at > NOW()
+          AND consumed_at IS NULL
+        RETURNING id, impersonator_user_id, target_user_id, app, reason
+      `,
+    );
+
+    const grant = rows[0];
+    if (!grant) {
+      // Uma mensagem so para todos os modos de falha (inexistente, expirado, ja
+      // usado): distingui-los entregaria um oraculo a quem tem so o codigo.
+      throw new BadRequestException(
+        getLocaleText(
+          'impersonation.invalidCode',
+          locale,
+          'Invalid, expired or already used simulation code.',
+        ),
+      );
+    }
+
+    // Revalida: o alvo pode ter virado admin ou sido desativado dentro dos 60s.
+    await this.assertTargetIsEligible(locale, grant.target_user_id);
+
+    const settings = await this.setting.getSettingValues(['impersonation-session-minutes']);
+    const minutes = Number(settings['impersonation-session-minutes']) || 30;
+
+    const session = await this.session.createImpersonation(
+      locale,
+      grant.target_user_id,
+      grant.impersonator_user_id,
+      params.ipAddress,
+      params.userAgent,
+      minutes,
+      grant.reason,
+    );
+
+    // `expiresIn` por chamada: o token precisa morrer junto com a sessao, nao
+    // aos 15 minutos globais do JwtModule (e nao ha refresh para renova-lo).
+    const accessToken = await this.token.createAccessToken(
+      {
+        sub: grant.target_user_id,
+        sessionId: session.id,
+        act: grant.impersonator_user_id,
+        imp: true,
+      },
+      { expiresIn: minutes * 60 },
+    );
+
+    await this.prisma.impersonation_grant.update({
+      where: { id: grant.id },
+      data: { session_id: session.id },
+    });
+
+    const [operator, target] = await this.getUserPair(
+      grant.impersonator_user_id,
+      grant.target_user_id,
+    );
+
+    await Promise.all([
+      this.user.registerUserActivity(
+        grant.target_user_id,
+        'impersonationStarted',
+        grant.impersonator_user_id,
+      ),
+      this.user.registerUserActivity(
+        grant.impersonator_user_id,
+        'impersonationPerformed',
+        grant.target_user_id,
+      ),
+      this.user.recordUserChange({
+        targetUserId: grant.target_user_id,
+        actorUserId: grant.impersonator_user_id,
+        action: 'impersonation_started',
+        summary: `app=${grant.app} session=#${session.id} expires=${session.expires_at.toISOString()}${grant.reason ? ` reason=${grant.reason}` : ''}`,
+        ipAddress: params.ipAddress || null,
+      }),
+    ]);
+
+    this.logger.log(
+      `[Impersonation] redeemed grant=#${grant.id} session=#${session.id} operator=${grant.impersonator_user_id} target=${grant.target_user_id} minutes=${minutes}`,
+    );
+
+    return {
+      accessToken,
+      expiresAt: session.expires_at.toISOString(),
+      sessionId: session.id,
+      app: grant.app,
+      operator,
+      target,
+    };
+  }
+
+  // ==========================================
+  // Encerrar
+  // ==========================================
+
+  /**
+   * Chamado pela propria sessao simulada, entao todos os identificadores vem do
+   * `request.auth` — nao ha parametro que permita encerrar sessao alheia.
+   */
+  async stop(params: {
+    sessionId: number | null;
+    targetUserId: number;
+    operatorUserId: number | null;
+    ipAddress?: string;
+  }) {
+    if (!params.sessionId || !params.operatorUserId) {
+      return { ended: false };
+    }
+
+    const revoked = await this.prisma.user_session.updateMany({
+      where: {
+        id: params.sessionId,
+        revoked_at: null,
+        impersonator_user_id: { not: null },
+      },
+      data: { revoked_at: new Date() },
+    });
+
+    await this.prisma.impersonation_grant.updateMany({
+      where: { session_id: params.sessionId, ended_at: null },
+      data: { ended_at: new Date() },
+    });
+
+    if (revoked.count > 0) {
+      await Promise.all([
+        this.user.registerUserActivity(
+          params.targetUserId,
+          'impersonationEnded',
+          params.operatorUserId,
+        ),
+        this.user.registerUserActivity(
+          params.operatorUserId,
+          'impersonationPerformedEnded',
+          params.targetUserId,
+        ),
+        this.user.recordUserChange({
+          targetUserId: params.targetUserId,
+          actorUserId: params.operatorUserId,
+          action: 'impersonation_ended',
+          summary: `session=#${params.sessionId}`,
+          ipAddress: params.ipAddress || null,
+        }),
+      ]);
+    }
+
+    this.logger.log(
+      `[Impersonation] stopped session=#${params.sessionId} operator=${params.operatorUserId} target=${params.targetUserId} revoked=${revoked.count}`,
+    );
+
+    return { ended: revoked.count > 0 };
+  }
+
+  // ==========================================
+  // Leitura
+  // ==========================================
+
+  /**
+   * Fonte de verdade do banner. A `sessionStorage` do cliente e so cache — e
+   * gravavel pelo proprio navegador, entao nao serve para decidir nada.
+   */
+  async currentSession(sessionId: number | null) {
+    if (!sessionId) {
+      return { active: false as const };
+    }
+
+    const session = await this.prisma.user_session.findUnique({
+      where: { id: sessionId },
+      select: {
+        user_id: true,
+        impersonator_user_id: true,
+        impersonation_reason: true,
+        expires_at: true,
+        revoked_at: true,
+      },
+    });
+
+    if (!session?.impersonator_user_id || session.revoked_at) {
+      return { active: false as const };
+    }
+
+    const [operator, target] = await this.getUserPair(
+      session.impersonator_user_id,
+      session.user_id,
+    );
+
+    return {
+      active: true as const,
+      operator,
+      target,
+      reason: session.impersonation_reason,
+      expiresAt: session.expires_at.toISOString(),
+    };
+  }
+
+  /** Apps que o operador pode escolher como destino. */
+  async listRedeemableApps() {
+    const settings = await this.setting.getSettingValues(['app-urls']);
+    const entries = this.parseAppUrls(settings['app-urls']);
+
+    return ImpersonationService.REDEEMABLE_APPS.filter((key) => entries.has(key)).map(
+      (key) => ({ key, url: entries.get(key)! }),
+    );
+  }
+
+  async history(paginationParams: PaginationDTO, filters: { targetUserId?: number }) {
+    const where: any = {};
+    if (filters.targetUserId) {
+      where.target_user_id = filters.targetUserId;
+    }
+
+    const paginated = await this.pagination.paginatePrismaModel(
+      this.prisma.impersonation_grant,
+      {
+        ...paginationParams,
+        sortField: (paginationParams as any)?.sortField || 'created_at',
+        sortOrder: (paginationParams as any)?.sortOrder || 'desc',
+        validSortFields: ['id', 'created_at', 'consumed_at', 'ended_at'],
+        where,
+      },
+    );
+
+    const rows = (paginated.data || []) as any[];
+    const ids = [
+      ...new Set(
+        rows.flatMap((row) => [row.impersonator_user_id, row.target_user_id]),
+      ),
+    ].filter((id): id is number => typeof id === 'number');
+
+    const users = ids.length
+      ? await this.prisma.user.findMany({
+          where: { id: { in: ids } },
+          select: { id: true, name: true },
+        })
+      : [];
+    const byId = new Map(users.map((user) => [user.id, user]));
+
+    return {
+      ...paginated,
+      data: rows.map((row) => ({
+        // `code_hash` nunca sai daqui.
+        id: row.id,
+        app: row.app,
+        reason: row.reason,
+        sessionId: row.session_id,
+        operator: byId.get(row.impersonator_user_id) ?? null,
+        target: byId.get(row.target_user_id) ?? null,
+        issuedIp: row.issued_ip,
+        redeemedIp: row.redeemed_ip,
+        consumedAt: row.consumed_at?.toISOString?.() ?? null,
+        endedAt: row.ended_at?.toISOString?.() ?? null,
+        expiresAt: row.expires_at?.toISOString?.() ?? null,
+        createdAt: row.created_at?.toISOString?.() ?? null,
+      })),
+    };
+  }
+
+  // ==========================================
+  // Manutencao
+  // ==========================================
+
+  /**
+   * Concessoes nao resgatadas viram lixo em 60s. As consumidas ficam: sao a
+   * trilha de auditoria.
+   */
+  @Cron(CronExpression.EVERY_DAY_AT_4AM)
+  async purgeExpired() {
+    const { count } = await this.prisma.impersonation_grant.deleteMany({
+      where: {
+        consumed_at: null,
+        expires_at: { lt: new Date(Date.now() - 24 * 60 * 60 * 1000) },
+      },
+    });
+
+    if (count > 0) {
+      this.logger.log(`[Impersonation] purged ${count} unredeemed grant(s)`);
+    }
+  }
+
+  // ==========================================
+  // Helpers
+  // ==========================================
+
+  private async assertTargetIsEligible(locale: string, targetUserId: number) {
+    const target = await this.prisma.user.findUnique({
+      where: { id: targetUserId },
+      select: {
+        id: true,
+        deactivated_at: true,
+        role_user: { select: { role: { select: { slug: true } } } },
+      },
+    });
+
+    if (!target) {
+      throw new NotFoundException(
+        getLocaleText('userNotFound', locale, 'User not found'),
+      );
+    }
+
+    // Conta excluida pelo proprio usuario: os identificadores ja foram
+    // anonimizados, entao nao ha o que simular.
+    if (target.deactivated_at) {
+      throw new BadRequestException(
+        getLocaleText(
+          'impersonation.deactivatedTarget',
+          locale,
+          'This account has been deactivated and cannot be simulated.',
+        ),
+      );
+    }
+
+    // Conta suspensa CONTINUA simulavel de proposito: "o usuario nao consegue
+    // entrar" e justamente o chamado de suporte mais comum.
+
+    const slugs = target.role_user.map((link) => link.role?.slug).filter(Boolean);
+    if (slugs.some((slug) => ImpersonationService.BLOCKED_TARGET_ROLES.includes(slug!))) {
+      throw new ForbiddenException(
+        getLocaleText(
+          'impersonation.privilegedTarget',
+          locale,
+          'Administrators cannot be simulated.',
+        ),
+      );
+    }
+  }
+
+  private async resolveAppOrigin(locale: string, app: string) {
+    if (!ImpersonationService.REDEEMABLE_APPS.includes(app)) {
+      throw new BadRequestException(
+        getLocaleText(
+          'impersonation.unknownApp',
+          locale,
+          'This application does not support access simulation.',
+        ),
+      );
+    }
+
+    const settings = await this.setting.getSettingValues(['app-urls']);
+    const origin = this.parseAppUrls(settings['app-urls']).get(app);
+
+    if (!origin) {
+      throw new BadRequestException(
+        getLocaleText(
+          'impersonation.appNotConfigured',
+          locale,
+          'This application has no URL configured in the app-urls setting.',
+        ),
+      );
+    }
+
+    return origin;
+  }
+
+  /**
+   * `app-urls` e uma lista de `chave=url`. Mesmo formato lido por
+   * `ChallengeService.resolveAppKeyFromOrigin` e `OAuthService`.
+   */
+  private parseAppUrls(value: unknown): Map<string, string> {
+    const entries = new Map<string, string>();
+    const list: string[] = Array.isArray(value) ? value : [];
+
+    for (const entry of list) {
+      const separatorIndex = entry.indexOf('=');
+      if (separatorIndex === -1) continue;
+
+      const key = entry.slice(0, separatorIndex).trim();
+      const url = entry.slice(separatorIndex + 1).trim().replace(/\/+$/, '');
+      if (key && url) entries.set(key, url);
+    }
+
+    return entries;
+  }
+
+  private async getUserPair(operatorId: number, targetId: number) {
+    const users = await this.prisma.user.findMany({
+      where: { id: { in: [operatorId, targetId] } },
+      select: { id: true, name: true },
+    });
+    const byId = new Map(users.map((user) => [user.id, user]));
+
+    return [
+      byId.get(operatorId) ?? { id: operatorId, name: '' },
+      byId.get(targetId) ?? { id: targetId, name: '' },
+    ];
+  }
+}

package/src/index.ts

@@ -49,6 +49,7 @@ export * from './file/file.service';
 
 export * from './pdf/pdf.module';
 export * from './pdf/pdf.service';
+export * from './setting/brand-asset.service';
 export * from './setting/setting.module';
 export * from './setting/setting.service';
 
@@ -65,12 +66,26 @@ export * from './ai-instruction/types/ai-instruction.types';
 
 export * from './app-command/app-command.module';
 export * from './app-command/app-command.registry';
+export * from './mail-delivery/mail-delivery.constants';
+export * from './mail-delivery/mail-delivery-provision.service';
+export * from './mail-delivery/mail-delivery.module';
+export * from './mail-delivery/mail-delivery.service';
+export * from './mail-delivery/ses-event.parser';
+export * from './mail-delivery/ses-webhook.service';
+export * from './mail-delivery/sns-message.util';
 export * from './webhook-integration/event-webhook.service';
 export * from './webhook-integration/integration-event-catalog.service';
 export * from './webhook-integration/webhook-integration.module';
 export * from './webhook-integration/webhook-integration.service';
 export * from './webhook-integration/webhook-protocol.registry';
 
+// Meeting Module (porta genérica de reuniões online)
+export * from './mailbox/mailbox.module';
+export * from './mailbox/mailbox-fetcher.registry';
+export * from './meeting/meeting.constants';
+export * from './meeting/meeting.module';
+export * from './meeting/meeting-provider.registry';
+
 // Integration Module
 export * from './integration/integration.module';
 export * from './integration/services/domain-event.publisher';
@@ -104,6 +119,9 @@ export * from './oauth/oauth-token-broker.service';
 
 // Utilities
 export * from './utils/locale-context';
+export * from './utils/geo-ip';
+export * from './utils/user-agent';
+export * from './utils/security-event-vars';
 
 
 // Notification Module
@@ -120,3 +138,6 @@ export * from './realtime/realtime.gateway';
 export * from './presence/presence.module';
 export * from './presence/presence.service';
 
+// Observability
+export * from './observability/monitored-cron';
+