@hed-hog/core 0.0.399 → 0.0.400

package/src/task/task.service.ts

@@ -3,6 +3,13 @@ import { Injectable, Logger } from '@nestjs/common';
 import { Cron, CronExpression } from '@nestjs/schedule';
 import { SettingService } from '../setting/setting.service';
 
+/**
+ * Teto de tempo da limpeza do `access_log`. Existe para o caso da entrada
+ * superar a saída de novo: o laço para e devolve o resto para a execução
+ * seguinte, em vez de varrer a madrugada inteira disputando o banco.
+ */
+const ACCESS_LOG_CLEANUP_BUDGET_MS = 10 * 60 * 1000;
+
 @Injectable()
 export class TasksService {
   private readonly logger = new Logger(TasksService.name);
@@ -270,6 +277,23 @@ export class TasksService {
     );
   }
 
+  /**
+   * Apaga os logs de acesso fora da janela de `access-log-retention-days`.
+   *
+   * Roda em lotes até drenar, e não em um lote só. O `access_log` recebe um
+   * INSERT por requisição — em produção, de 200 a 540 mil por dia — enquanto a
+   * limpeza apagava `cleanup-batch-limit` registros por execução diária. Com a
+   * entrada uma ordem de grandeza acima da saída, a retenção nunca era
+   * alcançada: a tabela chegou a 18,6 milhões de linhas e 4 GB, com 11,8
+   * milhões já vencidos e registros três meses mais velhos que a retenção de 30
+   * dias configurada.
+   *
+   * O `cleanup-batch-limit` passa a ser o tamanho de CADA lote — o papel que a
+   * própria descrição da setting sempre anunciou ("valores menores evitam locks
+   * prolongados mas aumentam a duração da limpeza"). O teto agora é de tempo,
+   * não de linhas: o laço para ao drenar a fila ou ao estourar o orçamento,
+   * para que a limpeza não avance madrugada adentro competindo com o tráfego.
+   */
   private async clearOldAccessLogs(): Promise<void> {
     const settings = await this.settingService.getSettingValues([
       'cleanup-batch-limit',
@@ -280,21 +304,37 @@ export class TasksService {
     this.logger.verbose('Starting cleanup of old access logs');
     const startAt = Date.now();
 
-    await this.prismaService.$executeRaw`
-      WITH del AS (
-        SELECT id
-        FROM access_log
-        WHERE created_at < (now() - ${Prisma.sql`INTERVAL '${Prisma.raw(String(retentionDays))} days'`})
-        ORDER BY id
-        LIMIT ${batchLimit}
-      )
-      DELETE FROM access_log al
-      USING del
-      WHERE al.id = del.id
-    `;
+    let deleted = 0;
+    let batches = 0;
+    for (;;) {
+      const removed = await this.prismaService.$executeRaw`
+        WITH del AS (
+          SELECT id
+          FROM access_log
+          WHERE created_at < (now() - ${Prisma.sql`INTERVAL '${Prisma.raw(String(retentionDays))} days'`})
+          ORDER BY id
+          LIMIT ${batchLimit}
+        )
+        DELETE FROM access_log al
+        USING del
+        WHERE al.id = del.id
+      `;
+
+      deleted += removed;
+      batches += 1;
+
+      if (removed < batchLimit) break;
+
+      if (Date.now() - startAt >= ACCESS_LOG_CLEANUP_BUDGET_MS) {
+        this.logger.warn(
+          `Access log cleanup hit the ${ACCESS_LOG_CLEANUP_BUDGET_MS}ms budget after ${deleted} rows; the remainder goes on the next run.`,
+        );
+        break;
+      }
+    }
 
     this.logger.verbose(
-      `Old access logs cleaned up in ${Date.now() - startAt}ms`,
+      `Old access logs cleaned up in ${Date.now() - startAt}ms (${deleted} rows in ${batches} batches)`,
     );
   }
 

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

@@ -410,4 +410,94 @@ describe('TokenService', () => {
       );
     });
   });
