@hed-hog/core 0.0.390 → 0.0.394

package/src/setting/setting.module.ts

@@ -4,6 +4,7 @@ import { PrismaModule } from '@hed-hog/api-prisma';
 import { Global, Module, forwardRef } from '@nestjs/common';
 import { AuthModule } from '../auth/auth.module';
 import { MailModule } from '../mail/mail.module';
+import { BrandAssetService } from './brand-asset.service';
 import { SettingsController } from './setting.controller';
 import { SettingService } from './setting.service';
 
@@ -17,7 +18,7 @@ import { SettingService } from './setting.service';
     forwardRef(() => MailModule),
   ],
   controllers: [SettingsController],
-  providers: [SettingService],
-  exports: [SettingService],
+  providers: [SettingService, BrandAssetService],
+  exports: [SettingService, BrandAssetService],
 })
 export class SettingModule { }

package/src/setting/setting.service.spec.ts

@@ -7,6 +7,7 @@ import {
   jest,
 } from '@jest/globals';
 import { BadRequestException } from '@nestjs/common';
+import { localeStorage } from '@hed-hog/api-locale';
 import { SettingService } from './setting.service';
 
 const makeDeps = () => {
@@ -16,7 +17,7 @@ const makeDeps = () => {
       findFirst: jest.fn(),
       findUnique: jest.fn(),
     },
-    setting_user: { findMany: jest.fn() },
+    setting_user: { findMany: jest.fn(), findFirst: jest.fn() },
     user: { findUnique: jest.fn() },
     $executeRawUnsafe: jest.fn().mockResolvedValue(undefined),
     $queryRawUnsafe: jest.fn().mockResolvedValue([]),
@@ -369,4 +370,81 @@ describe('SettingService', () => {
       ).resolves.toBeUndefined();
     });
   });
+
+  // Cadeia única de idioma do sistema: e-mail transacional e aviso de idioma de
+  // curso precisam responder a mesma pergunta do mesmo jeito.
+  describe('resolveUserLocale', () => {
+    const arrange = (deps: any, opts: { override?: string | null; system?: string } = {}) => {
+      deps.prisma.setting_user.findFirst.mockResolvedValue(
+        opts.override ? { value: opts.override } : null,
+      );
+      deps.prisma.setting.findMany.mockResolvedValue([
+        { id: 1, slug: 'language', value: opts.system ?? 'en', type: 'string', user_override: true },
+      ]);
+    };
+
+    it('a preferência do usuário vence tudo', async () => {
+      const { service, deps } = makeService();
+      arrange(deps, { override: 'pt', system: 'en' });
+
+      const result = await localeStorage.run({ locale: 'en', detected: true }, () =>
+        service.resolveUserLocale(42),
+      );
+
+      expect(result).toBe('pt');
+    });
+
+    it('normaliza a preferência gravada com região', async () => {
+      const { service, deps } = makeService();
+      arrange(deps, { override: 'pt-BR' });
+
+      await expect(service.resolveUserLocale(42)).resolves.toBe('pt');
+    });
+
+    it('sem preferência, usa o idioma que o cliente declarou', async () => {
+      const { service, deps } = makeService();
+      arrange(deps, { system: 'en' });
+
+      const result = await localeStorage.run({ locale: 'pt', detected: true }, () =>
+        service.resolveUserLocale(42),
+      );
+
+      expect(result).toBe('pt');
+    });
+
+    // O `en` default do middleware não pode passar por escolha do cliente e
+    // atropelar a setting do sistema.
+    it('ignora o locale do contexto quando o cliente não declarou idioma', async () => {
+      const { service, deps } = makeService();
+      arrange(deps, { system: 'pt' });
+
+      const result = await localeStorage.run({ locale: 'en', detected: false }, () =>
+        service.resolveUserLocale(42),
+      );
+
+      expect(result).toBe('pt');
+    });
+
+    it('cai na setting do sistema fora de qualquer requisição', async () => {
+      const { service, deps } = makeService();
+      arrange(deps, { system: 'pt' });
+
+      await expect(service.resolveUserLocale(42)).resolves.toBe('pt');
+    });
+
+    it('funciona sem usuário (destinatário que não tem conta)', async () => {
+      const { service, deps } = makeService();
+      arrange(deps, { system: 'pt' });
+
+      await expect(service.resolveUserLocale(null)).resolves.toBe('pt');
+      expect(deps.prisma.setting_user.findFirst).not.toHaveBeenCalled();
+    });
+
+    it('cai em "en" quando a consulta falha', async () => {
+      const { service, deps } = makeService();
+      deps.prisma.setting_user.findFirst.mockRejectedValue(new Error('db down'));
+
+      await expect(service.resolveUserLocale(42)).resolves.toBe('en');
+    });
+  });
 });

