@hed-hog/core 0.0.398 → 0.0.400

package/src/file/mcp-file-source.service.ts

@@ -0,0 +1,445 @@
+import { PrismaService } from '@hed-hog/api-prisma';
+import {
+  BadRequestException,
+  forwardRef,
+  Inject,
+  Injectable,
+  Logger,
+} from '@nestjs/common';
+import { createHash } from 'crypto';
+import { SettingService } from '../setting/setting.service';
+import { FileUploadTicketService } from './file-upload-ticket.service';
+import { FileService } from './file.service';
+import {
+  FILE_SOURCE_FIELDS,
+  FileSourceModality,
+} from './mcp-file-source.schema';
+import { findMimetypeConflict, MIMETYPE_SNIFF_BYTES } from './mimetype-sniff.util';
+import { fetchRemoteFile } from './remote-fetch.util';
+
+/**
+ * Normaliza as quatro origens de arquivo que uma tool MCP pode receber.
+ *
+ * Existe para que validação, sniffing de mimetype, auditoria e idempotência morem num
+ * ponto só. A alternativa — cada tool tratando as quatro origens por conta — garantiria
+ * que mais cedo ou mais tarde um caminho novo escapasse do `storage-accept-mimetype` ou
+ * da checagem de dono, e ninguém perceberia até virar incidente.
+ *
+ * Duas portas de saída, porque as tools consomem o arquivo de formas diferentes:
+ *
+ *   - `resolveFileId`     para quem persiste o anexo e só precisa do id;
+ *   - `resolveMulterFile` para quem quer os bytes e não guarda nada (importar extrato,
+ *                         extrair dados de uma nota com IA).
+ */
+
+export interface FileSourceArgs {
+  fileId?: number;
+  uploadId?: number;
+  fileUrl?: string;
+  fileBase64?: string;
+  fileName?: string;
+  mimeType?: string;
+  sha256?: string;
+  [key: string]: any;
+}
+
+export interface FileSourceContext {
+  userId: number;
+  toolName?: string;
+}
+
+export interface ResolveOptions {
+  /** Pasta no storage para as origens que ainda não têm arquivo gravado. */
+  destination: string;
+  isPrivate?: boolean;
+  /** `false` deixa a tool seguir sem arquivo (o extract-from-file aceita isso). */
+  required?: boolean;
+}
+
+export interface ResolvedFileSource {
+  fileId: number;
+  modality: FileSourceModality;
+  filename: string;
+  mimetype: string;
+  size: number;
+}
+
+export interface ResolvedFileContent {
+  file: MulterFile;
+  modality: FileSourceModality;
+  /** Preenchido quando a origem já era um arquivo armazenado. */
+  fileId?: number;
+}
+
+@Injectable()
+export class McpFileSourceService {
+  private readonly logger = new Logger(McpFileSourceService.name);
+
+  constructor(
+    private readonly prismaService: PrismaService,
+    @Inject(forwardRef(() => FileService))
+    private readonly fileService: FileService,
+    @Inject(forwardRef(() => FileUploadTicketService))
+    private readonly uploadTickets: FileUploadTicketService,
+    @Inject(forwardRef(() => SettingService))
+    private readonly settingService: SettingService,
+  ) {}
+
+  /**
+   * Qual origem veio, exigindo exatamente uma.
+   *
+   * Aceitar duas e escolher a "melhor" seria pior do que recusar: a chamada teria dois
+   * arquivos possíveis e o resultado dependeria de uma precedência que ninguém leu.
+   */
+  detectModality(args: FileSourceArgs, required = true): FileSourceModality | null {
+    const present = FILE_SOURCE_FIELDS.filter((field) => {
+      const value = args?.[field];
+      return value !== undefined && value !== null && value !== '';
+    });
+
+    if (present.length > 1) {
+      throw new BadRequestException(
+        `Provide exactly one file source, got ${present.length}: ${present.join(', ')}`,
+      );
+    }
+
+    if (present.length === 0) {
+      if (required) {
+        throw new BadRequestException(
+          `A file source is required: one of ${FILE_SOURCE_FIELDS.join(', ')}`,
+        );
+      }
+
+      return null;
+    }
+
+    return present[0];
+  }
+
+  private async maxBytes(): Promise<number> {
+    const settings = await this.settingService.getSettingValues(['storage-max-size']);
+    return Number(settings['storage-max-size']) || 10485760;
+  }
+
+  private async allowedUrlHosts(): Promise<string[]> {
+    const settings = await this.settingService.getSettingValues([
+      'mcp-file-url-allowed-hosts',
+    ]);
+    const raw = settings['mcp-file-url-allowed-hosts'];
+
+    return String(raw ?? '')
+      .split(',')
+      .map((host) => host.trim())
+      .filter(Boolean);
+  }
+
+  /**
+   * Valida um buffer que ainda não está no storage: tamanho, tipo declarado, tipo real e
+   * sha256 quando informado.
+   *
+   * `acceptMimetypes` sozinho não basta — ele compara a string que o cliente mandou com a
+   * allowlist, então um executável declarado como `application/pdf` passaria. O sniff é o
+   * contraditório dessa declaração.
+   */
+  private async assertBufferAcceptable(
+    buffer: Buffer,
+    mimetype: string,
+    expectedSha256?: string,
+  ) {
+    const maxBytes = await this.maxBytes();
+
+    if (buffer.length === 0) {
+      throw new BadRequestException(`File content is empty`);
+    }
+
+    if (buffer.length > maxBytes) {
+      throw new BadRequestException(
+        `File too large: ${buffer.length} bytes. The storage-max-size setting allows ${maxBytes}.`,
+      );
+    }
+
+    if (!(await this.fileService.acceptMimetypes(mimetype))) {
+      throw new BadRequestException(`Invalid file type: ${mimetype}`);
+    }
+
+    const conflict = findMimetypeConflict(mimetype, buffer);
+
+    if (conflict) {
+      throw new BadRequestException(
+        `Declared mimeType ${mimetype} but the content is ${conflict}`,
+      );
+    }
+
+    if (expectedSha256) {
+      const actual = createHash('sha256').update(buffer).digest('hex');
+
+      if (actual.toLowerCase() !== expectedSha256.toLowerCase()) {
+        throw new BadRequestException(
+          `sha256 mismatch: declared ${expectedSha256}, content hashes to ${actual}`,
+        );
+      }
+    }
+  }
+
+  private toMulterFile(
+    buffer: Buffer,
+    filename: string,
+    mimetype: string,
+  ): MulterFile {
+    return {
+      fieldname: 'file',
+      originalname: filename,
+      encoding: '7bit',
+      mimetype,
+      size: buffer.length,
+      destination: '',
+      filename,
+      path: '',
+      buffer,
+    };
+  }
+
+  private decodeBase64(args: FileSourceArgs): { buffer: Buffer; filename: string; mimetype: string } {
+    if (!args.fileName || !args.mimeType) {
+      throw new BadRequestException(
+        `fileBase64 requires fileName and mimeType`,
+      );
+    }
+
+    const buffer = Buffer.from(String(args.fileBase64), 'base64');
+
+    // `Buffer.from(x, 'base64')` nunca reclama: entrada inválida vira bytes truncados em
+    // silêncio. Reencodar e comparar é o que separa um base64 verdadeiro de um texto
+    // qualquer que o modelo tenha emitido no lugar.
+    if (buffer.length === 0) {
+      throw new BadRequestException(`fileBase64 decoded to zero bytes`);
+    }
+
+    const normalized = String(args.fileBase64).replace(/\s/g, '');
+
+    if (buffer.toString('base64').replace(/=+$/, '') !== normalized.replace(/=+$/, '')) {
+      throw new BadRequestException(
+        `fileBase64 is not valid base64 (it may have been truncated in transit)`,
+      );
+    }
+
+    return { buffer, filename: args.fileName, mimetype: args.mimeType };
+  }
+
+  private async fetchFromUrl(
+    args: FileSourceArgs,
+  ): Promise<{ buffer: Buffer; filename: string; mimetype: string; host: string }> {
+    const result = await fetchRemoteFile(String(args.fileUrl), {
+      maxBytes: await this.maxBytes(),
+      allowedHosts: await this.allowedUrlHosts(),
+    });
+
+    // Nome e tipo declarados ganham do que o servidor remoto disse: quem chama sabe o que
+    // pediu, e o `Content-Type` de um link de compartilhamento costuma vir genérico. O
+    // conteúdo real ainda é conferido depois, contra o que tiver sobrado aqui.
+    const fallbackName =
+      decodeURIComponent(new URL(result.finalUrl).pathname.split('/').pop() || '') ||
+      'download';
+
+    return {
+      buffer: result.buffer,
+      filename: args.fileName || fallbackName,
+      mimetype: args.mimeType || result.contentType || 'application/octet-stream',
+      host: result.finalHost,
+    };
+  }
+
+  /**
+   * Normaliza qualquer origem para um `fileId`.
+   *
+   * `fileId` e `uploadId` não regravam nada — o arquivo já está lá. `fileUrl` e
+   * `fileBase64` gravam, com o dono registrado, e é por isso que o `fileId` devolvido
+   * pode ser reaproveitado numa chamada seguinte sem novo upload.
+   */
+  // Sobrecargas para que o `| null` só apareça para quem pediu `required: false`. Sem
+  // isso todo chamador carregaria uma checagem de nulo que nunca acontece — e como o
+  // projeto não usa `strictNullChecks`, quem esquecesse a checagem não seria avisado.
+  async resolveFileId(
+    args: FileSourceArgs,
+    context: FileSourceContext,
+    options: ResolveOptions & { required?: true },
+  ): Promise<ResolvedFileSource>;
+  async resolveFileId(
+    args: FileSourceArgs,
+    context: FileSourceContext,
+    options: ResolveOptions & { required: false },
+  ): Promise<ResolvedFileSource | null>;
+  async resolveFileId(
+    args: FileSourceArgs,
+    context: FileSourceContext,
+    options: ResolveOptions,
+  ): Promise<ResolvedFileSource | null> {
+    const modality = this.detectModality(args, options.required !== false);
+
+    if (!modality) {
+      return null;
+    }
+
+    let file: any;
+    let sourceHost: string | undefined;
+
+    if (modality === 'fileId') {
+      file = await this.fileService.assertFileUsable(Number(args.fileId), context.userId);
+    } else if (modality === 'uploadId') {
+      file = await this.uploadTickets.complete(Number(args.uploadId), context.userId);
+    } else {
+      const fetched =
+        modality === 'fileUrl'
+          ? await this.fetchFromUrl(args)
+          : this.decodeBase64(args);
+
+      sourceHost = (fetched as any).host;
+
+      await this.assertBufferAcceptable(fetched.buffer, fetched.mimetype, args.sha256);
+
+      file = await this.fileService.upload(
+        options.destination,
+        this.toMulterFile(fetched.buffer, fetched.filename, fetched.mimetype),
+        undefined,
+        {
+          isPrivate: options.isPrivate ?? false,
+          createdByUserId: context.userId,
+        },
+      );
+    }
+
+    const resolved: ResolvedFileSource = {
+      fileId: file.id,
+      modality,
+      filename: file.filename,
+      mimetype: await this.fileService.mimetypeNameById(file.mimetype_id),
+      size: file.size ?? 0,
+    };
+
+    await this.recordIngest(resolved, context, sourceHost);
+
+    return resolved;
+  }
+
+  /**
+   * Normaliza qualquer origem para os bytes, sem gravar quando não é preciso.
+   *
+   * `fileId`/`uploadId` leem do storage; `fileUrl`/`fileBase64` ficam em memória — a tool
+   * que só quer ler um extrato não deve encher o acervo de arquivos que ninguém mais vai
+   * abrir.
+   */
+  async resolveMulterFile(
+    args: FileSourceArgs,
+    context: FileSourceContext,
+    options: Omit<ResolveOptions, 'destination'> & { destination?: string; required?: true },
+  ): Promise<ResolvedFileContent>;
+  async resolveMulterFile(
+    args: FileSourceArgs,
+    context: FileSourceContext,
+    options: Omit<ResolveOptions, 'destination'> & { destination?: string; required: false },
+  ): Promise<ResolvedFileContent | null>;
+  async resolveMulterFile(
+    args: FileSourceArgs,
+    context: FileSourceContext,
+    options: Omit<ResolveOptions, 'destination'> & { destination?: string },
+  ): Promise<ResolvedFileContent | null> {
+    const modality = this.detectModality(args, options.required !== false);
+
+    if (!modality) {
+      return null;
+    }
+
+    if (modality === 'fileId' || modality === 'uploadId') {
+      const stored =
+        modality === 'fileId'
+          ? await this.fileService.assertFileUsable(Number(args.fileId), context.userId)
+          : await this.uploadTickets.complete(Number(args.uploadId), context.userId);
+
+      const buffer = await this.fileService.bufferById(stored.id, await this.maxBytes());
+      const mimetype = await this.fileService.mimetypeNameById(stored.mimetype_id);
+
+      await this.recordIngest(
+        {
+          fileId: stored.id,
+          modality,
+          filename: stored.filename,
+          mimetype,
+          size: buffer.length,
+        },
+        context,
+      );
+
+      return {
+        file: this.toMulterFile(buffer, stored.filename, mimetype),
+        modality,
+        fileId: stored.id,
+      };
+    }
+
+    const fetched =
+      modality === 'fileUrl' ? await this.fetchFromUrl(args) : this.decodeBase64(args);
+
+    await this.assertBufferAcceptable(fetched.buffer, fetched.mimetype, args.sha256);
+
+    await this.recordIngest(
+      {
+        fileId: 0,
+        modality,
+        filename: fetched.filename,
+        mimetype: fetched.mimetype,
+        size: fetched.buffer.length,
+      },
+      context,
+      (fetched as any).host,
+    );
+
+    return {
+      file: this.toMulterFile(fetched.buffer, fetched.filename, fetched.mimetype),
+      modality,
+    };
+  }
+
+  /**
+   * Registra a ingestão em `audit_log`, com a modalidade usada.
+   *
+   * `audit_log` é tabela global (só o finance escrevia nela até aqui, mas ela não é do
+   * finance), e `finance.audit-logs.list` já a lê sem filtrar por library — então a
+   * trilha das quatro modalidades fica visível por um caminho que já existe.
+   *
+   * Nunca derruba a operação: auditoria que falha e leva o anexo junto troca um problema
+   * de observabilidade por um de funcionamento.
+   */
+  private async recordIngest(
+    resolved: ResolvedFileSource,
+    context: FileSourceContext,
+    sourceHost?: string,
+  ) {
+    try {
+      await this.prismaService.audit_log.create({
+        data: {
+          actor_user_id: context.userId || null,
+          action: 'MCP_FILE_INGEST',
+          entity_table: 'file',
+          entity_id: String(resolved.fileId || ''),
+          summary: `Ingested ${resolved.filename} via ${resolved.modality}${
+            context.toolName ? ` for ${context.toolName}` : ''
+          }`,
+          after_data: JSON.stringify({
+            modality: resolved.modality,
+            tool: context.toolName ?? null,
+            file_id: resolved.fileId || null,
+            filename: resolved.filename,
+            mimetype: resolved.mimetype,
+            bytes: resolved.size,
+            ...(sourceHost ? { source_host: sourceHost } : {}),
+          }),
+        },
+      });
+    } catch (error: any) {
+      this.logger.warn(`Failed to record MCP file ingest: ${error.message}`);
+    }
+  }
+
+  /** Quanto do arquivo basta para reconhecer o tipo — reexportado para os testes. */
+  static readonly SNIFF_BYTES = MIMETYPE_SNIFF_BYTES;
+}