+
+  describe('verify - audiencia (audience binding)', () => {
+    const RESOURCE = 'https://hub-api.example.com/mcp';
+    const activeSession = {
+      revoked_at: null,
+      expires_at: new Date(Date.now() + 60_000),
+    };
+
+    // ESTE e o teste central do audience binding: sem ele, o token entregue ao
+    // conector do Claude valeria na API REST inteira.
+    it('recusa token COM aud numa rota que nao declara recurso', async () => {
+      const { service, deps } = makeService();
+      deps.jwt.verifyAsync.mockResolvedValue({ sub: 1, sessionId: 9, aud: RESOURCE });
+
+      await expect(service.verify('en', 'tok')).rejects.toThrow(
+        UnauthorizedException,
+      );
+      // Nem chega a consultar a sessao: a recusa e antes.
+      expect(deps.prisma.user_session.findUnique).not.toHaveBeenCalled();
+    });
+
+    it('recusa token cujo aud e de OUTRO recurso', async () => {
+      const { service, deps } = makeService();
+      deps.jwt.verifyAsync.mockResolvedValue({
+        sub: 1,
+        sessionId: 9,
+        aud: 'https://outro.example.com/mcp',
+      });
+
+      await expect(service.verify('en', 'tok', RESOURCE)).rejects.toThrow(
+        UnauthorizedException,
+      );
+    });
+
+    it('aceita token cujo aud casa exatamente com o recurso', async () => {
+      const { service, deps } = makeService();
+      deps.jwt.verifyAsync.mockResolvedValue({ sub: 1, sessionId: 9, aud: RESOURCE });
+      deps.prisma.user_session.findUnique.mockResolvedValue(activeSession);
+
+      await expect(service.verify('en', 'tok', RESOURCE)).resolves.toMatchObject({
+        sub: 1,
+        aud: RESOURCE,
+      });
+    });
+
+    // Comparacao por igualdade exata: barra final e outro recurso.
+    it('nao normaliza barra final ao comparar', async () => {
+      const { service, deps } = makeService();
+      deps.jwt.verifyAsync.mockResolvedValue({
+        sub: 1,
+        sessionId: 9,
+        aud: RESOURCE + '/',
+      });
+
+      await expect(service.verify('en', 'tok', RESOURCE)).rejects.toThrow(
+        UnauthorizedException,
+      );
+    });
+
+    // O login normal nao pode mudar de comportamento por causa disso.
+    it('aceita token SEM aud, com ou sem recurso declarado', async () => {
+      const { service, deps } = makeService();
+      deps.jwt.verifyAsync.mockResolvedValue({ sub: 1, sessionId: 9 });
+      deps.prisma.user_session.findUnique.mockResolvedValue(activeSession);
+
+      await expect(service.verify('en', 'tok')).resolves.toMatchObject({ sub: 1 });
+      await expect(service.verify('en', 'tok', RESOURCE)).resolves.toMatchObject({
+        sub: 1,
+      });
+    });
+
+    it('falha fechado em erro de banco quando o token e de recurso', async () => {
+      const { service, deps } = makeService();
+      deps.jwt.verifyAsync.mockResolvedValue({ sub: 1, sessionId: 9, aud: RESOURCE });
+      deps.prisma.user_session.findUnique.mockRejectedValue(new Error('db down'));
+
+      await expect(service.verify('en', 'tok', RESOURCE)).rejects.toThrow(
+        UnauthorizedException,
+      );
+    });
+
+    it('segue aberto em erro de banco para a sessao de login', async () => {
+      const { service, deps } = makeService();
+      deps.jwt.verifyAsync.mockResolvedValue({ sub: 1, sessionId: 9 });
+      deps.prisma.user_session.findUnique.mockRejectedValue(new Error('db down'));
+
+      await expect(service.verify('en', 'tok')).resolves.toMatchObject({ sub: 1 });
+    });
+  });
+
 });

package/src/token/token.service.ts

@@ -22,13 +22,46 @@ export class TokenService {
     private readonly setting: SettingService,
   ) { }
 