package/src/setting/setting.service.ts

@@ -1,5 +1,11 @@
 import { itemTranslations } from '@hed-hog/api';
-import { getLocaleText, LocaleService } from '@hed-hog/api-locale';
+import {
+  getLocaleFromContext,
+  getLocaleText,
+  isLocaleDetectedFromContext,
+  LocaleService,
+  normalizeLocaleCode,
+} from '@hed-hog/api-locale';
 import { PaginationDTO, PaginationService } from '@hed-hog/api-pagination';
 import { PrismaService, setting_type_0f055cd5ea_enum } from '@hed-hog/api-prisma';
 import {
@@ -499,6 +505,8 @@ export class SettingService implements OnModuleInit, OnModuleDestroy {
       'password-block-leaked',
       'mfa-email-code-length',
       'mcp-enabled',
+      'richtext-ai-enabled',
+      'richtext-ai-profile-id',
       'date-format',
       'time-format',
       'timezone',
@@ -1303,6 +1311,106 @@ export class SettingService implements OnModuleInit, OnModuleDestroy {
     });
   }
 
+  /**
+   * Le SO o override do usuario, sem cair para o valor global.
+   *
+   * `getSettingValues(slug, userId)` nao serve para isso: quando o usuario nao
+   * tem override ele devolve o valor global, indistinguivel de uma preferencia
+   * real. Quem precisa saber se o usuario *escolheu* algo - o idioma do e-mail
+   * e a gravacao unica no login - depende dessa diferenca.
+   */
+  async getUserSettingValue(
+    userId: number,
+    slug: string,
+  ): Promise<string | null> {
+    if (!userId) {
+      return null;
+    }
+
+    const settingUser = await this.prismaService.setting_user.findFirst({
+      where: {
+        user_id: userId,
+        setting: {
+          slug,
+          user_override: true,
+        },
+      },
+      select: {
+        value: true,
+      },
+    });
+
+    const value = String(settingUser?.value ?? '').trim();
+
+    return value || null;
+  }
+
+  /**
+   * Idioma efetivo de um usuario.
+   *
+   * Cadeia unica do sistema, para que e-mail, aviso de idioma de curso e
+   * qualquer outra decisao de idioma respondam a mesma pergunta do mesmo jeito:
+   *
+   *   1. preferencia gravada do usuario  - escolha explicita sempre vence;
+   *   2. idioma que o cliente declarou nesta requisicao;
+   *   3. setting global `language`;
+   *   4. `en`.
+   *
+   * O passo 2 exige que o cliente tenha REALMENTE declarado: o `en` que o
+   * middleware usa como default nao pode vencer a setting do sistema.
+   */
+  async resolveUserLocale(userId?: number | null): Promise<string> {
+    try {
+      if (userId) {
+        const preferred = normalizeLocaleCode(
+          await this.getUserSettingValue(userId, 'language'),
+        );
+
+        if (preferred) {
+          return preferred;
+        }
+      }
+
+      const fromRequest = normalizeLocaleCode(getLocaleFromContext());
+
+      if (fromRequest && isLocaleDetectedFromContext()) {
+        return fromRequest;
+      }
+
+      const settings = await this.getSettingValues(['language']);
+
+      return normalizeLocaleCode(settings?.['language']) ?? fromRequest ?? 'en';
+    } catch (error) {
+      this.logger.warn(`Could not resolve locale for user ${userId}: ${error}`);
+
+      return normalizeLocaleCode(getLocaleFromContext()) ?? 'en';
+    }
+  }
+
+  /**
+   * Valores aceitos por uma setting de combobox (`setting_list`).
+   *
+   * `setSettingUserValue` valida que a setting existe e permite override, mas
+   * nao valida o *valor*. Sem esta checagem, um navegador em `de-DE` gravaria
+   * `de` como idioma e todo e-mail seguinte procuraria um template que nao
+   * existe.
+   */
+  async getSettingListValues(slug: string): Promise<string[]> {
+    const setting = await this.prismaService.setting.findFirst({
+      where: { slug },
+      select: {
+        setting_list: {
+          select: { value: true },
+          orderBy: { order: 'asc' },
+        },
+      },
+    });
+
+    return (setting?.setting_list ?? [])
+      .map((item) => String(item?.value ?? '').trim())
+      .filter(Boolean);
+  }
+
   async getSettingValues(
     slug: string | string[],
     userId?: number,

package/src/token/token.service.spec.ts

@@ -7,6 +7,7 @@ import {
   jest,
 } from '@jest/globals';
 import {
+  BadRequestException,
   ForbiddenException,
   UnauthorizedException,
 } from '@nestjs/common';
@@ -279,6 +280,21 @@ describe('TokenService', () => {
       );
     });
 
