@hed-hog/core 0.0.399 → 0.0.400

package/src/file/file.service.ts

@@ -1,10 +1,12 @@
 import {
   GetBucketNotificationConfigurationCommand,
+  GetObjectCommand,
   HeadBucketCommand,
   HeadObjectCommand,
   PutBucketNotificationConfigurationCommand,
   S3Client,
 } from '@aws-sdk/client-s3';
+import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
 import {
   AddPermissionCommand,
   CreateFunctionCommand,
@@ -23,6 +25,7 @@ import { PaginationDTO, PaginationService } from '@hed-hog/api-pagination';
 import { PrismaService } from '@hed-hog/api-prisma';
 import {
   BadRequestException,
+  ForbiddenException,
   forwardRef,
   Inject,
   Injectable,
@@ -31,6 +34,7 @@ import {
   OnModuleInit
 } from '@nestjs/common';
 import { JwtService } from '@nestjs/jwt';
+import { createHash } from 'crypto';
 import type { Request } from 'express';
 import { createWriteStream, promises as fs } from 'fs';
 import { tmpdir } from 'os';
@@ -44,6 +48,8 @@ import {
 } from '../integration-profile/integration-profile.utils';
 import { SettingService } from '../setting/setting.service';
 import { DeleteDTO } from './dto/delete.dto';
+import { fixMojibake } from './filename-encoding.util';
+import { MIMETYPE_SNIFF_BYTES } from './mimetype-sniff.util';
 import {
   ImageOptimizationService,
   ImageVariantFormat,
@@ -96,21 +102,13 @@ export class FileService implements OnModuleInit {
     return `${file.location}/${file.path}`;
   }
 
-  private hasMojibake(value: string): boolean {
-    return /Ã.|Â.|â[\u0080-\u00BF]/.test(value);
-  }
-
+  /**
+   * Nome que chegou com o encoding trocado (busboy entrega `originalname` em
+   * latin1, e a base ainda recebe nome importado com o mesmo defeito). A lógica
+   * mora no util porque a migration de backfill a reproduz em plpgsql.
+   */
   private normalizeUploadedFilename(filename: string): string {
-    if (!filename) {
-      return filename;
-    }
-
-    if (!this.hasMojibake(filename)) {
-      return filename;
-    }
-
-    const decoded = Buffer.from(filename, 'latin1').toString('utf8');
-    return this.hasMojibake(decoded) ? filename : decoded;
+    return filename ? fixMojibake(filename) : filename;
   }
 
   constructor(
@@ -548,6 +546,9 @@ export class FileService implements OnModuleInit {
       skipMimeValidation?: boolean;
       skipSizeValidation?: boolean;
       isPrivate?: boolean;
+      // Quem enviou. É o que permite recusar um `fileId` de outro usuário nas tools MCP
+      // (ver `assertFileUsable`); fica nulo nos caminhos internos sem usuário.
+      createdByUserId?: number | null;
     },
   ) {
 
@@ -610,6 +611,7 @@ export class FileService implements OnModuleInit {
         mimetype_id: await this.getMimeType(optimized.mimetype),
         size: optimized.buffer.length,
         is_private: options?.isPrivate ?? false,
+        created_by_user_id: options?.createdByUserId ?? null,
       },
     });
 
@@ -629,6 +631,8 @@ export class FileService implements OnModuleInit {
       skipSizeValidation?: boolean;
       // Tira o arquivo das rotas que servem por id sem autenticação.
       isPrivate?: boolean;
+      // Quem enviou. Ver a nota do mesmo campo em `upload`.
+      createdByUserId?: number | null;
       // Mesmo par maxWidth/maxHeight que `upload` aceita — só tem efeito em image/*.
       resize?: { maxWidth?: number; maxHeight?: number };
     },
@@ -652,9 +656,18 @@ export class FileService implements OnModuleInit {
     );
     // Recupera o tipo real quando o caller não informou o mimetype (default antigo era
     // application/octet-stream, que fazia imagens caírem fora da otimização e do serve).
+    // Diferente de `upload`, aqui só existe um caminho no disco — e ler o arquivo inteiro
+    // é justamente o que o branch de streaming abaixo evita para SCORM/vídeo de vários GB.
+    // Por isso o sniffing recebe só o cabeçalho, e apenas quando o caller não declarou um
+    // tipo concreto: sem isso, uma imagem enviada como application/octet-stream sem
+    // extensão no nome escapava da otimização e era gravada byte a byte.
+    const declaredMimetype = metadata?.mimetype;
+    const isGenericMimetype =
+      !declaredMimetype || declaredMimetype === 'application/octet-stream';
     const mimetype = await this.resolveEffectiveMimetype(
-      metadata?.mimetype,
+      declaredMimetype,
       originalname,
+      isGenericMimetype ? await this.readFileHeader(filePath) : undefined,
     );
 
     if (!metadata?.skipMimeValidation && !(await this.acceptMimetypes(mimetype))) {
@@ -687,6 +700,7 @@ export class FileService implements OnModuleInit {
           mimetype_id: await this.getMimeType(mimetype),
           size,
           is_private: metadata?.isPrivate ?? false,
+          created_by_user_id: metadata?.createdByUserId ?? null,
         },
       });
     }