-  async verify(locale: string, token: string) {
+  /**
+   * `allowedAudience` declara qual recurso ESTA rota atende. A regra e de mao
+   * unica, e e essa assimetria que faz o modelo funcionar:
+   *
+   * - token SEM `aud` (o login normal) vale em qualquer lugar, com ou sem o
+   *   parametro — nada muda para quem ja existe;
+   * - token COM `aud` so vale onde aquele exato recurso foi declarado. Em
+   *   qualquer outra rota, 401.
+   *
+   * O AuthGuard global chama este metodo SEM o terceiro argumento, entao toda
+   * rota que ninguem marcou como recurso ja recusa um token de conector — por
+   * construcao, inclusive nas rotas que ainda nem foram escritas. Nao ha
+   * allowlist para alguem esquecer de atualizar.
+   *
+   * A comparacao e feita aqui, na mao, e nao pela opcao `audience` do
+   * jsonwebtoken: quando aquela opcao esta ausente, a lib simplesmente NAO OLHA o
+   * claim. E exatamente essa omissao que precisa virar rejeicao.
+   */
+  async verify(locale: string, token: string, allowedAudience?: string) {
     try {
 
       const payload = await this.jwt.verifyAsync(token, {
         secret: this.security.getJwtSecret(),
       });
 
+      const audience = payload.aud;
+      const isResourceToken = audience !== undefined;
+
+      // Igualdade exata de string, sem parsear URL — normalizar abriria as mesmas
+      // brechas que a allowlist de redirect_uri ja evita (barra final, case do
+      // host, porta default).
+      if (isResourceToken && audience !== allowedAudience) {
+        this.logger.warn(
+          `[TokenVerify] sessionId=${payload.sessionId} userId=${payload.sub} token with aud=${audience} used outside its resource`,
+        );
+        throw new UnauthorizedException(
+          getLocaleText('accessDenied', locale, 'Access denied.'),
+        );
+      }
+
       // Verify session is not revoked (only if prisma is available)
       if (payload.sessionId && this.prisma) {
         try {
@@ -62,8 +95,21 @@ export class TokenService {
           if (sessionError instanceof UnauthorizedException) {
             throw sessionError;
           }
-          // DB error: log but allow auth to continue to avoid blocking on transient DB issues
           this.logger.error(`[TokenVerify] DB error validating sessionId=${payload.sessionId} userId=${payload.sub}: ${(sessionError as any)?.message}`);
+
+          // Token de recurso nao ganha o beneficio da duvida. Para a sessao de
+          // login, seguir em frente numa falha transitoria de banco e a troca
+          // certa — derrubar todo mundo logado e pior que aceitar uma revogacao
+          // com atraso. Para um token entregue a um cliente externo, user_session
+          // e o UNICO jeito de revogar: continuar aqui faria uma revogacao valer
+          // so no vencimento do JWT. A decisao segue a natureza do TOKEN, nao a
+          // da rota.
+          if (isResourceToken) {
+            throw new UnauthorizedException(
+              getLocaleText('accessDenied', locale, 'Access denied.'),
+            );
+          }
+          // DB error: log but allow auth to continue to avoid blocking on transient DB issues
         }
       }
 

package/src/user/user-credential.util.ts

@@ -21,15 +21,24 @@ export function hasPendingPasswordReset(user: any): boolean {
   );
 }
 
+/**
+ * Credencial de senha que ainda vale: do tipo password e não revogada.
+ *
+ * Existe para quem já tem as credenciais em memória e precisa do mesmo critério
+ * que as consultas de Prisma expressam com `revoked_at: null`. O login e a troca
+ * de e-mail filtravam só por `type`, então uma credencial revogada continuava
+ * autenticando — e a revogação é justamente o que o convite de acesso enterprise
+ * usa para transformar "autorize o acesso" em "crie sua conta e defina a senha".
+ */
+export function isActivePasswordCredential(credential: any): boolean {
+  return credential?.type === 'password' && !credential?.revoked_at;
+}
+
 /**
  * Usuários criados/autenticados apenas via provedor externo (ex: Microsoft
  * Entra ID) nunca têm uma credencial de senha ativa — não faz sentido
  * oferecer o fluxo de "esqueci a senha" para eles.
  */
 export function hasPasswordCredential(user: any): boolean {
-  return Boolean(
-    user?.user_credential?.some(
-      (credential) => credential?.type === 'password' && !credential?.revoked_at,
-    ),
-  );
+  return Boolean(user?.user_credential?.some(isActivePasswordCredential));
 }

package/src/user/user.service.ts

@@ -25,6 +25,7 @@ import {
   PENDING_PASSWORD_RESET_WHERE,
   hasPendingPasswordReset,
 } from './user-credential.util';
+import { USER_SORT } from './user.sort';
 
 // Constants
 const IDENTIFIER_TYPE = {
@@ -48,17 +49,6 @@ const PASSWORD_CHARSETS = {
   symbols: '@#$%&*!?-_+',
 } as const;
 
-const USER_SORT_FIELDS = [
-  'id',
-  'name',
-  'photo_id',
-  'suspended_until',
-  'suspended_reason',
-  'deactivated_at',
-  'created_at',
-  'updated_at',
-] as const;
-
 type UserChangeLog = user_change_log;
 type UserChangeLogActor = Prisma.userGetPayload<{
   select: {
@@ -164,7 +154,7 @@ export class UserService {
       this.prismaService.user,
       {
         ...paginationParams,
-        validSortFields: USER_SORT_FIELDS,
+        sort: USER_SORT,
         where: this.buildUserListWhere(filter, paginationParams?.search),
         include: this.getUserIncludeClause(),
       }

package/src/user/user.sort.ts

@@ -0,0 +1,25 @@
+import { defineSortable } from '@hed-hog/api-pagination';
+
+/**
+ * Campos ordenáveis de `user`.
+ *
+ * `email` fica de fora: mora em `user_identifier` (relação to-many filtrada
+ * por `type = 'email'`), sem coluna própria em `user` para o Prisma ordenar —
+ * mesma limitação documentada em `libraries/lms/src/instructor/instructor.sort.ts`
+ * para o e-mail do instrutor.
+ *
+ * `passwordReset` também fica de fora: é booleano calculado no service
+ * (`hasPendingPasswordReset`), não uma coluna.
+ *
+ * Sem ninguém pedir ordenação, o resultado continua igual ao de antes
+ * (`id` desc, o fallback do `paginatePrismaModel` quando não há `sortField`).
+ */
+export const USER_SORT = defineSortable(
+  {
+    name: true,
+    suspended_until: true,
+    last_login_at: true,
+    id: { initialOrder: 'desc' },
+  },
+  { default: 'id', defaultOrder: 'desc' },
+);

package/src/utils/abbreviate-name.spec.ts

@@ -0,0 +1,50 @@
+import { describe, it, expect } from '@jest/globals';
+import { abbreviateName } from './abbreviate-name';
+
+describe('abbreviateName', () => {
+  it('mantém primeiro nome e último sobrenome', () => {
+    expect(abbreviateName('João Henrique Cunha Rangel')).toBe('João Rangel');
+  });
+
+  it('ignora partículas (de/da/do/das/dos/e) ao escolher o último sobrenome', () => {
+    expect(abbreviateName('Maria de Souza')).toBe('Maria Souza');
+    expect(abbreviateName('Ana da Silva')).toBe('Ana Silva');
+    expect(abbreviateName('Pedro dos Santos')).toBe('Pedro Santos');
+    expect(abbreviateName('Carlos do Nascimento')).toBe('Carlos Nascimento');
+    expect(abbreviateName('José das Neves')).toBe('José Neves');
+    expect(abbreviateName('Silva e Souza Junior')).toBe('Silva Junior');
+  });
+
+  it('nome com duas palavras não muda', () => {
+    expect(abbreviateName('Ana Paula')).toBe('Ana Paula');
+  });
+
+  it('nome com uma palavra só passa como está', () => {
+    expect(abbreviateName('Madonna')).toBe('Madonna');
+  });
+
+  it('nome vazio ou só espaço devolve vazio', () => {
+    expect(abbreviateName('')).toBe('');
+    expect(abbreviateName('   ')).toBe('');
+  });
+
+  it('nome nulo/indefinido devolve vazio', () => {
+    expect(abbreviateName(null)).toBe('');
+    expect(abbreviateName(undefined)).toBe('');
+  });
+
+  it('normaliza espaços múltiplos entre palavras', () => {
+    expect(abbreviateName('  João   Henrique   Rangel  ')).toBe('João Rangel');
+  });
+
+  it('cai no primeiro nome quando só sobra partícula depois dele', () => {
+    // Dado maltratado (ex.: sobrenome vazio salvo como "de") — não deve
+    // repetir o primeiro nome nem devolver a partícula sozinha.
+    expect(abbreviateName('João de')).toBe('João');
+  });
+
+  it('fallback "Alguém"/"Someone" (sem atribuidor) passa direto, sem quebrar', () => {
+    expect(abbreviateName('Alguém')).toBe('Alguém');
+    expect(abbreviateName('Someone')).toBe('Someone');
+  });
+});

package/src/utils/abbreviate-name.ts

@@ -0,0 +1,44 @@
+/**
+ * Partículas ignoradas ao escolher o "último sobrenome" — sem isso, "Maria de
+ * Souza" viraria "Maria de" em vez de "Maria Souza".
+ */
+const NAME_PARTICLES = new Set(['de', 'da', 'do', 'das', 'dos', 'e']);
+
+/**
+ * Abrevia um nome completo para "primeiro nome + último sobrenome", o formato
+ * usado nos templates de e-mail transacional (ex.: `operations-task-assigned`)
+ * pra não estampar o nome completo do colaborador — "João Henrique Cunha
+ * Rangel" vira "João Rangel".
+ *
+ * Partículas (de/da/do/das/dos/e) são ignoradas na escolha do último
+ * sobrenome, não removidas do nome inteiro — só afetam qual token conta como
+ * "o último". Nome com uma palavra só, vazio ou nulo passa como está (nada a
+ * abreviar).
+ */
+export function abbreviateName(fullName?: string | null): string {
+  const trimmed = (fullName ?? '').trim();
+  if (!trimmed) {
+    return trimmed;
+  }
+
+  const words = trimmed.split(/\s+/);
+  if (words.length === 1) {
+    return words[0];
+  }
+
+  const firstName = words[0];
+
+  // Anda de trás pra frente até achar um token que não seja partícula. Se
+  // todos os tokens depois do primeiro forem partícula (dado maltratado),
+  // cai no primeiro nome sozinho em vez de repetir "João de" ou "João João".
+  let lastIndex = words.length - 1;
+  while (lastIndex > 0 && NAME_PARTICLES.has(words[lastIndex].toLowerCase())) {
+    lastIndex--;
+  }
+
+  if (lastIndex === 0) {
+    return firstName;
+  }
+
+  return `${firstName} ${words[lastIndex]}`;
+}

package/src/utils/date-range-query.dto.ts

@@ -0,0 +1,56 @@
+import { Transform } from 'class-transformer';
+import { IsDateString, IsOptional } from 'class-validator';
+
+/**
+ * `?from=yyyy-MM-dd&to=yyyy-MM-dd` — o par padrão de recorte por período de
+ * toda listagem nova. Endpoint que já tem nome próprio (`dateFrom`/`dateTo` da
+ * fila, `createdAtFrom`/`createdAtTo` do mail-sent, `date_from`/`date_to` do
+ * sac) mantém o nome dele: só o que nasce daqui em diante usa `from`/`to`.
+ *
+ * Composto, e não herdado de `PaginationDTO`, porque quase todo adotante é o
+ * **segundo** argumento `@Query()` do controller, ao lado do `@Pagination()` —
+ * que descarta tudo que não é paginação. Carregar `page`/`pageSize` junto
+ * duplicaria campo que o DTO de filtro não é dono. Onde o DTO de filtro já
+ * estende `PaginationDTO`, o jeito de juntar os dois é o `IntersectionType`:
+ *
+ * ```ts
+ * export class ListContractsDto extends IntersectionType(
+ *   PaginationDTO,
+ *   DateRangeQueryDTO,
+ * ) {}
+ * ```
+ *
+ * Quem traduz este par para o `where` do banco é o `resolveDateRange` /
+ * `dateRangeWhere` (`./date-range`).
+ */
+
+/**
+ * O admin manda `?from=` quando o usuário **limpa** o campo. O `@IsOptional()`
+ * só pula `null`/`undefined`, então sem isto o campo limpo viraria 400 — uma
+ * regressão de tela causada por um parâmetro que nem deveria existir. O
+ * `@Transform` roda no `plainToInstance` do `ValidationPipe`, antes do
+ * `validate`, então a string vazia nunca chega ao validador.
+ */
+const blankToUndefined = ({ value }: { value: unknown }) => {
+  const raw = typeof value === 'string' ? value.trim() : value;
+
+  return raw === '' || raw === null ? undefined : raw;
+};
+
+export class DateRangeQueryDTO {
+  /** Primeiro dia do recorte, inclusive. `yyyy-MM-dd`. */
+  @IsOptional()
+  @Transform(blankToUndefined)
+  @IsDateString({}, { message: 'from must be a date in the yyyy-MM-dd format' })
+  from?: string;
+
+  /**
+   * Último dia do recorte, **inclusive** — é assim que o usuário lê o
+   * calendário. Quem converte para o `< to+1d` que o banco precisa é o
+   * `resolveDateRange`.
+   */
+  @IsOptional()
+  @Transform(blankToUndefined)
+  @IsDateString({}, { message: 'to must be a date in the yyyy-MM-dd format' })
+  to?: string;
+}

package/src/utils/date-range.spec.ts

@@ -0,0 +1,175 @@
+import { addIsoDays, dateRangeWhere, resolveDateRange } from './date-range';
+
+describe('resolveDateRange', () => {
+  it('devolve null quando não há período', () => {
+    expect(resolveDateRange()).toBeNull();
+    expect(resolveDateRange('', '')).toBeNull();
+    expect(resolveDateRange(null, null)).toBeNull();
+  });
+
+  it('só com `from`, limita apenas o início', () => {
+    const range = resolveDateRange('2026-08-01')!;
+
+    expect(range.gte).toEqual(new Date('2026-08-01T00:00:00.000Z'));
+    expect(range.lt).toBeUndefined();
+  });
+
+  it('só com `to`, limita apenas o fim', () => {
+    const range = resolveDateRange(undefined, '2026-08-31')!;
+
+    expect(range.lt).toEqual(new Date('2026-09-01T00:00:00.000Z'));
+    expect(range.gte).toBeUndefined();
+  });
+
+  /**
+   * O caso que os três serviços erravam: com `lte` + `new Date(to)` o dia 31
+   * inteiro ficava de fora, porque `'2026-08-31'` vira o INSTANTE
+   * `2026-08-31T00:00:00Z`.
+   */
+  it('inclui o dia final inteiro', () => {
+    const { lt } = resolveDateRange('2026-08-01', '2026-08-31')!;
+
+    expect(lt).toEqual(new Date('2026-09-01T00:00:00.000Z'));
+    expect(new Date('2026-08-31T23:59:59.999Z') < lt!).toBe(true);
+    expect(new Date('2026-09-01T00:00:00.000Z') < lt!).toBe(false);
+  });
+
+  it('atravessa a virada do mês e do ano', () => {
+    expect(resolveDateRange('2026-12-31', '2026-12-31')!.lt).toEqual(
+      new Date('2027-01-01T00:00:00.000Z'),
+    );
+  });
+
+  it('cobre o 29 de fevereiro em ano bissexto', () => {
+    expect(resolveDateRange('2028-02-28', '2028-02-29')!.lt).toEqual(
+      new Date('2028-03-01T00:00:00.000Z'),
+    );
+  });
+
+  it('inverte o período digitado de trás pra frente', () => {
+    expect(resolveDateRange('2026-08-31', '2026-08-01')).toEqual(
+      resolveDateRange('2026-08-01', '2026-08-31'),
+    );
+  });
+
+  it('trata data inválida como ausente, sem estourar', () => {
+    expect(resolveDateRange('31/08/2026', '2026-08-31')!.gte).toBeUndefined();
+    expect(resolveDateRange('2026-13-01')).toBeNull();
+    expect(resolveDateRange('2026-02-31')).toBeNull();
+    expect(resolveDateRange('ontem')).toBeNull();
+  });
+
+  it('aceita ISO completo e ignora a hora', () => {
+    expect(
+      resolveDateRange('2026-08-01T13:45:00.000Z', '2026-08-31T09:00:00Z'),
+    ).toEqual(resolveDateRange('2026-08-01', '2026-08-31'));
+  });
+
+  it('não limita o fim a agora — período no futuro continua aberto', () => {
+    // Contrato vigente, reunião agendada e assinatura a vencer dependem disso.
+    const { lt } = resolveDateRange('2099-01-01', '2099-12-31')!;
+
+    expect(lt).toEqual(new Date('2100-01-01T00:00:00.000Z'));
+    expect(lt!.getTime()).toBeGreaterThan(Date.now());
+  });
+
+  it('expõe as strings que o SQL cru precisa', () => {
+    const range = resolveDateRange('2026-08-01', '2026-08-31')!;
+
+    expect(range.fromIso).toBe('2026-08-01');
+    expect(range.toExclusiveIso).toBe('2026-09-01');
+  });
+});
+
+describe('resolveDateRange — fuso', () => {
+  it('desloca as bordas para o fuso pedido', () => {
+    // Em São Paulo (UTC-3) o dia civil começa às 03:00 UTC.
+    const range = resolveDateRange('2026-08-01', '2026-08-31', {
+      timezone: 'America/Sao_Paulo',
+    })!;
+
+    expect(range.gte).toEqual(new Date('2026-08-01T03:00:00.000Z'));
+    expect(range.lt).toEqual(new Date('2026-09-01T03:00:00.000Z'));
+  });
+
+  /**
+   * A armadilha da coluna `@db.Date`: o Prisma manda o parâmetro como `DATE` e
+   * o trunca pela leitura UTC. Meia-noite de 01/08 em Tóquio é
+   * `2026-07-31T15:00Z`, que truncaria para 31/07 e derrubaria um dia inteiro
+   * da consulta, sem erro nenhum. Por isso `dateOnly` ignora o fuso.
+   */
+  it('mantém `dateOnly` em UTC puro, mesmo com fuso a leste', () => {
+    const range = resolveDateRange('2026-08-01', '2026-08-31', {
+      timezone: 'Asia/Tokyo',
+    })!;
+
+    expect(range.gte).toEqual(new Date('2026-07-31T15:00:00.000Z'));
+    expect(range.dateOnly.gte).toEqual(new Date('2026-08-01T00:00:00.000Z'));
+    expect(range.dateOnly.lt).toEqual(new Date('2026-09-01T00:00:00.000Z'));
+  });
+
+  it('acerta a borda na virada do horário de verão', () => {
+    // Lisboa entra no horário de verão em 29/03/2026: antes UTC+0, depois +1.
+    const range = resolveDateRange('2026-03-28', '2026-03-30', {
+      timezone: 'Europe/Lisbon',
+    })!;
+
+    expect(range.gte).toEqual(new Date('2026-03-28T00:00:00.000Z'));
+    expect(range.lt).toEqual(new Date('2026-03-30T23:00:00.000Z'));
+  });
+
+  it('cai no UTC quando o fuso é desconhecido', () => {
+    expect(
+      resolveDateRange('2026-08-01', '2026-08-31', { timezone: 'Nao/Existe' }),
+    ).toEqual(resolveDateRange('2026-08-01', '2026-08-31'));
+  });
+});
+
+describe('addIsoDays', () => {
+  it('soma dias de calendário', () => {
+    expect(addIsoDays('2026-08-31', 1)).toBe('2026-09-01');
+    expect(addIsoDays('2026-12-31', 1)).toBe('2027-01-01');
+    expect(addIsoDays('2028-02-28', 1)).toBe('2028-02-29');
+    expect(addIsoDays('2026-09-01', -1)).toBe('2026-08-31');
+  });
+});
+
+describe('dateRangeWhere', () => {
+  it('devolve {} sem período, pra espalhar ser sempre seguro', () => {
+    expect(dateRangeWhere('created_at')).toEqual({});
+    expect(dateRangeWhere('created_at', '', '')).toEqual({});
+    expect({ deleted_at: null, ...dateRangeWhere('created_at') }).toEqual({
+      deleted_at: null,
+    });
+  });
+
+  it('monta o fragmento do Prisma', () => {
+    expect(dateRangeWhere('created_at', '2026-08-01', '2026-08-31')).toEqual({
+      created_at: {
+        gte: new Date('2026-08-01T00:00:00.000Z'),
+        lt: new Date('2026-09-01T00:00:00.000Z'),
+      },
+    });
+  });
+
+  it('usa as bordas UTC puras para coluna de data', () => {
+    expect(
+      dateRangeWhere('meeting_date', '2026-08-01', '2026-08-31', {
+        dateOnly: true,
+        timezone: 'America/Sao_Paulo',
+      }),
+    ).toEqual({
+      meeting_date: {
+        gte: new Date('2026-08-01T00:00:00.000Z'),
+        lt: new Date('2026-09-01T00:00:00.000Z'),
+      },
+    });
+  });
+
+  it('omite a chave ausente em vez de pô-la como undefined', () => {
+    const where = dateRangeWhere('created_at', '2026-08-01');
+
+    expect(Object.keys(where.created_at)).toEqual(['gte']);
+    expect('lt' in where.created_at).toBe(false);
+  });
+});