+    it('createAccessToken repassa expiresIn por chamada (sessão simulada)', async () => {
+      const { service, deps } = makeService();
+      deps.jwt.signAsync.mockResolvedValue('signed');
+
+      await service.createAccessToken(
+        { sub: 42, sessionId: 555, act: 7, imp: true },
+        { expiresIn: 1800 },
+      );
+
+      expect(deps.jwt.signAsync).toHaveBeenCalledWith(
+        { sub: 42, sessionId: 555, act: 7, imp: true },
+        { secret: 'secret', expiresIn: 1800 },
+      );
+    });
+
     it('createOpaqueToken delega ao security', async () => {
       const { service, deps } = makeService();
       await expect(service.createOpaqueToken(32)).resolves.toBe('opaque-token');
@@ -328,6 +344,52 @@ describe('TokenService', () => {
       );
     });
 
+    it('createEmailConfirmationToken assina com propósito e validade de 7d', async () => {
+      const { service, deps } = makeService();
+      deps.jwt.signAsync.mockResolvedValue('confirm-tok');
+
+      await expect(
+        service.createEmailConfirmationToken({ userIdentifierId: 42 }),
+      ).resolves.toBe('confirm-tok');
+      expect(deps.jwt.signAsync).toHaveBeenCalledWith(
+        { userIdentifierId: 42, purpose: 'email-confirmation' },
+        expect.objectContaining({ secret: 'secret', expiresIn: '7d' }),
+      );
+    });
+
+    it('verifyEmailConfirmationToken retorna o identificador do payload', async () => {
+      const { service, deps } = makeService();
+      deps.jwt.verifyAsync.mockResolvedValue({
+        userIdentifierId: 42,
+        purpose: 'email-confirmation',
+      });
+
+      await expect(
+        service.verifyEmailConfirmationToken('pt-BR', 'tok'),
+      ).resolves.toEqual({ userIdentifierId: 42 });
+    });
+
+    // Sem esta checagem, um token de MFA ou de sessão viraria confirmação de
+    // e-mail — e, no sentido inverso, o token do link entraria em fluxos que
+    // autenticam.
+    it('verifyEmailConfirmationToken recusa token de outro propósito', async () => {
+      const { service, deps } = makeService();
+      deps.jwt.verifyAsync.mockResolvedValue({ userIdentifierId: 42 });
+
+      await expect(
+        service.verifyEmailConfirmationToken('pt-BR', 'tok'),
+      ).rejects.toThrow(BadRequestException);
+    });
+
+    it('verifyEmailConfirmationToken lança BadRequest em token inválido', async () => {
+      const { service, deps } = makeService();
+      deps.jwt.verifyAsync.mockRejectedValue(new Error('bad'));
+
+      await expect(
+        service.verifyEmailConfirmationToken('pt-BR', 'tok'),
+      ).rejects.toThrow(BadRequestException);
+    });
+
     it('decodeExpiredToken ignora expiração', async () => {
       const { service, deps } = makeService();
       deps.jwt.verifyAsync.mockResolvedValue({ sub: 7 });

package/src/token/token.service.ts

@@ -1,10 +1,13 @@
 import { getLocaleText } from "@hed-hog/api-locale";
 import { PrismaService } from "@hed-hog/api-prisma";
-import { ForbiddenException, forwardRef, Inject, Injectable, Logger, UnauthorizedException } from "@nestjs/common";
-import { JwtService } from "@nestjs/jwt";
+import { BadRequestException, ForbiddenException, forwardRef, Inject, Injectable, Logger, UnauthorizedException } from "@nestjs/common";
+import { JwtService, JwtSignOptions } from "@nestjs/jwt";
 import { SecurityService } from "../security/security.service";
 import { SettingService } from "../setting/setting.service";
 
+/** Claim que separa o token do link de confirmação de e-mail dos demais JWTs. */
+const EMAIL_CONFIRMATION_PURPOSE = 'email-confirmation';
+
 @Injectable()
 export class TokenService {
   private readonly logger = new Logger(TokenService.name);
@@ -79,9 +82,16 @@ export class TokenService {
     }
   }
 
-  async createAccessToken(payload: Record<string, any>) {
+  /**
+   * `options` permite sobrescrever o `expiresIn` global do JwtModule numa
+   * chamada especifica — usado pela simulacao de acesso, cujo token precisa
+   * morrer junto com a sessao (que nao e renovavel) e nao aos 15 minutos
+   * padrao.
+   */
+  async createAccessToken(payload: Record<string, any>, options?: JwtSignOptions) {
     return this.jwt.signAsync(payload, {
       secret: this.security.getJwtSecret(),
+      ...(options ?? {}),
     });
   }
 
@@ -178,6 +188,50 @@ export class TokenService {
     }
   }
 
+  /**
+   * Token do link de confirmação de e-mail enviado no cadastro. É um JWT, e não
+   * um token opaco em `user_identifier_challenge` como o do reset de senha, por
+   * dois motivos: `completeAccount`/`authorizeAccountInvite` aceitam qualquer
+   * linha válida daquela tabela, então um token gravado ali transformaria o
+   * e-mail de boas-vindas num link de login de 7 dias — o claim `purpose` fecha
+   * essa porta; e como nada é consumido, clicar duas vezes (pré-fetch do
+   * cliente de e-mail, encaminhamento) continua funcionando.
+   */
+  async createEmailConfirmationToken(payload: { userIdentifierId: number }) {
+    return this.jwt.signAsync(
+      { ...payload, purpose: EMAIL_CONFIRMATION_PURPOSE },
+      {
+        secret: this.security.getJwtSecret(),
+        expiresIn: '7d',
+      },
+    );
+  }
+
+  async verifyEmailConfirmationToken(
+    locale: string,
+    token: string,
+  ): Promise<{ userIdentifierId: number }> {
+    try {
+      const payload = await this.jwt.verifyAsync(token, {
+        secret: this.security.getJwtSecret(),
+      });
+
+      if (payload.purpose !== EMAIL_CONFIRMATION_PURPOSE) {
+        throw new Error('Token purpose mismatch');
+      }
+
+      return { userIdentifierId: payload.userIdentifierId };
+    } catch (error) {
+      throw new BadRequestException(
+        getLocaleText(
+          'confirmEmail.invalidOrExpired',
+          locale,
+          'This confirmation link is invalid or has expired.',
+        ),
+      );
+    }
+  }
+
   async decodeExpiredToken(token: string): Promise<any> {
     try {
       return await this.jwt.verifyAsync(token, {

package/src/user/user.service.spec.ts

@@ -23,7 +23,7 @@ const makeDeps = () => {
   };
   const paginationService = { paginatePrismaModel: jest.fn() };
   const security = { hashArgon2: jest.fn().mockResolvedValue('hashed') };
-  const challenge = { verifyEmail: jest.fn() };
+  const challenge = { sendEmailConfirmationLink: jest.fn() };
   const file = { upload: jest.fn(), delete: jest.fn(), getBuffer: jest.fn() };
   const integrationApi = { publishEvent: jest.fn().mockResolvedValue(undefined) };
   const settingService = { getSettingValues: jest.fn().mockResolvedValue({}) };
@@ -69,7 +69,16 @@ describe('UserService', () => {
       deps.prismaService.user_activity.create.mockResolvedValue({ id: 1 });
       await service.registerUserActivity(5, 'login');
       expect(deps.prismaService.user_activity.create).toHaveBeenCalledWith({
-        data: { user_id: 5, action: 'login' },
+        data: { user_id: 5, action: 'login', actor_user_id: null },
+      });
+    });
+
+    it('grava o ator quem provocou a atividade (simulação de acesso)', async () => {
+      const { service, deps } = makeService();
+      deps.prismaService.user_activity.create.mockResolvedValue({ id: 1 });
+      await service.registerUserActivity(5, 'impersonationStarted', 9);
+      expect(deps.prismaService.user_activity.create).toHaveBeenCalledWith({
+        data: { user_id: 5, action: 'impersonationStarted', actor_user_id: 9 },
       });
     });
   });
@@ -403,7 +412,29 @@ describe('UserService', () => {
         id: '7',
         action: 'login',
         createdAt: '2026-01-01T00:00:00.000Z',
+        actor: null,
+      });
+    });
+
+    it('resolve o nome do ator numa atividade de simulação de acesso', async () => {
+      const { service, deps } = makeService();
+      deps.prismaService.user.findUnique.mockResolvedValue({ id: 1 });
+      deps.paginationService.paginatePrismaModel.mockResolvedValue({
+        data: [
+          {
+            id: 8,
+            action: 'impersonationStarted',
+            actor_user_id: 42,
+            created_at: new Date('2026-01-01T00:00:00Z'),
+          },
+        ],
+        total: 1,
       });
+      deps.prismaService.user.findMany.mockResolvedValue([{ id: 42, name: 'Operadora' }]);
+
+      const result = await service.listUserActivities('en', 1, {});
+
+      expect(result.data[0].actor).toEqual({ id: 42, name: 'Operadora' });
     });
   });
 });