package/src/file/mimetype-sniff.util.spec.ts

@@ -0,0 +1,126 @@
+import { describe, expect, it } from '@jest/globals';
+import {
+  detectMimetypeFromBytes,
+  findMimetypeConflict,
+} from './mimetype-sniff.util';
+
+/** Cabeçalho mínimo de cada formato, com o resto preenchido para passar do tamanho. */
+const sample = (...parts: Array<string | number[]>): Buffer => {
+  const chunks = parts.map((part) =>
+    typeof part === 'string' ? Buffer.from(part, 'latin1') : Buffer.from(part),
+  );
+
+  return Buffer.concat([...chunks, Buffer.alloc(64)]);
+};
+
+const PDF = sample('%PDF-1.7');
+const JPEG = sample([0xff, 0xd8, 0xff, 0xe0]);
+const PNG = sample([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+const GIF = sample('GIF89a');
+const WEBP = sample('RIFF', [0, 0, 0, 0], 'WEBP');
+const WAV = sample('RIFF', [0, 0, 0, 0], 'WAVE');
+const MP3 = sample('ID3');
+const FLAC = sample('fLaC');
+const OGG = sample('OggS');
+const MP4 = sample([0, 0, 0, 0x20], 'ftyp', 'isom');
+const M4A = sample([0, 0, 0, 0x20], 'ftyp', 'M4A ');
+const ZIP = sample([0x50, 0x4b, 0x03, 0x04]);
+const DOCX = sample([0x50, 0x4b, 0x03, 0x04], '.....word/document.xml');
+const XLSX = sample([0x50, 0x4b, 0x03, 0x04], '.....xl/workbook.xml');
+const PPTX = sample([0x50, 0x4b, 0x03, 0x04], '.....ppt/presentation.xml');
+/** Cabeçalho de executável do Windows — o caso que motiva o sniff existir. */
+const EXE = sample('MZ', [0x90, 0x00, 0x03, 0x00]);
+
+describe('detectMimetypeFromBytes', () => {
+  it.each([
+    ['pdf', PDF, 'application/pdf'],
+    ['jpeg', JPEG, 'image/jpeg'],
+    ['png', PNG, 'image/png'],
+    ['gif', GIF, 'image/gif'],
+    ['webp', WEBP, 'image/webp'],
+    ['wav', WAV, 'audio/wav'],
+    ['mp3', MP3, 'audio/mpeg'],
+    ['flac', FLAC, 'audio/flac'],
+    ['ogg', OGG, 'audio/ogg'],
+    ['mp4', MP4, 'video/mp4'],
+    ['m4a', M4A, 'audio/mp4'],
+    ['zip', ZIP, 'application/zip'],
+  ])('reconhece %s', (_name, buffer, expected) => {
+    expect(detectMimetypeFromBytes(buffer)).toBe(expected);
+  });
+
+  it('distingue os três OOXML pelo nome das entradas do zip', () => {
+    expect(detectMimetypeFromBytes(DOCX)).toBe(
+      'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    );
+    expect(detectMimetypeFromBytes(XLSX)).toBe(
+      'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    );
+    expect(detectMimetypeFromBytes(PPTX)).toBe(
+      'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+    );
+  });
+
+  it('devolve null para formato que não conhece, em vez de chutar', () => {
+    // CSV e OFX entram por aqui, e é justamente por isso que desconhecido não é recusa:
+    // barrá-los quebraria o finance.statements.import.
+    expect(detectMimetypeFromBytes(Buffer.from('data,valor\n2026-01-01,10'))).toBeNull();
+    expect(detectMimetypeFromBytes(Buffer.alloc(2))).toBeNull();
+  });
+});
+
+describe('findMimetypeConflict', () => {
+  it('não acusa conflito quando o conteúdo confirma o declarado', () => {
+    expect(findMimetypeConflict('application/pdf', PDF)).toBeNull();
+    expect(findMimetypeConflict('image/png', PNG)).toBeNull();
+  });
+
+  it('acusa um formato conhecido que contradiz o declarado', () => {
+    expect(findMimetypeConflict('application/pdf', PNG)).toBe('image/png');
+    expect(findMimetypeConflict('image/png', PDF)).toBe('application/pdf');
+  });
+
+  it('acusa o executável declarado como PDF', () => {
+    // O caso central: `storage-accept-mimetype` sozinho aprovaria, porque ele só olha a
+    // string que o cliente mandou. E um `.exe` não tem nenhuma assinatura que o sniffer
+    // reconheça, então tratar "desconhecido" como "sem objeção" deixaria ele entrar.
+    expect(findMimetypeConflict('application/pdf', EXE)).toBe('a Windows executable');
+    expect(
+      findMimetypeConflict('image/png', sample([0x7f, 0x45, 0x4c, 0x46])),
+    ).toBe('an ELF executable');
+    expect(findMimetypeConflict('application/pdf', sample('#!/bin/sh\nrm -rf /'))).toBe(
+      'a script with a shebang',
+    );
+  });
+
+  it('recusa conteúdo irreconhecível quando o tipo declarado é verificável', () => {
+    // Nem todo payload hostil traz assinatura de executável. Declarar um formato que TEM
+    // assinatura conhecida é assumir que ela vai estar lá.
+    expect(findMimetypeConflict('application/pdf', Buffer.from('nao sou um pdf'))).toBe(
+      'not recognizable as application/pdf',
+    );
+    expect(findMimetypeConflict('image/png', Buffer.from('nem uma imagem'))).toBe(
+      'not recognizable as image/png',
+    );
+  });
+
+  it('aceita sinônimos do mesmo formato', () => {
+    expect(findMimetypeConflict('audio/mp3', MP3)).toBeNull();
+    expect(findMimetypeConflict('audio/x-wav', WAV)).toBeNull();
+    expect(findMimetypeConflict('image/jpg', JPEG)).toBeNull();
+  });
+
+  it('não briga dentro da família zip, já que um docx é literalmente um zip', () => {
+    expect(findMimetypeConflict('application/zip', DOCX)).toBeNull();
+    expect(
+      findMimetypeConflict(
+        'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+        ZIP,
+      ),
+    ).toBeNull();
+  });
+
+  it('não acusa nada quando a assinatura é desconhecida', () => {
+    expect(findMimetypeConflict('text/csv', Buffer.from('a,b,c'))).toBeNull();
+  });
+});