@@ -724,20 +738,102 @@ export class FileService implements OnModuleInit {
         mimetype_id: await this.getMimeType(optimized.mimetype),
         size: optimized.buffer.length,
         is_private: metadata?.isPrivate ?? false,
+        created_by_user_id: metadata?.createdByUserId ?? null,
       },
     });
 
     return file;
   }
 
+  /**
+   * Mimetypes de imagem que `optimizeBuffer` devolve intactos por decisão de projeto
+   * (vetor não vira bitmap, GIF animado não vira quadro único). Enfileirá-los para
+   * reotimização seria custo de download e reprocessamento com resultado garantidamente
+   * nulo, então ficam fora da varredura.
+   */
+  private static readonly NON_OPTIMIZABLE_IMAGE_MIMETYPES = [
+    'image/svg+xml',
+    'image/gif',
+  ];
+
+  /**
+   * Lista as imagens armazenadas que valem uma passada por `reoptimizeFile`, para a
+   * operação em massa de reprocessamento do acervo.
+   *
+   * Devolve junto o total e a soma de bytes do filtro inteiro (não só da página), que é
+   * o que permite mostrar uma prévia antes de enfileirar dezenas de milhares de jobs.
+   * O core não conhece a fila — quem enfileira é a library `queue`, que depende deste
+   * pacote e não o contrário.
+   */
+  async findOptimizableImages(params?: {
+    /** Piso de tamanho em bytes; abaixo disso o ganho não paga o reprocessamento. */
+    minSize?: number;
+    /** Restringe a `location` exatas (ex.: `lms/xp/skills`), para rollout em ondas. */
+    locations?: string[];
+    offset?: number;
+    limit?: number;
+  }): Promise<{ ids: number[]; total: number; totalBytes: number }> {
+    const minSize = Math.max(0, Math.trunc(Number(params?.minSize) || 0));
+    const locations = (params?.locations ?? [])
+      .map((location) => String(location).trim())
+      .filter(Boolean);
+
+    const where: any = {
+      size: { gte: minSize },
+      file_mimetype: {
+        name: {
+          startsWith: 'image/',
+          notIn: FileService.NON_OPTIMIZABLE_IMAGE_MIMETYPES,
+        },
+      },
+    };
+
+    if (locations.length) {
+      where.location = { in: locations };
+    }
+
+    const [aggregate, rows] = await Promise.all([
+      this.prismaService.file.aggregate({
+        where,
+        _count: { _all: true },
+        _sum: { size: true },
+      }),
+      this.prismaService.file.findMany({
+        where,
+        select: { id: true },
+        // Ordem estável para que o enfileiramento paginado não pule nem repita linhas.
+        orderBy: { id: 'asc' },
+        skip: Math.max(0, Math.trunc(Number(params?.offset) || 0)),
+        take: Math.min(5000, Math.max(1, Math.trunc(Number(params?.limit) || 1000))),
+      }),
+    ]);
+
+    return {
+      ids: rows.map((row) => row.id),
+      total: aggregate._count._all ?? 0,
+      totalBytes: Number(aggregate._sum.size ?? 0),
+    };
+  }
+
+  /**
+   * Ganho mínimo para valer a regravação de um arquivo que já está no formato final.
+   *
+   * Recomprimir WebP sobre WebP sempre devolve alguns bytes a menos, então um limiar de
+   * "estritamente menor" nunca converge: cada passada da varredura trocaria o arquivo
+   * por um ganho irrisório e mais uma geração de perda de qualidade. Medido aqui, três
+   * passadas seguidas rendiam 10926 → 10664 → 10662 bytes — a última custou uma
+   * recompressão inteira para economizar 2 bytes.
+   */
+  private static readonly REOPTIMIZE_MIN_GAIN_RATIO = 0.1;
+
   /**
    * Re-applies the current image-optimization settings to an already-stored file,
    * rewriting it in place: the `file` record keeps the same id, so every row that
    * references it (course_image, course_lesson_video_frame, ...) stays valid without
-   * any FK juggling. Only replaces the stored object when the optimized result is
-   * strictly smaller or the mimetype changed (e.g. PNG → WebP) — this keeps the
-   * operation idempotent and avoids repeated lossy recompression. Non-image files are
-   * left untouched.
+   * any FK juggling. Only replaces the stored object when the mimetype changed
+   * (e.g. PNG → WebP) or the result is smaller by a margin that justifies the rewrite —
+   * that margin is what actually makes the operation idempotent and avoids repeated
+   * lossy recompression. Non-image files are left untouched.
    */
   async reoptimizeFile(fileId: number): Promise<{
     changed: boolean;
@@ -760,9 +856,15 @@ export class FileService implements OnModuleInit {
     );
 
     const mimetypeChanged = optimized.mimetype !== currentMimetype;
-    const smaller = optimized.buffer.length < oldSize;
-
-    if (!mimetypeChanged && !smaller) {
+    // Mudança de formato é o ganho principal (PNG → WebP) e vale por si; sem ela, só
+    // regrava quando a economia passa do limiar. `optimizeBuffer` já garante que o
+    // resultado nunca é maior que a entrada neste caminho (sem crop de alvo exato).
+    const worthRewriting =
+      oldSize > 0 &&
+      (oldSize - optimized.buffer.length) / oldSize >=
+        FileService.REOPTIMIZE_MIN_GAIN_RATIO;
+
+    if (!mimetypeChanged && !worthRewriting) {
       return {
         changed: false,
         oldSize,
@@ -850,7 +952,130 @@ export class FileService implements OnModuleInit {
     return files.map((file) => file.id);
   }
 
-  async getFiles(paginationParams: PaginationDTO) {
+  /**
+   * `ownerUserId` restringe a listagem aos arquivos enviados por aquele usuário.
+   *
+   * Existe para as tools MCP: sem ele, `core.files.list` é um índice de tudo o que
+   * qualquer empresa já subiu, incluindo o que está gravado como `is_private`. O
+   * controller REST continua chamando sem o parâmetro, porque ali a rota já é `admin`
+   * e a tela de arquivos é justamente a visão global.
+   */
+  /**
+   * Grava um stream em disco medindo, hasheando e guardando o cabeçalho de uma vez só.
+   *
+   * O upload assinado recebe o binário cru no corpo do PUT, e nada garante que venha com
+   * `Content-Length` — sem o contador abaixo, um corpo aberto encheria o disco do pod. O
+   * corte é feito em pleno voo, antes de o excedente chegar ao arquivo.
+   *
+   * Passa o cabeçalho adiante porque conferir o tipo real é obrigatório nesse caminho, e
+   * reler o arquivo depois seria uma segunda passada por nada.
+   */
+  async writeStreamToPath(
+    source: NodeJS.ReadableStream,
+    targetPath: string,
+    maxBytes: number,
+  ): Promise<{ bytes: number; sha256: string; header: Buffer }> {
+    const hash = createHash('sha256');
+    const headerChunks: Buffer[] = [];
+    let headerLength = 0;
+    let bytes = 0;
+
+    const target = createWriteStream(targetPath);
+
+    await pipeline(
+      source as any,
+      async function* (chunks: AsyncIterable<Buffer>) {
+        for await (const chunk of chunks) {
+          const buffer = Buffer.from(chunk);
+          bytes += buffer.length;
+
+          if (bytes > maxBytes) {
+            throw new BadRequestException(
+              `Upload exceeds the declared size of ${maxBytes} bytes`,
+            );
+          }
+
+          hash.update(buffer);
+
+          if (headerLength < MIMETYPE_SNIFF_BYTES) {
+            const slice = buffer.subarray(0, MIMETYPE_SNIFF_BYTES - headerLength);
+            headerChunks.push(slice);
+            headerLength += slice.length;
+          }
+
+          yield buffer;
+        }
+      },
+      target,
+    );
+
+    return {
+      bytes,
+      sha256: hash.digest('hex'),
+      header: Buffer.concat(headerChunks),
+    };
+  }
+
+  /**
+   * Conteúdo de um arquivo já armazenado, em memória.
+   *
+   * Existe para as tools que consomem os bytes sem persistir nada (importar extrato,
+   * extrair dados de uma nota com IA): elas recebem um `fileId` e precisam do arquivo,
+   * não de um stream. O teto evita que um `fileId` apontando para um SCORM de vários GB
+   * derrube o pod — quem serve arquivo grande usa `openReadStream` e não passa por aqui.
+   */
+  async bufferById(fileId: number, maxBytes: number): Promise<Buffer> {
+    const { stream } = await this.openReadStreamById(fileId);
+    const chunks: Buffer[] = [];
+    let total = 0;
+
+    for await (const chunk of stream as AsyncIterable<Buffer>) {
+      total += chunk.length;
+
+      if (total > maxBytes) {
+        (stream as any).destroy?.();
+        throw new BadRequestException(
+          `File ${fileId} is larger than the ${maxBytes} bytes this operation can load`,
+        );
+      }
+
+      chunks.push(Buffer.from(chunk));
+    }
+
+    return Buffer.concat(chunks);
+  }
+
+  /**
+   * Nome do mimetype de um arquivo.
+   *
+   * `get()` e `upload()` devolvem a linha crua, sem a relação, e cada chamador que
+   * precisava do tipo vinha refazendo o `include` por conta. Como o cache de
+   * `getMimeType` é id-por-nome, este é o inverso dele e sai do mesmo mapa quando já
+   * tiver sido consultado.
+   */
+  async mimetypeNameById(mimetypeId: number): Promise<string> {
+    const cached = Object.entries(this.mimetypes).find(
+      ([, id]) => id === mimetypeId,
+    );
+
+    if (cached) {
+      return cached[0];
+    }
+
+    const row = await this.prismaService.file_mimetype.findUnique({
+      where: { id: mimetypeId },
+      select: { name: true },
+    });
+
+    if (row?.name) {
+      this.mimetypes[row.name] = mimetypeId;
+      return row.name;
+    }
+
+    return 'application/octet-stream';
+  }
+
+  async getFiles(paginationParams: PaginationDTO, ownerUserId?: number) {
     const fields = ['filename', 'path'];
     const OR = this.prismaService.createInsensitiveSearch(
       fields,
@@ -863,11 +1088,84 @@ export class FileService implements OnModuleInit {
       {
         where: {
           OR,
+          ...(ownerUserId ? { created_by_user_id: ownerUserId } : {}),
         },
       },
     );
   }
 
+  /**
+   * Papéis que enxergam qualquer arquivo. Os mesmos que já governam as rotas de arquivo
+   * em `route.yaml` — quem administra o acervo pela tela também o administra pelo MCP.
+   */
+  private static readonly FILE_ADMIN_ROLES = ['admin', 'admin-access'];
+
+  /** Cache curto de papéis, no mesmo espírito do McpPermissionService. */
+  private readonly fileAdminCache = new Map<number, { value: boolean; at: number }>();
+  private static readonly FILE_ADMIN_CACHE_TTL_MS = 30_000;
+
+  async isFileAdmin(userId: number): Promise<boolean> {
+    const cached = this.fileAdminCache.get(userId);
+
+    if (cached && Date.now() - cached.at < FileService.FILE_ADMIN_CACHE_TTL_MS) {
+      return cached.value;
+    }
+
+    const found = await this.prismaService.role_user.findFirst({
+      where: {
+        user_id: userId,
+        role: { slug: { in: FileService.FILE_ADMIN_ROLES } },
+      },
+      select: { role_id: true },
+    });
+
+    const value = Boolean(found);
+    this.fileAdminCache.set(userId, { value, at: Date.now() });
+
+    return value;
+  }
+
+  /**
+   * Porteiro do `fileId` vindo de fora: só o dono usa um arquivo, e quem administra o
+   * acervo usa qualquer um.
+   *
+   * Sem isto, apontar um `fileId` numa tool seria enumerar — id de arquivo é sequencial,
+   * exatamente o motivo pelo qual `is_private` existe. Arquivo anterior a esta coluna
+   * (ou gravado por cron/seed/webhook) fica com dono nulo e só o admin alcança: não dá
+   * para provar de quem ele é, e adivinhar a favor do chamador seria abrir a porta que
+   * este método fecha.
+   */
+  async assertFileUsable(fileId: number, userId: number) {
+    if (!Number.isInteger(fileId) || fileId <= 0) {
+      throw new BadRequestException(`Invalid file id: ${fileId}`);
+    }
+
+    const file = await this.prismaService.file.findUnique({
+      where: { id: fileId },
+      include: { file_mimetype: true },
+    });
+
+    // Mesma resposta para inexistente e para alheio seria o ideal contra enumeração, mas
+    // `get()` já responde 404 com o id, e divergir aqui só confundiria quem integra.
+    if (!file) {
+      throw new NotFoundException(`File not found: ${fileId}`);
+    }
+
+    if (file.created_by_user_id === userId) {
+      return file;
+    }
+
+    if (await this.isFileAdmin(userId)) {
+      return file;
+    }
+
+    throw new ForbiddenException(
+      file.created_by_user_id === null
+        ? `File ${fileId} has no recorded owner and can only be used by an administrator`
+        : `File ${fileId} belongs to another user`,
+    );
+  }
+
   async get(fileId: number) {
     const file = await this.prismaService.file.findUnique({
       where: { id: fileId },
@@ -1028,19 +1326,45 @@ export class FileService implements OnModuleInit {
     return undefined;
   }
 
+  /**
+   * Resolve o `file` cujo `resolveProviderPath` (location + path, ou path já combinado) bate com
+   * o `filepath` embutido no token de download — é o inverso de `resolveProviderPath`.
+   *
+   * Bug corrigido (relatado como "Token de download inválido ou expirado" no storage local):
+   * `tempURLById` assina o token com `resolveProviderPath(file)` (ex.:
+   * "class-assignment-tasks/abc123.pdf", já com o prefixo de `location`), mas o upload local/S3
+   * grava só o basename em `file.path` ("abc123.pdf") e o `location` separado em outra coluna.
+   * Um `findFirst({ where: { path: filepath } })` direto nunca batia para esses arquivos — sempre
+   * caía no `catch` abaixo e mostrava a mensagem genérica de token inválido, mesmo com o token
+   * (e o arquivo) perfeitamente válidos. S3 mascarava isso porque `S3Provider.tempURL` devolve uma
+   * URL assinada direto do bucket, sem passar por este método.
+   */
+  private async findFileByResolvedPath(filepath: string) {
+    const bySameValue = await this.prismaService.file.findFirst({
+      where: { path: filepath },
+      include: { file_mimetype: true },
+    });
+    if (bySameValue) return bySameValue;
+
+    const slashIndex = filepath.lastIndexOf('/');
+    if (slashIndex === -1) return null;
+
+    return this.prismaService.file.findFirst({
+      where: {
+        location: filepath.slice(0, slashIndex),
+        path: filepath.slice(slashIndex + 1),
+      },
+      include: { file_mimetype: true },
+    });
+  }
+
   async download(locale:string, token: string) {
     try {
       const { filepath } = this.jwtService.verify(token, {
         secret: process.env.JWT_SECRET,
       });
 
-      // Buscar o arquivo no banco para pegar nome original e mimetype
-      const file = await this.prismaService.file.findFirst({
-        where: { path: filepath },
-        include: {
-          file_mimetype: true,
-        },
-      });
+      const file = await this.findFileByResolvedPath(filepath);
 
       if (!file) {
         throw new NotFoundException(getLocaleText('file.download.not_found', locale, `Not found: ${filepath}`));
@@ -1186,6 +1510,30 @@ export class FileService implements OnModuleInit {
     return map[ext] ?? null;
   }
 
+  /**
+   * Lê só o começo do arquivo, o bastante para o sharp reconhecer o formato pelo
+   * cabeçalho. Existe para o sniffing de `uploadFromPath`, que não pode chamar
+   * `fs.readFile`: o mesmo caminho recebe pacotes SCORM e vídeos de vários GB, e
+   * carregá-los inteiros estoura o limite de Buffer. Devolve `undefined` em qualquer
+   * falha de leitura — quem chama já trata a ausência do buffer.
+   */
+  private async readFileHeader(
+    filePath: string,
+    bytes = 64 * 1024,
+  ): Promise<Buffer | undefined> {
+    let handle: fs.FileHandle | undefined;
+    try {
+      handle = await fs.open(filePath, 'r');
+      const buffer = Buffer.alloc(bytes);
+      const { bytesRead } = await handle.read(buffer, 0, bytes, 0);
+      return bytesRead > 0 ? buffer.subarray(0, bytesRead) : undefined;
+    } catch {
+      return undefined;
+    } finally {
+      await handle?.close().catch(() => undefined);
+    }
+  }
+
   /**
    * Resolves the MIME type to persist for an upload. When the incoming mimetype is
    * generic (application/octet-stream or empty), recovers the real image type from
@@ -1197,29 +1545,7 @@ export class FileService implements OnModuleInit {
     name: string,
     buffer?: Buffer,
   ): Promise<string> {
-    if (mimetype && mimetype.startsWith('image/')) {
-      // O mimetype que chega do navegador vem da EXTENSÃO do arquivo, não do
-      // conteúdo: um PNG renomeado para `.svg` é anunciado como `image/svg+xml`.
-      // Gravar isso faz o endpoint de imagem servir bytes PNG sob Content-Type
-      // de SVG e, com o `nosniff` que a API envia, o navegador não corrige
-      // sozinho — a imagem simplesmente não renderiza, sem erro nenhum.
-      // Com os bytes em mãos, quem decide é a assinatura do arquivo.
-      if (buffer) {
-        const sniffed =
-          await this.imageOptimizationService.detectImageMimetype(buffer);
-        // Só sobrepõe quando o sniffing reconheceu o formato: um `null` significa
-        // que o sharp não entendeu o buffer, e aí o declarado ainda é o melhor
-        // palpite disponível.
-        if (sniffed && sniffed !== mimetype) {
-          this.logger.warn(
-            `Upload "${name}" foi anunciado como ${mimetype}, mas os bytes são ${sniffed}. Persistindo o tipo real.`,
-          );
-          return sniffed;
-        }
-      }
-
-      return mimetype;
-    }
+    if (mimetype && mimetype.startsWith('image/')) return mimetype;
     // Tipos concretos não-imagem (video, pdf, ...) são mantidos como estão.
     if (mimetype && mimetype !== 'application/octet-stream') return mimetype;
 
@@ -1514,6 +1840,17 @@ export class FileService implements OnModuleInit {
     return url;
   }
 
+  /** Par de `tempURLById`, pela mesma razão: `path` cru resolve para NoSuchKey no S3. */
+  async tempOpenURLById(fileId: number, expires = 3600) {
+    const url = await this.tempURLById(fileId, expires);
+
+    if (typeof url === 'string') {
+      return url.replace('/file/download/', '/file/open/');
+    }
+
+    return url;
+  }
+
   async getTemporaryCredentials(params: {
     accessKeyId: string;
     secretAccessKey: string;
@@ -1596,6 +1933,49 @@ export class FileService implements OnModuleInit {
     };
   }
 
+  /**
+   * URL assinada de um objeto em bucket avulso.
+   *
+   * O `getFileUrl` do provider resolve arquivos do acervo, que vivem no destino
+   * ativo do core. Este metodo serve para os buckets que outras libraries
+   * configuram por conta propria — o Studio grava no perfil de armazenamento
+   * dele, que pode nao ser o mesmo — e por isso recebe as credenciais e o bucket
+   * de fora, como o `headS3Object` ao lado.
+   */
+  async signS3Object(params: {
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken?: string;
+    region: string;
+    bucket: string;
+    key: string;
+    expiresInSeconds?: number;
+    downloadFileName?: string;
+  }): Promise<string> {
+    const s3 = new S3Client({
+      region: params.region,
+      credentials: {
+        accessKeyId: params.accessKeyId,
+        secretAccessKey: params.secretAccessKey,
+        ...(params.sessionToken ? { sessionToken: params.sessionToken } : {}),
+      },
+    });
+
+    const command = new GetObjectCommand({
+      Bucket: params.bucket,
+      Key: params.key,
+      ...(params.downloadFileName
+        ? {
+            ResponseContentDisposition: `attachment; filename="${params.downloadFileName.replace(/"/g, '')}"`,
+          }
+        : {}),
+    });
+
+    return getSignedUrl(s3 as any, command, {
+      expiresIn: params.expiresInSeconds ?? 900,
+    });
+  }
+
   async headS3Bucket(params: {
     accessKeyId: string;
     secretAccessKey: string;

package/src/file/filename-encoding.util.spec.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from '@jest/globals';
+import { fixMojibake, hasMojibake } from './filename-encoding.util';
+
+/**
+ * Inverso exato do que o util desfaz: escreve o texto em UTF-8 e lê os bytes
+ * como Latin-1. É como o nome se quebra de verdade, e aplicá-lo duas vezes
+ * reproduz a camada dupla que existe na base (file id 19768 em produção).
+ */
+const breakEncoding = (value: string): string =>
+  Buffer.from(value, 'utf8').toString('latin1');
+
+describe('fixMojibake', () => {
+  it('desfaz uma camada', () => {
+    expect(fixMojibake('Introdução ao JavaScript.zip')).toBe(
+      'Introdução ao JavaScript.zip',
+    );
+  });
+
+  it('desfaz a camada dupla que veio da importação', () => {
+    const original = '04_Aula - Introdução ao JavaScript - Básico I.zip';
+    const broken = breakEncoding(breakEncoding(original));
+
+    expect(broken).not.toBe(original);
+    expect(fixMojibake(broken)).toBe(original);
+  });
+
+  it('recupera caractere de três bytes, como o travessão', () => {
+    const original = 'Curso 1 — Unidade Biomassa Sul.pdf';
+
+    expect(fixMojibake(breakEncoding(original))).toBe(original);
+  });
+
+  it('não mexe em nome já correto', () => {
+    expect(fixMojibake('Introdução ao JavaScript.zip')).toBe(
+      'Introdução ao JavaScript.zip',
+    );
+  });
+
+  /**
+   * O nome casa o padrão por causa do "ÃO", mas os bytes Latin-1 (C7 C3 4F) não
+   * formam UTF-8. Converter aqui destruiria um nome que está certo.
+   */
+  it('preserva nome em caixa alta que casa o padrão sem ser mojibake', () => {
+    expect(hasMojibake('MANUTENÇÃO PREVENTIVA.pdf')).toBe(true);
+    expect(fixMojibake('MANUTENÇÃO PREVENTIVA.pdf')).toBe(
+      'MANUTENÇÃO PREVENTIVA.pdf',
+    );
+  });
+
+  it('preserva vazio e ASCII puro', () => {
+    expect(fixMojibake('')).toBe('');
+    expect(fixMojibake('relatorio-2026.pdf')).toBe('relatorio-2026.pdf');
+  });
+});