@hed-hog/core 0.0.399 → 0.0.401

package/src/file/file-upload-ticket.service.ts

@@ -0,0 +1,513 @@
+import { Prisma, PrismaService } from '@hed-hog/api-prisma';
+import {
+  BadRequestException,
+  forwardRef,
+  Inject,
+  Injectable,
+  Logger,
+  NotFoundException,
+} from '@nestjs/common';
+import { JwtService } from '@nestjs/jwt';
+import { createHash } from 'crypto';
+import { SettingService } from '../setting/setting.service';
+import { FileService } from './file.service';
+import { findMimetypeConflict, MIMETYPE_SNIFF_BYTES } from './mimetype-sniff.util';
+
+/** Tamanho, hash e cabeçalho — o suficiente para validar sem carregar o arquivo. */
+export interface UploadedContentDigest {
+  bytes: number;
+  sha256: string;
+  header: Buffer;
+}
+
+/**
+ * Upload cujo binário não viaja dentro da chamada.
+ *
+ * O cliente abre um ticket, manda os bytes por fora (um PUT assinado, ou em partes quando
+ * não consegue falar HTTP) e só então usa o `fileId` na tool que precisa do arquivo. O
+ * ticket é o que amarra esse vaivém a um usuário, a um nome, a um mimetype e a um
+ * tamanho declarados — sem ele o endpoint de upload seria uma porta aberta, já que ele
+ * responde sem sessão, autenticado apenas pelo token.
+ *
+ * Por que não uma URL pré-assinada do próprio bucket: nenhum dos cinco providers
+ * (`s3`, `spaces`, `gcs`, `abs`, `local`) tem presign de escrita hoje — `getSignedUrl` só
+ * aparece com `GetObjectCommand` —, o provider `local` do dev não teria caminho nenhum, e
+ * validar o mimetype pelo conteúdo só seria possível depois do objeto já estar no bucket.
+ * O PUT assinado da própria API resolve os cinco de uma vez e mantém a validação antes da
+ * gravação. Os bytes ainda passam pela API, mas o objetivo era tirá-los da conversa.
+ */
+
+export type UploadTicketMode = 'signed_url' | 'chunked';
+
+export interface CreateUploadTicketParams {
+  userId: number;
+  fileName: string;
+  mimeType: string;
+  sizeBytes: number;
+  destination?: string;
+  isPrivate?: boolean;
+  sha256?: string;
+  idempotencyKey?: string;
+  mode: UploadTicketMode;
+}
+
+const DEFAULT_UPLOAD_TTL_SECONDS = 900;
+const DEFAULT_CHUNK_BYTES = 65536;
+/** Onde caem os uploads que ainda não têm dono no domínio (o título, a tarefa, a página). */
+const DEFAULT_DESTINATION = 'mcp/uploads';
+
+@Injectable()
+export class FileUploadTicketService {
+  private readonly logger = new Logger(FileUploadTicketService.name);
+
+  constructor(
+    private readonly prismaService: PrismaService,
+    private readonly jwtService: JwtService,
+    @Inject(forwardRef(() => SettingService))
+    private readonly settingService: SettingService,
+    @Inject(forwardRef(() => FileService))
+    private readonly fileService: FileService,
+  ) {}
+
+  private async limits() {
+    const settings = await this.settingService.getSettingValues([
+      'storage-max-size',
+      'storage-upload-url-ttl',
+      'mcp-upload-chunk-bytes',
+    ]);
+
+    return {
+      maxBytes: Number(settings['storage-max-size']) || 10485760,
+      ttlSeconds:
+        Number(settings['storage-upload-url-ttl']) || DEFAULT_UPLOAD_TTL_SECONDS,
+      chunkBytes: Number(settings['mcp-upload-chunk-bytes']) || DEFAULT_CHUNK_BYTES,
+    };
+  }
+
+  /**
+   * Abre o ticket. Repetir a mesma `idempotencyKey` devolve o ticket anterior em vez de
+   * abrir outro — o retry de um cliente que não viu a resposta não deve render dois
+   * uploads nem dois arquivos.
+   */
+  async create(params: CreateUploadTicketParams) {
+    const { maxBytes, ttlSeconds, chunkBytes } = await this.limits();
+
+    if (!params.fileName?.trim()) {
+      throw new BadRequestException(`fileName is required`);
+    }
+
+    if (!params.mimeType?.trim()) {
+      throw new BadRequestException(`mimeType is required`);
+    }
+
+    if (!Number.isInteger(params.sizeBytes) || params.sizeBytes <= 0) {
+      throw new BadRequestException(`sizeBytes must be a positive integer`);
+    }
+
+    if (params.sizeBytes > maxBytes) {
+      throw new BadRequestException(
+        `File too large: ${params.sizeBytes} bytes. The storage-max-size setting allows ${maxBytes}.`,
+      );
+    }
+
+    // Barra o tipo já na abertura: deixar para o fim faria o cliente subir o arquivo
+    // inteiro para só então descobrir que ele nunca seria aceito.
+    if (!(await this.fileService.acceptMimetypes(params.mimeType))) {
+      throw new BadRequestException(`Invalid file type: ${params.mimeType}`);
+    }
+
+    if (params.sha256 && !/^[0-9a-f]{64}$/i.test(params.sha256)) {
+      throw new BadRequestException(`sha256 must be 64 hexadecimal characters`);
+    }
+
+    if (params.idempotencyKey) {
+      const existing = await this.prismaService.file_upload_ticket.findFirst({
+        where: {
+          user_id: params.userId,
+          idempotency_key: params.idempotencyKey,
+        },
+      });
+
+      if (existing) {
+        return { ticket: existing, chunkBytes, reused: true };
+      }
+    }
+
+    // Tipado como Unchecked de propósito: extrair o literal para uma variável faz o
+    // TypeScript perder a união discriminada do Prisma, e `user_id` (escalar, e não a
+    // relação `user`) passa a bater na variante Checked, onde ele é `never`.
+    const data: Prisma.file_upload_ticketUncheckedCreateInput = {
+      user_id: params.userId,
+      filename: params.fileName.trim().slice(0, 255),
+      mimetype: params.mimeType.trim(),
+      size_bytes: params.sizeBytes,
+      destination: (params.destination || DEFAULT_DESTINATION).slice(0, 255),
+      is_private: params.isPrivate ?? false,
+      sha256: params.sha256 ? params.sha256.toLowerCase() : null,
+      mode: params.mode,
+      status: 'pending' as const,
+      idempotency_key: params.idempotencyKey || null,
+      expires_at: new Date(Date.now() + ttlSeconds * 1000),
+    };
+
+    try {
+      const ticket = await this.prismaService.file_upload_ticket.create({ data });
+      return { ticket, chunkBytes, reused: false };
+    } catch (error: any) {
+      // A unicidade de (user_id, idempotency_key) é um índice PARCIAL, e o Prisma não
+      // modela índice parcial — ele não aparece no schema e o cliente não o conhece.
+      // A garantia continua sendo do Postgres, mas a violação chega aqui como P2002 cru
+      // em vez de ser evitada pelo `findFirst` acima, que perde a corrida por milissegundos.
+      if (error?.code === 'P2002' && params.idempotencyKey) {
+        const existing = await this.prismaService.file_upload_ticket.findFirst({
+          where: {
+            user_id: params.userId,
+            idempotency_key: params.idempotencyKey,
+          },
+        });
+
+        if (existing) {
+          return { ticket: existing, chunkBytes, reused: true };
+        }
+      }
+
+      throw error;
+    }
+  }
+
+  /**
+   * Token do PUT assinado. Carrega só o id do ticket: tudo o mais (usuário, tamanho,
+   * tipo, validade) é lido da linha, que é a fonte da verdade e pode ser invalidada.
+   */
+  signUploadToken(ticketId: number, ttlSeconds: number): string {
+    return this.jwtService.sign(
+      { t: 'file-upload', ticketId },
+      {
+        secret: process.env.JWT_SECRET,
+        expiresIn: `${Math.max(1, Math.floor(ttlSeconds))}s`,
+      },
+    );
+  }
+
+  async buildUploadUrl(ticketId: number, req?: any) {
+    const { ttlSeconds } = await this.limits();
+    const token = this.signUploadToken(ticketId, ttlSeconds);
+    const origin = await this.fileService.resolvePublicBaseUrl(
+      req ?? ({ protocol: 'https', get: () => '' } as any),
+    );
+
+    return `${origin}/file/upload/${encodeURIComponent(token)}`;
+  }
+
+  /** Lê o ticket do token, sem consumi-lo. */
+  async resolveTicketFromToken(token: string) {
+    let payload: any;
+
+    try {
+      payload = this.jwtService.verify(token, { secret: process.env.JWT_SECRET });
+    } catch {
+      throw new BadRequestException(`Invalid or expired upload token`);
+    }
+
+    if (payload?.t !== 'file-upload' || !payload?.ticketId) {
+      throw new BadRequestException(`Token is not an upload token`);
+    }
+
+    const ticket = await this.prismaService.file_upload_ticket.findUnique({
+      where: { id: Number(payload.ticketId) },
+    });
+
+    if (!ticket) {
+      throw new NotFoundException(`Upload ticket not found`);
+    }
+
+    return ticket;
+  }
+
+  /**
+   * Marca o ticket como consumido, e só devolve `true` para quem venceu a corrida.
+   *
+   * O `updateMany` condicional é o que dá uso único sem abrir transação: dois PUTs
+   * simultâneos com o mesmo token entram aqui juntos, o Postgres serializa o UPDATE e o
+   * segundo enxerga `count: 0` porque o status já não é `pending`.
+   */
+  async claim(ticketId: number): Promise<boolean> {
+    const claimed = await this.prismaService.file_upload_ticket.updateMany({
+      where: {
+        id: ticketId,
+        status: 'pending',
+        expires_at: { gt: new Date() },
+      },
+      data: { status: 'completed', consumed_at: new Date() },
+    });
+
+    return claimed.count === 1;
+  }
+
+  async markFailed(ticketId: number) {
+    await this.prismaService.file_upload_ticket
+      .update({ where: { id: ticketId }, data: { status: 'failed' } })
+      .catch((error: any) =>
+        this.logger.warn(`Failed to mark upload ticket ${ticketId}: ${error.message}`),
+      );
+  }
+
+  async attachFile(ticketId: number, fileId: number) {
+    await this.prismaService.file_upload_ticket.update({
+      where: { id: ticketId },
+      data: { file_id: fileId },
+    });
+  }
+
+  /**
+   * O que basta saber sobre o conteúdo para conferi-lo contra o ticket.
+   *
+   * Separado do buffer de propósito: o PUT assinado escreve direto no disco e nunca tem o
+   * arquivo inteiro em memória, então ele produz estes três valores durante o stream. O
+   * modo em partes, que monta o buffer de qualquer forma, deriva os mesmos com
+   * `describeUploadedBuffer`.
+   */
+  static describeUploadedBuffer(buffer: Buffer): UploadedContentDigest {
+    return {
+      bytes: buffer.length,
+      sha256: createHash('sha256').update(buffer).digest('hex'),
+      header: buffer.subarray(0, MIMETYPE_SNIFF_BYTES),
+    };
+  }
+
+  /**
+   * Confere tamanho, integridade e o tipo real contra o declarado.
+   *
+   * Roda para os dois modos, no ponto em que os bytes já existem por inteiro — é aqui que
+   * um `.exe` declarado como `application/pdf` é recusado, coisa que a validação por
+   * header nunca pegaria, e que o `storage-accept-mimetype` sozinho também não pega
+   * porque ele só olha a string que o cliente mandou.
+   */
+  async assertContentMatchesTicket(ticket: any, digest: UploadedContentDigest) {
+    const { maxBytes } = await this.limits();
+
+    if (digest.bytes === 0) {
+      throw new BadRequestException(`Uploaded content is empty`);
+    }
+
+    if (digest.bytes > maxBytes) {
+      throw new BadRequestException(
+        `File too large: ${digest.bytes} bytes. The storage-max-size setting allows ${maxBytes}.`,
+      );
+    }
+
+    if (digest.bytes !== ticket.size_bytes) {
+      throw new BadRequestException(
+        `Uploaded ${digest.bytes} bytes but the ticket declared ${ticket.size_bytes}`,
+      );
+    }
+
+    if (ticket.sha256 && digest.sha256 !== ticket.sha256) {
+      throw new BadRequestException(
+        `sha256 mismatch: declared ${ticket.sha256}, uploaded content hashes to ${digest.sha256}`,
+      );
+    }
+
+    const conflict = findMimetypeConflict(ticket.mimetype, digest.header);
+
+    if (conflict) {
+      throw new BadRequestException(
+        `Declared mimeType ${ticket.mimetype} but the content is ${conflict}`,
+      );
+    }
+  }
+
+  // ── Modo em partes ─────────────────────────────────────────────────────────
+
+  /**
+   * Grava uma parte. Reenviar o mesmo índice sobrescreve, para que o retry de uma parte
+   * perdida não duplique nem desalinhe a montagem.
+   */
+  async appendChunk(
+    uploadId: number,
+    index: number,
+    chunkBase64: string,
+    userId: number,
+  ) {
+    const ticket = await this.requireOwnPendingTicket(uploadId, userId);
+
+    if (ticket.mode !== 'chunked') {
+      throw new BadRequestException(
+        `Upload ${uploadId} was opened for direct upload; use the signed URL instead of append`,
+      );
+    }
+
+    if (!Number.isInteger(index) || index < 0) {
+      throw new BadRequestException(`index must be a non-negative integer`);
+    }
+
+    if (!chunkBase64) {
+      throw new BadRequestException(`chunkBase64 is required`);
+    }
+
+    const { chunkBytes } = await this.limits();
+    const data = Buffer.from(chunkBase64, 'base64');
+
+    if (data.length === 0) {
+      throw new BadRequestException(`chunkBase64 decoded to zero bytes`);
+    }
+
+    if (data.length > chunkBytes) {
+      throw new BadRequestException(
+        `Chunk ${index} has ${data.length} bytes, above the ${chunkBytes} allowed by the mcp-upload-chunk-bytes setting`,
+      );
+    }
+
+    await this.prismaService.file_upload_chunk.upsert({
+      where: { ticket_id_index: { ticket_id: uploadId, index } },
+      create: { ticket_id: uploadId, index, data },
+      update: { data },
+    });
+
+    const received = await this.prismaService.file_upload_chunk.count({
+      where: { ticket_id: uploadId },
+    });
+
+    const expected = Math.ceil(ticket.size_bytes / chunkBytes);
+
+    return {
+      uploadId,
+      index,
+      received,
+      expected,
+      remaining: Math.max(0, expected - received),
+    };
+  }
+
+  private async requireOwnPendingTicket(uploadId: number, userId: number) {
+    const ticket = await this.prismaService.file_upload_ticket.findUnique({
+      where: { id: uploadId },
+    });
+
+    if (!ticket) {
+      throw new NotFoundException(`Upload ticket not found: ${uploadId}`);
+    }
+
+    // O ticket é do usuário que o abriu, sem exceção para admin: ele não é um recurso
+    // administrável, é um passo intermediário de quem está subindo o arquivo.
+    if (ticket.user_id !== userId) {
+      throw new NotFoundException(`Upload ticket not found: ${uploadId}`);
+    }
+
+    if (ticket.status !== 'pending') {
+      throw new BadRequestException(
+        `Upload ticket ${uploadId} is ${ticket.status} and cannot receive more content`,
+      );
+    }
+
+    if (ticket.expires_at.getTime() <= Date.now()) {
+      throw new BadRequestException(`Upload ticket ${uploadId} has expired`);
+    }
+
+    return ticket;
+  }
+
+  /**
+   * Fecha o upload e devolve o arquivo.
+   *
+   * Serve aos dois modos e é idempotente: um ticket que já gerou arquivo devolve o mesmo
+   * `fileId` em vez de erro, porque o retry de um `complete` cuja resposta se perdeu não
+   * pode render um segundo arquivo.
+   */
+  async complete(uploadId: number, userId: number) {
+    const ticket = await this.prismaService.file_upload_ticket.findUnique({
+      where: { id: uploadId },
+    });
+
+    if (!ticket || ticket.user_id !== userId) {
+      throw new NotFoundException(`Upload ticket not found: ${uploadId}`);
+    }
+
+    if (ticket.file_id) {
+      return this.fileService.get(ticket.file_id);
+    }
+
+    if (ticket.mode === 'signed_url') {
+      throw new BadRequestException(
+        ticket.status === 'pending'
+          ? `Upload ticket ${uploadId} has no content yet; PUT the file to the signed URL first`
+          : `Upload ticket ${uploadId} is ${ticket.status} and produced no file`,
+      );
+    }
+
+    await this.requireOwnPendingTicket(uploadId, userId);
+
+    // Reivindica antes de montar: dois `complete` simultâneos entrariam os dois no
+    // `uploadFromPath` e gerariam dois arquivos para o mesmo ticket.
+    if (!(await this.claim(uploadId))) {
+      const current = await this.prismaService.file_upload_ticket.findUnique({
+        where: { id: uploadId },
+      });
+
+      if (current?.file_id) {
+        return this.fileService.get(current.file_id);
+      }
+
+      throw new BadRequestException(`Upload ticket ${uploadId} is already being completed`);
+    }
+
+    try {
+      const chunks = await this.prismaService.file_upload_chunk.findMany({
+        where: { ticket_id: uploadId },
+        orderBy: { index: 'asc' },
+      });
+
+      if (chunks.length === 0) {
+        throw new BadRequestException(`Upload ticket ${uploadId} has no chunks`);
+      }
+
+      // Índice faltando significa parte perdida no caminho; montar assim geraria um
+      // arquivo silenciosamente corrompido, que é pior do que recusar.
+      chunks.forEach((chunk, position) => {
+        if (chunk.index !== position) {
+          throw new BadRequestException(
+            `Upload ticket ${uploadId} is missing chunk ${position}`,
+          );
+        }
+      });
+
+      const buffer = Buffer.concat(chunks.map((chunk) => Buffer.from(chunk.data)));
+
+      await this.assertContentMatchesTicket(
+        ticket,
+        FileUploadTicketService.describeUploadedBuffer(buffer),
+      );
+
+      const file = await this.fileService.upload(
+        ticket.destination,
+        {
+          fieldname: 'file',
+          originalname: ticket.filename,
+          encoding: '7bit',
+          mimetype: ticket.mimetype,
+          size: buffer.length,
+          destination: '',
+          filename: ticket.filename,
+          path: '',
+          buffer,
+        },
+        undefined,
+        {
+          isPrivate: ticket.is_private,
+          createdByUserId: ticket.user_id,
+        },
+      );
+
+      await this.attachFile(uploadId, file.id);
+      // As partes já cumpriram o papel e somam o arquivo inteiro no banco.
+      await this.prismaService.file_upload_chunk.deleteMany({
+        where: { ticket_id: uploadId },
+      });
+
+      return file;
+    } catch (error) {
+      await this.markFailed(uploadId);
+      throw error;
+    }
+  }
+}

