@hed-hog/core 0.0.390 → 0.0.394

package/src/profile/profile.service.ts

@@ -24,6 +24,7 @@ import { SecurityService } from '../security/security.service';
 import { SettingService } from '../setting/setting.service';
 import { TokenService } from '../token/token.service';
 import { UserService } from '../user/user.service';
+import { buildSecurityEventVars } from '../utils/security-event-vars';
 import { resolveWebAuthnOrigin } from '../utils/webauthn-origin';
 import { ChangeEmailDto } from './dto/change-email.dto';
 import { ChangePasswordDto } from './dto/change-password.dto';
@@ -322,9 +323,18 @@ export class ProfileService {
   }
 
   async getProfile(userId: number) {
-    return this.prisma.user.findUnique({
-      where: { id: userId },
-    });
+    const [user, passwordCredentials] = await Promise.all([
+      this.prisma.user.findUnique({ where: { id: userId } }),
+      this.prisma.user_credential.count({ where: { user_id: userId, type: 'password' } }),
+    ]);
+
+    if (!user) return user;
+
+    // Quem entrou só por login social não tem senha para digitar. Sem este
+    // campo o cliente não tem como saber disso e acaba exigindo a senha em
+    // telas onde `deleteAccount`/`changePassword` já a dispensam — o que deixa
+    // essas contas sem caminho para excluir a própria conta.
+    return { ...user, hasPassword: passwordCredentials > 0 };
   }
 
   async getMFAMethods(userId: number) {
@@ -477,14 +487,22 @@ export class ProfileService {
     });
 
     if (user?.user_identifier?.[0]?.value) {
-      this.mail.sendTemplatedMail(locale, {
-        email: user.user_identifier[0].value,
+      const recipientEmail = user.user_identifier[0].value;
+      // Data e pais sao formatados aqui, entao o idioma tem que ser o mesmo que
+      // o corpo do e-mail vai usar - resolvido antes, nao dentro do envio.
+      const recipientLocale = await this.mail.resolveRecipientLocale(
+        recipientEmail,
+        locale,
+        userId,
+      );
+
+      this.mail.sendTemplatedMail(recipientLocale, {
+        email: recipientEmail,
         slug: 'auth-change-password-notification',
+        userId,
         variables: {
           name: user.name,
-          userAgent: userAgent || 'Unknown',
-          ipAddress: ipAddress || 'Unknown',
-          location: 'Unknown',
+          ...buildSecurityEventVars({ ipAddress, userAgent, locale: recipientLocale }),
         },
         app: await this.challenge.resolveAppKeyFromOrigin(origin),
       }).catch(error => {

package/src/redis/redis-pubsub.ts

@@ -1,3 +1,4 @@
+import * as Sentry from '@sentry/nestjs';
 import { Logger } from '@nestjs/common';
 import { createClient, type RedisClientType } from 'redis';
 
@@ -132,6 +133,16 @@ export async function createRedisPubSub(
       try {
         await onMessage(message);
       } catch (error) {
+        // A instrumentação automática do Sentry para node-redis cobre publish()
+        // mas NÃO subscribe()/entrega de mensagem (limitação da instrumentação
+        // vendorizada, não deste projeto) — sem esta captura explícita, uma
+        // falha aqui era só um logger.warn, invisível fora do log do pod.
+        Sentry.withScope((scope) => {
+          scope.setTags({ 'redis.channel': channel, 'redis.label': label });
+          Sentry.captureException(error, {
+            mechanism: { handled: true, type: 'hedhog.redis_pubsub' },
+          });
+        });
         logger.warn(
           `Failed to handle Redis ${label} message: ${extractRedisErrorMessage(error)}`,
         );

package/src/role/guards/role.guard.spec.ts

@@ -154,4 +154,79 @@ describe('RoleGuard', () => {
       true,
     );
   });
+
+  describe('simulação de acesso — denylist de rotas', () => {
+    const impersonatedRequest = {
+      headers: { authorization: 'Bearer tok' },
+      auth: { sub: 42, sessionId: 555, act: 7, imp: true },
+    };
+
+    it('bloqueia GET /auth/desktop-token, que é @NoRole()', async () => {
+      // Sem esta guarda o operador cunharia para o ALVO uma sessão completa,
+      // renovável e de 30 dias — furando o teto da simulação.
+      const { guard, deps } = makeService();
+      setMeta(deps.reflector, { withNoRole: true });
+      setPath(deps.reflector, 'auth', 'desktop-token', RequestMethod.GET);
+
+      await expect(
+        guard.canActivate(makeContext(impersonatedRequest) as any),
+      ).rejects.toThrow(ForbiddenException);
+    });
+
+    it('bloqueia POST /auth/logout, que é @Public()', async () => {
+      // O cookie `rt` da mesma origem é o do OPERADOR: sair por aqui revogaria
+      // a sessão real dele.
+      const { guard, deps } = makeService();
+      setMeta(deps.reflector, { public: true });
+      setPath(deps.reflector, 'auth', 'logout', RequestMethod.POST);
+
+      await expect(
+        guard.canActivate(makeContext(impersonatedRequest) as any),
+      ).rejects.toThrow(ForbiddenException);
+    });
+
+    it('bloqueia a família /auth/pairing por prefixo', async () => {
+      const { guard, deps } = makeService();
+      setMeta(deps.reflector, { public: true });
+      setPath(deps.reflector, 'auth', 'pairing/redeem', RequestMethod.POST);
+
+      await expect(
+        guard.canActivate(makeContext(impersonatedRequest) as any),
+      ).rejects.toThrow(ForbiddenException);
+    });
+
+    it('bloqueia simulação aninhada em POST /impersonation/start', async () => {
+      const { guard, deps } = makeService();
+      setMeta(deps.reflector, { withRole: true });
+      setPath(deps.reflector, 'impersonation', 'start', RequestMethod.POST);
+
+      await expect(
+        guard.canActivate(makeContext(impersonatedRequest) as any),
+      ).rejects.toThrow(ForbiddenException);
+    });
+
+    it('libera POST /impersonation/stop — sem ela não há como sair', async () => {
+      const { guard, deps } = makeService();
+      setMeta(deps.reflector, { withNoRole: true });
+      setPath(deps.reflector, 'impersonation', 'stop', RequestMethod.POST);
+
+      await expect(
+        guard.canActivate(makeContext(impersonatedRequest) as any),
+      ).resolves.toBe(true);
+    });
+
+    it('não interfere fora de uma simulação', async () => {
+      const { guard, deps } = makeService();
+      setMeta(deps.reflector, { withNoRole: true });
+      setPath(deps.reflector, 'auth', 'desktop-token', RequestMethod.GET);
+      const request = {
+        headers: { authorization: 'Bearer tok' },
+        auth: { sub: 3, sessionId: 1 },
+      };
+
+      await expect(guard.canActivate(makeContext(request) as any)).resolves.toBe(
+        true,
+      );
+    });
+  });
 });

package/src/role/guards/role.guard.ts

@@ -14,6 +14,7 @@ import {
 import { METHOD_METADATA } from '@nestjs/common/constants';
 import { Reflector } from '@nestjs/core';
 import { Request } from 'express';
+import { isRestrictedDuringImpersonation } from '../../impersonation/impersonation-restrictions';
 
 @Injectable()
 export class RoleGuard implements CanActivate {
@@ -29,6 +30,27 @@ export class RoleGuard implements CanActivate {
   ) {}
 
   async canActivate(context: ExecutionContext): Promise<boolean> {
+    const request = context.switchToHttp().getRequest<Request>();
+    const { fullPath, httpMethod } = this.resolveRoute(context);
+
+    // ANTES dos atalhos de @Public()/@NoRole(): sao esses dois decorators que
+    // protegem as rotas que uma simulacao nao pode alcancar (ver
+    // impersonation-restrictions.ts). Checar depois deles deixaria
+    // /auth/desktop-token e /auth/logout passarem.
+    if (
+      (request as any)?.auth?.imp === true &&
+      isRestrictedDuringImpersonation(httpMethod, fullPath)
+    ) {
+      const locale = request['locale'] || 'en';
+      throw new ForbiddenException(
+        getLocaleText(
+          'impersonation.restrictedRoute',
+          locale,
+          'This action is not available during an access simulation.',
+        ),
+      );
+    }
+
     const isPublic = this.reflector.getAllAndOverride<boolean>(IS_PUBLIC_KEY, [
       context.getHandler(),
       context.getClass(),
@@ -57,23 +79,6 @@ export class RoleGuard implements CanActivate {
       return true;
     }
 
-    const request = context.switchToHttp().getRequest<Request>();
-    const controller = context.getClass();
-    const handler = context.getHandler();
-    const controllerPath = this.reflector.get<string>('path', controller) || '';
-    const methodPath = this.reflector.get<string>('path', handler) || '';
-
-    const requestMethod = this.reflector.get<RequestMethod>(
-      METHOD_METADATA,
-      handler,
-    );
-
-    let fullPath = `/${controllerPath}/${methodPath}`.replace(/\/+/g, '/');
-
-    if (fullPath.endsWith('/')) {
-      fullPath = fullPath.slice(0, -1);
-    }
-
     const token = this.extractTokenFromHeader(request);
 
     if (!token) {
@@ -85,37 +90,11 @@ export class RoleGuard implements CanActivate {
 
     const userId = (request as any)?.auth?.sub;
 
-    let httpMethod: any;
-    switch (requestMethod) {
-      case RequestMethod.GET:
-        httpMethod = 'GET';
-        break;
-      case RequestMethod.POST:
-        httpMethod = 'POST';
-        break;
-      case RequestMethod.PUT:
-        httpMethod = 'PUT';
-        break;
-      case RequestMethod.DELETE:
-        httpMethod = 'DELETE';
-        break;
-      case RequestMethod.PATCH:
-        httpMethod = 'PATCH';
-        break;
-      case RequestMethod.OPTIONS:
-        httpMethod = 'OPTIONS';
-        break;
-      case RequestMethod.HEAD:
-        httpMethod = 'HEAD';
-        break;
-      case RequestMethod.ALL:
-        httpMethod = 'ALL';
-        break;
-    }
-    
     const route = await this.prisma.route.count({
       where: {
-        method: httpMethod,
+        // `route.method` e um enum gerado com nome variavel por instalacao; o
+        // valor vem dos metadados do Nest e sempre casa com um dos membros.
+        method: httpMethod as any,
         url: fullPath,
         role_route: {
           some: {
@@ -171,6 +150,45 @@ export class RoleGuard implements CanActivate {
     return true;
   }
 
+  /**
+   * Reconstroi `METHOD /path` a partir dos metadados do Nest — a mesma chave
+   * usada na tabela `route`, com os `:params` declarados no controller.
+   */
+  private resolveRoute(context: ExecutionContext): {
+    fullPath: string;
+    httpMethod: string;
+  } {
+    const controllerPath =
+      this.reflector.get<string>('path', context.getClass()) || '';
+    const methodPath =
+      this.reflector.get<string>('path', context.getHandler()) || '';
+
+    let fullPath = `/${controllerPath}/${methodPath}`.replace(/\/+/g, '/');
+
+    if (fullPath.endsWith('/')) {
+      fullPath = fullPath.slice(0, -1);
+    }
+
+    const requestMethod = this.reflector.get<RequestMethod>(
+      METHOD_METADATA,
+      context.getHandler(),
+    );
+
+    const httpMethod =
+      {
+        [RequestMethod.GET]: 'GET',
+        [RequestMethod.POST]: 'POST',
+        [RequestMethod.PUT]: 'PUT',
+        [RequestMethod.DELETE]: 'DELETE',
+        [RequestMethod.PATCH]: 'PATCH',
+        [RequestMethod.OPTIONS]: 'OPTIONS',
+        [RequestMethod.HEAD]: 'HEAD',
+        [RequestMethod.ALL]: 'ALL',
+      }[requestMethod] ?? '';
+
+    return { fullPath, httpMethod };
+  }
+
   private extractTokenFromHeader(request: Request): string | undefined {
     const [type, token] = request.headers.authorization?.split(' ') ?? [];
     return type === 'Bearer' ? token : undefined;

package/src/session/session.service.spec.ts

@@ -292,6 +292,9 @@ describe('SessionService', () => {
         revoked_at: null,
         expires_at: new Date(Date.now() + 100000),
         browser_id: 'br',
+        // O refresh e fail-closed: `impersonator_user_id` precisa vir do select
+        // e ser explicitamente null para a rotacao seguir.
+        impersonator_user_id: null,
       });
       const tx = {
         user_session: {
@@ -312,6 +315,84 @@ describe('SessionService', () => {
     });
   });
 
+  describe('createImpersonation', () => {
+    it('grava o operador, expiração própria e browser_id nulo', async () => {
+      jest.useFakeTimers().setSystemTime(new Date('2026-08-22T12:00:00Z'));
+      const { service, deps } = makeService();
+      deps.prisma.user_session.create.mockResolvedValue({ id: 9 });
+
+      await service.createImpersonation('pt', 42, 7, '1.2.3.4', 'ua', 30, 'chamado 123');
+
+      const data = (deps.prisma.user_session.create as any).mock.calls[0][0].data;
+      expect(data.user_id).toBe(42);
+      expect(data.impersonator_user_id).toBe(7);
+      expect(data.impersonation_reason).toBe('chamado 123');
+      expect(data.browser_id).toBeNull();
+      expect(data.expires_at).toEqual(new Date('2026-08-22T12:30:00Z'));
+    });
+
+    it('descarta o token opaco — não existe refresh token para a sessão simulada', async () => {
+      const { service, deps } = makeService();
+      deps.prisma.user_session.create.mockResolvedValue({ id: 9 });
+
+      const result: any = await service.createImpersonation(
+        'pt', 42, 7, '1.2.3.4', 'ua', 30,
+      );
+
+      expect(result).toEqual({ id: 9 });
+      expect(result.token).toBeUndefined();
+    });
+
+    it('NÃO aplica o limite de sessões: simular alguém não pode derrubar a pessoa', async () => {
+      const { service, deps } = makeService();
+      deps.setting.getSettingValues.mockResolvedValue({ 'max-concurrent-sessions': 1 });
+      deps.prisma.user_session.create.mockResolvedValue({ id: 9 });
+
+      await service.createImpersonation('pt', 42, 7, '1.2.3.4', 'ua', 30);
+
+      expect(deps.prisma.user_session.findMany).not.toHaveBeenCalled();
+      expect(deps.prisma.user_session.updateMany).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('refresh - sessão simulada', () => {
+    it('rejeita rotação de sessão de simulação', async () => {
+      const { service, deps } = makeService();
+      deps.prisma.user_session.findFirst.mockResolvedValue({
+        id: 1,
+        user_id: 42,
+        ip_address: '1.2.3.4',
+        user_agent: 'ua',
+        revoked_at: null,
+        expires_at: new Date(Date.now() + 100000),
+        browser_id: null,
+        impersonator_user_id: 7,
+      });
+
+      await expect(service.refresh('pt', 'tok', '1.2.3.4', 'ua')).rejects.toThrow(
+        UnauthorizedException,
+      );
+      expect(deps.prisma.$transaction).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('enforceSessionLimit - sessões simuladas', () => {
+    it('não conta simulações no limite de sessões do usuário', async () => {
+      const { service, deps } = makeService();
+      deps.setting.getSettingValues.mockResolvedValue({
+        'max-concurrent-sessions': 2,
+        'refresh-token-expiration-minutes': 100,
+      });
+      deps.prisma.user_session.findMany.mockResolvedValue([]);
+      deps.prisma.user_session.create.mockResolvedValue({ id: 1 });
+
+      await service.create('pt', 42, '1.2.3.4', 'ua', 'br');
+
+      const where = (deps.prisma.user_session.findMany as any).mock.calls[0][0].where;
+      expect(where.impersonator_user_id).toBeNull();
+    });
+  });
+
   describe('getUserSessions - paginação', () => {
     it('lança BadRequest quando usuário não existe', async () => {
       const { service, deps } = makeService();

package/src/session/session.service.ts

@@ -79,6 +79,77 @@ export class SessionService {
     return { token, session };
   }
 
+  /**
+   * Sessao de simulacao de acesso: um operador vendo o sistema como outro
+   * usuario. Caminho separado do `create` por tres motivos, todos deliberados:
+   *
+   * 1. NAO chama `enforceSessionLimit`. Com `max-concurrent-sessions > 0`,
+   *    abrir uma simulacao despejaria sessoes REAIS do alvo — simular alguem
+   *    derrubaria a pessoa.
+   * 2. O token opaco e gerado e DESCARTADO. Ninguem recebe refresh token para
+   *    esta sessao, entao ela e nao renovavel por construcao, nao so por regra.
+   * 3. `browser_id` fica nulo, para a simulacao nao se misturar aos slots de
+   *    navegador do alvo.
+   */
+  async createImpersonation(
+    locale: string,
+    targetUserId: number,
+    impersonatorUserId: number,
+    ipAddress: string,
+    userAgent: string,
+    expiresInMinutes: number,
+    reason?: string | null,
+  ) {
+    if (!targetUserId || !impersonatorUserId) {
+      throw new BadRequestException(getLocaleText('session.userIdRequired', locale, 'User ID is required to create a session.'));
+    }
+
+    const throwawayToken = await this.token.createOpaqueToken();
+
+    return this.prisma.user_session.create({
+      data: {
+        user_id: targetUserId,
+        ip_address: ipAddress || 'unknown',
+        user_agent: userAgent || 'unknown',
+        expires_at: new Date(Date.now() + expiresInMinutes * 60 * 1000),
+        hash: this.security.hashWithPepper(throwawayToken),
+        browser_id: null,
+        impersonator_user_id: impersonatorUserId,
+        impersonation_reason: reason ?? null,
+      },
+    });
+  }
+
+  /**
+   * Anexa `impersonator: { id, name }` as sessoes simuladas. Nao ha relacao
+   * Prisma para isso: `impersonator_user_id` e INT puro, sem FK, para nao
+   * renomear `user.user_session` no db pull. Mesmo padrao de
+   * `UserService.listUserChangeLogs` com os atores.
+   */
+  private async attachImpersonators<T extends { impersonator_user_id?: number | null }>(rows: T[]) {
+    const ids = Array.from(
+      new Set(rows.map((row) => row.impersonator_user_id).filter((id): id is number => typeof id === 'number')),
+    );
+
+    if (!ids.length) {
+      return rows.map((row) => ({ ...row, impersonator: null }));
+    }
+
+    const users = 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 rows.map((row) => ({
+      ...row,
+      impersonator:
+        typeof row.impersonator_user_id === 'number'
+          ? (byId.get(row.impersonator_user_id) ?? { id: row.impersonator_user_id, name: '' })
+          : null,
+    }));
+  }
+
   async refresh(locale: string, refreshToken: string, ipAddress: string, userAgent: string, browserId?: string | null) {
     if (!refreshToken) {
       throw new UnauthorizedException(getLocaleText('accessDenied', locale, 'Access denied.'));
@@ -88,7 +159,7 @@ export class SessionService {
 
     const rawSession = await this.prisma.user_session.findFirst({
       where: { hash },
-      select: { id: true, user_id: true, ip_address: true, user_agent: true, revoked_at: true, expires_at: true, browser_id: true },
+      select: { id: true, user_id: true, ip_address: true, user_agent: true, revoked_at: true, expires_at: true, browser_id: true, impersonator_user_id: true },
     });
 
     if (!rawSession) {
@@ -106,6 +177,15 @@ export class SessionService {
       throw new UnauthorizedException(getLocaleText('accessDenied', locale, 'Access denied.'));
     }
 
+    // Simulacao de acesso e nao renovavel. `createImpersonation` ja descarta o
+    // token opaco, entao chegar aqui significa que alguem obteve o segredo por
+    // outro caminho — e renovar transformaria a janela de 30 minutos numa sessao
+    // normal de 30 dias, sem a marca de simulado.
+    if (rawSession.impersonator_user_id !== null) {
+      this.logger.warn(`[SessionRefresh] Refresh rejected: sessionId=${rawSession.id} userId=${rawSession.user_id} is an impersonation session`);
+      throw new UnauthorizedException(getLocaleText('accessDenied', locale, 'Access denied.'));
+    }
+
     const session = {
       id: rawSession.id,
       user_id: rawSession.user_id,
@@ -223,7 +303,9 @@ export class SessionService {
       });
 
       const itemsWithLocation = await Promise.all(
-        paginate.data.map(async (s) => {
+        // O `hash` é o resumo do refresh token: nenhum cliente precisa dele, e
+        // a lista de sessões é exibida na tela de segurança do app e do site.
+        paginate.data.map(async ({ hash: _hash, ...s }) => {
           const ip = s.ip_address || s.ip || null;
           let location: GeoIpResult | null = null;
           if (ip && ip !== '127.0.0.1' && ip !== '::1') {
@@ -240,7 +322,7 @@ export class SessionService {
       );
 
       return {
-        data: itemsWithLocation,
+        data: await this.attachImpersonators(itemsWithLocation),
         total: paginate.total || 0,
         lastPage: Math.ceil((paginate.total || 0) / (paginate.pageSize || 1)),
         page: paginate.page ?? 1,
@@ -272,7 +354,9 @@ export class SessionService {
       });
 
       const itemsWithLocation = await Promise.all(
-        paginate.data.map(async (s) => {
+        // O `hash` é o resumo do refresh token: nenhum cliente precisa dele, e
+        // a lista de sessões é exibida na tela de segurança do app e do site.
+        paginate.data.map(async ({ hash: _hash, ...s }) => {
           const ip = s.ip_address || s.ip || null;
           let location: GeoIpResult | null = null;
           if (ip && ip !== '127.0.0.1' && ip !== '::1') {
@@ -289,7 +373,7 @@ export class SessionService {
       );
 
       return {
-        data: itemsWithLocation,
+        data: await this.attachImpersonators(itemsWithLocation),
         total: paginate.total || 0,
         lastPage: Math.ceil((paginate.total || 0) / (paginate.pageSize || 1)),
         page: paginate.page ?? 1,
@@ -391,7 +475,10 @@ export class SessionService {
       where: {
         user_id: userId,
         revoked_at: null,
-        expires_at: { gt: new Date() }
+        expires_at: { gt: new Date() },
+        // Simulacao de acesso nao consome slot: ela nasce com browser_id nulo e
+        // seria contada como slot proprio, despejando uma sessao real do alvo.
+        impersonator_user_id: null,
       },
       orderBy: { created_at: 'asc' },
       select: { id: true, browser_id: true }

package/src/setting/brand-asset.service.ts

@@ -0,0 +1,137 @@
+import {
+  BrandAssetBases,
+  isPublicAssetUrl,
+  resolveBrandAssetUrl,
+} from '@hed-hog/api-mail';
+import { forwardRef, Inject, Injectable, Logger } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { SettingService } from './setting.service';
+
+// Reexportados para que as libraries que ja dependem do core (lms, crm,
+// operations) usem a regra sem precisar declarar `@hed-hog/api-mail`.
+export { isPublicAssetUrl, resolveBrandAssetUrl };
+export type { BrandAssetBases };
+
+/** Timeout do fetch em {@link BrandAssetService.fetchAsDataUri}. */
+const FETCH_TIMEOUT_MS = 5_000;
+
+/**
+ * Resolucao das settings de marca (`image-url`, `icon-url`, `pdf-logo`) para
+ * URL absoluta, para quem renderiza fora do browser: e-mail, PDF, relatorio.
+ *
+ * Existe porque a mesma regra estava duplicada em quatro lugares, todos
+ * derivando a base da env `API_URL` - que nao esta definida em nenhum
+ * manifesto de producao. As settings `url` e `api-url` sao a fonte de verdade
+ * (gravadas na instalacao e editaveis no admin); a env fica como fallback de
+ * dev/CI.
+ */
+@Injectable()
+export class BrandAssetService {
+  private readonly logger = new Logger(BrandAssetService.name);
+
+  constructor(
+    @Inject(forwardRef(() => SettingService))
+    private readonly setting: SettingService,
+    private readonly configService: ConfigService,
+  ) {}
+
+  /** Bases publicas do front (setting `url`) e da API (setting `api-url`). */
+  async getBases(): Promise<BrandAssetBases> {
+    const port = this.configService.get<string | number>('PORT') ?? 3100;
+    let settings: Record<string, any> = {};
+
+    try {
+      settings = await this.setting.getSettingValues(['url', 'api-url']);
+    } catch (error) {
+      this.logger.warn(
+        `Could not read the base URL settings, falling back to the environment: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+    }
+
+    const read = (slug: string) => String(settings[slug] ?? '').trim();
+
+    return {
+      appBaseUrl: read('url'),
+      apiBaseUrl:
+        read('api-url') ||
+        String(this.configService.get<string>('API_URL') ?? '').trim() ||
+        `http://localhost:${port}`,
+    };
+  }
+
+  /**
+   * Resolve um valor de setting de marca para URL absoluta. Devolve `''`
+   * quando nao ha valor ou nao ha base utilizavel - quem chama decide o
+   * fallback.
+   */
+  async resolveAssetUrl(value?: string | null): Promise<string> {
+    const trimmed = String(value ?? '').trim();
+
+    if (!trimmed) {
+      return '';
+    }
+
+    return resolveBrandAssetUrl(trimmed, await this.getBases());
+  }
+
+  /**
+   * Logo do sistema ja absoluto, na ordem de prioridade informada.
+   *
+   * `slugs` permite ao chamador antepor um slug proprio (ex.: `pdf-logo`)
+   * antes de cair no `image-url` global.
+   */
+  async resolveLogoUrl(
+    slugs: string[] = ['image-url', 'icon-url'],
+  ): Promise<string> {
+    const settings = await this.setting.getSettingValues(slugs);
+
+    for (const slug of slugs) {
+      const value = String(settings[slug] ?? '').trim();
+
+      if (value) {
+        return this.resolveAssetUrl(value);
+      }
+    }
+
+    return '';
+  }
+
+  /**
+   * Baixa a imagem e devolve como data URI.
+   *
+   * O Playwright renderiza o PDF em uma pagina sem sessao e, dependendo do
+   * ambiente, sem rota para o host publico; embutir o binario evita o slot de
+   * imagem vazio. Devolve `null` em qualquer falha, para o chamador cair na
+   * URL absoluta.
+   */
+  async fetchAsDataUri(url: string): Promise<string | null> {
+    if (!url || url.startsWith('data:')) {
+      return url || null;
+    }
+
+    try {
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+      const response = await globalThis.fetch(url, { signal: controller.signal });
+      clearTimeout(timeout);
+
+      if (!response.ok) {
+        return null;
+      }
+
+      const contentType = response.headers.get('content-type') ?? 'image/svg+xml';
+      const buffer = await response.arrayBuffer();
+
+      return `data:${contentType};base64,${Buffer.from(buffer).toString('base64')}`;
+    } catch {
+      return null;
+    }
+  }
+
+  /** Reexportado para quem renderiza e-mail. Ver `isPublicAssetUrl`. */
+  isPublicUrl(url?: string | null): boolean {
+    return isPublicAssetUrl(url);
+  }
+}