package/src/user/user.service.ts

@@ -186,7 +186,47 @@ export class UserService {
   }
 
   async get(locale: string, userId: number) {
-    return this.findUserById(locale, userId);
+    const user = await this.findUserById(locale, userId);
+
+    // Enriquecimento so aqui, e nao em `findUserById`: aquele metodo tambem
+    // serve `GET /auth/verify`, que roda a cada carga de pagina. Quem precisa
+    // dos nomes de operador/ator e a ficha do usuario no admin.
+    const [user_activity, user_session] = await Promise.all([
+      this.attachActivityActors((user as any).user_activity ?? []),
+      this.attachSessionImpersonators((user as any).user_session ?? []),
+    ]);
+
+    return { ...user, user_activity, user_session };
+  }
+
+  /** Ver `attachActivityActors`: mesma razao, aplicada a `user_session`. */
+  private async attachSessionImpersonators(sessions: any[]) {
+    const ids = [
+      ...new Set(
+        sessions
+          .map((session) => session.impersonator_user_id)
+          .filter((id): id is number => typeof id === 'number'),
+      ),
+    ];
+
+    const users = ids.length
+      ? await this.prismaService.user.findMany({
+          where: { id: { in: ids } },
+          select: { id: true, name: true },
+        })
+      : [];
+    const byId = new Map(users.map((user) => [user.id, user]));
+
+    return sessions.map((session: any) => ({
+      ...session,
+      impersonator:
+        typeof session.impersonator_user_id === 'number'
+          ? (byId.get(session.impersonator_user_id) ?? {
+              id: session.impersonator_user_id,
+              name: '',
+            })
+          : null,
+    }));
   }
 
   async createWithEmailAndPassword(
@@ -236,7 +276,7 @@ export class UserService {
     });
 
     try {
-      await this.challenge.verifyEmail(locale, user.id, email, app);
+      await this.challenge.sendEmailConfirmationLink(locale, user.id, email, app);
     } catch (error: any) {
       this.logger.warn(
         `Signup confirmation email failed for user ${user.id}: ${error?.message ?? error}`
@@ -253,7 +293,10 @@ export class UserService {
       payload: { id: user.id, name: user.name, email },
     }).catch(() => null);
 
-    return { user, hasChallenge: true };
+    // `hasChallenge` não é decidido aqui: quem chama (AuthService.signupWithEmailAndPassword)
+    // é que sabe se `require-email-verification` está ligada e se o cadastro
+    // deve ou não já sair com uma sessão emitida.
+    return { user };
   }
 
   async update(
@@ -459,6 +502,9 @@ export class UserService {
           take: 20,
         },
         user_session: true,
+        // Os dispositivos NAO entram aqui: uma conta antiga acumula dezenas
+        // deles, e embutir a lista inteira pesaria em todo GET /user/:id. O
+        // sheet busca em GET /user-device/user/:userId, que e paginado.
         user_account: true,
          role_user: {
            include: {
@@ -673,7 +719,15 @@ export class UserService {
   // Activity Tracking
   // ==========================================
 
-  async registerUserActivity(userId: number | null | undefined, action: string) {
+  /**
+   * `actorUserId` marca quem provocou a atividade quando nao foi o proprio
+   * usuario — hoje, o operador de uma simulacao de acesso.
+   */
+  async registerUserActivity(
+    userId: number | null | undefined,
+    action: string,
+    actorUserId?: number | null,
+  ) {
     if (!userId || !Number.isInteger(userId) || userId <= 0) {
       return null;
     }
@@ -682,6 +736,7 @@ export class UserService {
       data: {
         user_id: userId,
         action,
+        actor_user_id: actorUserId ?? null,
       },
     });
   }
@@ -690,13 +745,18 @@ export class UserService {
   // Change Log (administrative audit trail)
   // ==========================================
 
-  private async recordUserChange(data: {
+  /**
+   * Publico porque a simulacao de acesso (ImpersonationService) tambem precisa
+   * gravar na mesma trilha administrativa, com o operador como ator.
+   */
+  async recordUserChange(data: {
     targetUserId: number;
     actorUserId?: number | null;
     action: string;
     summary?: string;
     beforeData?: unknown;
     afterData?: unknown;
+    ipAddress?: string | null;
   }) {
     return this.prismaService.user_change_log
       .create({
@@ -705,6 +765,7 @@ export class UserService {
           actor_user_id: data.actorUserId ?? null,
           action: data.action,
           summary: data.summary ?? null,
+          ip_address: data.ipAddress ?? null,
           before_data:
             data.beforeData === undefined
               ? null
@@ -930,16 +991,57 @@ export class UserService {
       },
     );
 
+    const withActors = await this.attachActivityActors(paginated.data || []);
+
     return {
       ...paginated,
-      data: (paginated.data || []).map((activity: any) => ({
+      data: withActors.map((activity: any) => ({
         id: String(activity.id),
         action: activity.action,
         createdAt: activity.created_at?.toISOString?.() || null,
+        actor: activity.actor,
       })),
     };
   }
 
+  /**
+   * Anexa `actor` as atividades provocadas por outra pessoa (simulacao de
+   * acesso). `actor_user_id` e INT puro, sem FK — uma segunda FK para `user`
+   * renomearia a relacao `user.user_activity` no db pull —, entao o nome vem de
+   * uma consulta separada, como em `listUserChangeLogs`.
+   *
+   * Preserva os campos originais: a ficha do usuario embute `user_activity` cru
+   * e a linha do tempo do admin le `created_at`, nao `createdAt`.
+   */
+  async attachActivityActors(activities: any[]) {
+    const actorIds = [
+      ...new Set(
+        activities
+          .map((activity) => activity.actor_user_id)
+          .filter((id): id is number => typeof id === 'number'),
+      ),
+    ];
+
+    const actors = actorIds.length
+      ? await this.prismaService.user.findMany({
+          where: { id: { in: actorIds } },
+          select: { id: true, name: true },
+        })
+      : [];
+    const actorById = new Map(actors.map((actor) => [actor.id, actor]));
+
+    return activities.map((activity: any) => ({
+      ...activity,
+      actor:
+        typeof activity.actor_user_id === 'number'
+          ? (actorById.get(activity.actor_user_id) ?? {
+              id: activity.actor_user_id,
+              name: '',
+            })
+          : null,
+    }));
+  }
+
   // ==========================================
   // Private Helper Methods
   // ==========================================