package/src/file/file.controller.ts

@@ -31,6 +31,7 @@ import { join } from 'path';
 import { DeleteDTO } from './dto/delete.dto';
 import { UploadFileDTO } from './dto/upload.dto';
 import { FileService } from './file.service';
+import { FileUploadTicketService } from './file-upload-ticket.service';
 
 // Teto duro do multipart, avaliado enquanto o corpo ainda está chegando. É
 // diferente do setting `storage-max-size`, que só roda depois do arquivo inteiro
@@ -46,6 +47,8 @@ export class FileController {
   constructor(
     @Inject(forwardRef(() => FileService))
     private readonly fileService: FileService,
+    @Inject(forwardRef(() => FileUploadTicketService))
+    private readonly uploadTickets: FileUploadTicketService,
   ) {}
 
   private renderDownloadErrorHtml(locale: string, error: any): string {
@@ -123,6 +126,68 @@ export class FileController {
     };
   }
 
+  /**
+   * Recebe o binário de um upload aberto por `core.files.create-upload-url`.
+   *
+   * É `@Public()` porque a autorização é o próprio token: ele é assinado, vale por
+   * minutos, aponta para um único ticket e só serve uma vez. Existe para tirar o arquivo
+   * do corpo da chamada MCP — base64 de um PDF de 131 KB já passa de 175 mil caracteres,
+   * acima do que o modelo consegue emitir.
+   *
+   * O corpo é o binário cru, sem multipart: `express.json` não o toca porque o
+   * content-type não é JSON, e o stream vai direto para um arquivo temporário com
+   * contador de bytes, que é o que impede um corpo sem `Content-Length` de encher a
+   * memória do pod.
+   */
+  @Public()
+  @Put('upload/:token')
+  async uploadSigned(@Param('token') token: string, @Req() req: Request) {
+    const ticket = await this.uploadTickets.resolveTicketFromToken(token);
+
+    // Reivindica ANTES de gravar: dois PUTs simultâneos com o mesmo token subiriam os
+    // dois e deixariam um blob órfão no storage, além de dois registros para um ticket.
+    if (!(await this.uploadTickets.claim(ticket.id))) {
+      throw new BadRequestException(
+        `Upload token already used or expired for ticket ${ticket.id}`,
+      );
+    }
+
+    const tempPath = join(tmpdir(), `hedhog-upload-${ticket.id}-${Date.now()}`);
+
+    try {
+      // Uma passada só: grava, conta, hasheia e guarda o cabeçalho para o sniff.
+      const digest = await this.fileService.writeStreamToPath(
+        req as any,
+        tempPath,
+        ticket.size_bytes,
+      );
+
+      await this.uploadTickets.assertContentMatchesTicket(ticket, digest);
+
+      const file = await this.fileService.uploadFromPath(ticket.destination, tempPath, {
+        originalname: ticket.filename,
+        mimetype: ticket.mimetype,
+        size: digest.bytes,
+        isPrivate: ticket.is_private,
+        createdByUserId: ticket.user_id,
+      });
+
+      await this.uploadTickets.attachFile(ticket.id, file.id);
+
+      return {
+        uploadId: ticket.id,
+        fileId: file.id,
+        filename: file.filename,
+        size: file.size,
+      };
+    } catch (error) {
+      await this.uploadTickets.markFailed(ticket.id);
+      throw error;
+    } finally {
+      await rm(tempPath, { force: true }).catch(() => undefined);
+    }
+  }
+
   @Public()
   @Get('download/:token')
   async download(

package/src/file/file.module.ts

@@ -5,7 +5,9 @@ import { JwtModule } from '@nestjs/jwt';
 import { SettingModule } from '../setting/setting.module';
 import { FileController } from './file.controller';
 import { FileService } from './file.service';
+import { FileUploadTicketService } from './file-upload-ticket.service';
 import { ImageOptimizationService } from './image-optimization.service';
+import { McpFileSourceService } from './mcp-file-source.service';
 
 @Module({
   imports: [
@@ -16,8 +18,18 @@ import { ImageOptimizationService } from './image-optimization.service';
       JwtModule,
     ),
   ],
-  providers: [FileService, ImageOptimizationService],
-  exports: [FileService, ImageOptimizationService],
+  providers: [
+    FileService,
+    ImageOptimizationService,
+    FileUploadTicketService,
+    McpFileSourceService,
+  ],
+  exports: [
+    FileService,
+    ImageOptimizationService,
+    FileUploadTicketService,
+    McpFileSourceService,
+  ],
   controllers: [FileController],
 })
 export class FileModule { }