@hed-hog/core 0.0.399 → 0.0.401

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

@@ -0,0 +1,265 @@
+/**
+ * Identifica o tipo real de um arquivo pelos primeiros bytes, para que o mimetype
+ * declarado por quem envia não seja a única palavra sobre o que está sendo gravado.
+ *
+ * Hoje o `Content-Type` do multipart é a fonte de verdade sempre que vem concreto
+ * (`resolveEffectiveMimetype` no `FileService` só recorre ao conteúdo quando o caller
+ * manda vazio ou `application/octet-stream`), então um executável enviado como
+ * `image/png` passa direto pelo `storage-accept-mimetype`. Nas origens novas do MCP o
+ * cliente escolhe livremente o `mimeType`, o que tornaria essa brecha trivial de usar.
+ *
+ * Cobre o conjunto de opções do `storage-accept-mimetype` e nada além: a função não é
+ * um detector geral, é o contraditório do que foi declarado. Quando o formato não está
+ * nesta lista ela devolve `null`, e quem chama mantém o tipo declarado — recusar o que
+ * não se sabe reconhecer barraria CSV, OFX e afins, que são justamente o insumo do
+ * `statements.import`.
+ *
+ * Não usa `file-type`: da v19 em diante o pacote é ESM puro e quebraria o build CJS
+ * destas libraries. Os formatos aqui têm assinatura estável e curta.
+ *
+ * Existem dois primos, e a diferença entre eles e este é de política, não de descuido:
+ * `cms/src/form/cms-form-file-sniffer.ts` e
+ * `operations/src/task-intake/task-intake-file-sniffer.ts` usam allowlist **fechada** —
+ * o que não é reconhecido é recusado — porque servem endpoints anônimos, onde o mimetype
+ * declarado não vale nada e o conjunto aceito é estreito (print e vídeo do problema).
+ * Aqui a política é aberta: o caminho é autenticado e precisa continuar aceitando CSV e
+ * OFX, que não têm assinatura, para o `finance.statements.import`. Unificar os três
+ * significaria parametrizar essa política através de uma fronteira de segurança, e
+ * afrouxar por acidente o endpoint anônimo é o risco que isso carrega — é mudança
+ * própria, não carona nesta.
+ */
+
+/** Quanto do início do arquivo basta para todas as assinaturas abaixo. */
+export const MIMETYPE_SNIFF_BYTES = 4096;
+
+const ascii = (buffer: Buffer, offset: number, text: string): boolean =>
+  buffer.length >= offset + text.length &&
+  buffer.toString('latin1', offset, offset + text.length) === text;
+
+const bytes = (buffer: Buffer, offset: number, ...expected: number[]): boolean => {
+  if (buffer.length < offset + expected.length) {
+    return false;
+  }
+
+  return expected.every((byte, index) => buffer[offset + index] === byte);
+};
+
+/**
+ * ZIP é o container de docx/xlsx/pptx: os três começam com `PK\x03\x04` e só se
+ * distinguem pelo nome das entradas. O `[Content_Types].xml` de um OOXML declara o tipo
+ * do documento, e a primeira entrada costuma ser `word/`, `xl/` ou `ppt/` — procuramos
+ * essas marcas no cabeçalho lido, sem descompactar.
+ */
+const sniffZipFlavor = (buffer: Buffer): string => {
+  const head = buffer.toString('latin1', 0, Math.min(buffer.length, MIMETYPE_SNIFF_BYTES));
+
+  if (head.includes('word/')) {
+    return 'application/vnd.openxmlformats-officedocument.wordprocessingml.document';
+  }
+
+  if (head.includes('xl/')) {
+    return 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet';
+  }
+
+  if (head.includes('ppt/')) {
+    return 'application/vnd.openxmlformats-officedocument.presentationml.presentation';
+  }
+
+  return 'application/zip';
+};
+
+/**
+ * `ftyp` na posição 4 marca a família ISO-BMFF. A marca de quatro letras que segue diz
+ * se é vídeo ou áudio; `M4A ` é o único caso de áudio que interessa aqui.
+ */
+const sniffIsoBmff = (buffer: Buffer): string => {
+  const brand = buffer.toString('latin1', 8, 12);
+  return brand.startsWith('M4A') ? 'audio/mp4' : 'video/mp4';
+};
+
+/**
+ * Tipo real do conteúdo, ou `null` quando a assinatura não é reconhecida.
+ *
+ * Só precisa dos primeiros bytes — passe o cabeçalho quando o arquivo for grande, e
+ * nunca o arquivo inteiro só para chamar esta função.
+ */
+export function detectMimetypeFromBytes(buffer: Buffer): string | null {
+  if (!buffer || buffer.length < 4) {
+    return null;
+  }
+
+  if (ascii(buffer, 0, '%PDF-')) {
+    return 'application/pdf';
+  }
+
+  if (bytes(buffer, 0, 0xff, 0xd8, 0xff)) {
+    return 'image/jpeg';
+  }
+
+  if (bytes(buffer, 0, 0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a)) {
+    return 'image/png';
+  }
+
+  if (ascii(buffer, 0, 'GIF87a') || ascii(buffer, 0, 'GIF89a')) {
+    return 'image/gif';
+  }
+
+  // RIFF é container: os bytes 8..11 dizem o que ele carrega.
+  if (ascii(buffer, 0, 'RIFF')) {
+    if (ascii(buffer, 8, 'WEBP')) {
+      return 'image/webp';
+    }
+
+    if (ascii(buffer, 8, 'WAVE')) {
+      return 'audio/wav';
+    }
+
+    return null;
+  }
+
+  if (ascii(buffer, 0, 'fLaC')) {
+    return 'audio/flac';
+  }
+
+  if (ascii(buffer, 0, 'OggS')) {
+    return 'audio/ogg';
+  }
+
+  // ID3 é a tag de metadados que antecede o quadro MPEG; 0xFF 0xFB/0xF3/0xF2 é o quadro
+  // cru, sem tag. `audio/mp3` e `audio/mpeg` são o mesmo formato com dois nomes, e a
+  // allowlist aceita os dois — devolvemos o nome canônico e o cotejo trata o sinônimo.
+  if (ascii(buffer, 0, 'ID3') || bytes(buffer, 0, 0xff, 0xfb) || bytes(buffer, 0, 0xff, 0xf3) || bytes(buffer, 0, 0xff, 0xf2)) {
+    return 'audio/mpeg';
+  }
+
+  if (ascii(buffer, 4, 'ftyp')) {
+    return sniffIsoBmff(buffer);
+  }
+
+  // `PK\x03\x04` é o arquivo; `PK\x05\x06` e `PK\x07\x08` são ZIP vazio e spanned.
+  if (bytes(buffer, 0, 0x50, 0x4b, 0x03, 0x04) || bytes(buffer, 0, 0x50, 0x4b, 0x05, 0x06) || bytes(buffer, 0, 0x50, 0x4b, 0x07, 0x08)) {
+    return sniffZipFlavor(buffer);
+  }
+
+  return null;
+}
+
+/**
+ * Sinônimos que nomeiam o mesmo formato. Recusar um upload porque o cliente escreveu
+ * `audio/mp3` onde os bytes dizem `audio/mpeg` seria falso positivo puro.
+ */
+const EQUIVALENT_MIMETYPES: string[][] = [
+  ['audio/mp3', 'audio/mpeg'],
+  ['audio/wav', 'audio/x-wav', 'audio/wave'],
+  ['image/jpeg', 'image/jpg'],
+  ['video/mp4', 'audio/mp4'],
+];
+
+const isEquivalent = (a: string, b: string): boolean =>
+  EQUIVALENT_MIMETYPES.some((group) => group.includes(a) && group.includes(b));
+
+const ZIP_FAMILY = [
+  'application/zip',
+  'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+];
+
+/**
+ * Tipos que esta função sabe confirmar positivamente.
+ *
+ * Declarar um deles é assumir um formato com assinatura conhecida, então o conteúdo tem
+ * de exibi-la. Fora desta lista (CSV, OFX, texto solto) não há o que conferir, e a
+ * ausência de assinatura não é indício de nada.
+ */
+const VERIFIABLE_MIMETYPES = new Set([
+  'application/pdf',
+  'image/jpeg',
+  'image/jpg',
+  'image/png',
+  'image/gif',
+  'image/webp',
+  'audio/mp3',
+  'audio/mpeg',
+  'audio/wav',
+  'audio/x-wav',
+  'audio/wave',
+  'audio/flac',
+  'audio/ogg',
+  'audio/mp4',
+  'video/mp4',
+  ...ZIP_FAMILY,
+]);
+
+/**
+ * Formatos que nunca estão na allowlist e que caracterizam conteúdo executável.
+ *
+ * Não são detectados para serem aceitos — são detectados para que a recusa diga o que o
+ * arquivo realmente é, em vez de um genérico "não confere".
+ */
+const EXECUTABLE_SIGNATURES: Array<{ test: (b: Buffer) => boolean; label: string }> = [
+  { test: (b) => ascii(b, 0, 'MZ'), label: 'a Windows executable' },
+  { test: (b) => bytes(b, 0, 0x7f, 0x45, 0x4c, 0x46), label: 'an ELF executable' },
+  { test: (b) => bytes(b, 0, 0xcf, 0xfa, 0xed, 0xfe), label: 'a Mach-O executable' },
+  { test: (b) => bytes(b, 0, 0xca, 0xfe, 0xba, 0xbe), label: 'a Java class or fat binary' },
+  { test: (b) => ascii(b, 0, '#!'), label: 'a script with a shebang' },
+];
+
+const describeExecutable = (buffer: Buffer): string | null =>
+  EXECUTABLE_SIGNATURES.find((entry) => entry.test(buffer))?.label ?? null;
+
+/**
+ * Confronta o tipo declarado com o que os bytes dizem.
+ *
+ * Devolve `null` quando não há conflito, ou uma descrição do que o conteúdo realmente é —
+ * é ela que a mensagem de erro mostra, porque "declarado X, conteúdo Y" é o que permite
+ * corrigir a chamada.
+ *
+ * A regra tem dois lados, e o segundo é o que fecha o buraco:
+ *
+ *   1. assinatura reconhecida que contradiz o declarado → conflito;
+ *   2. assinatura NÃO reconhecida, mas o tipo declarado é um dos verificáveis → também
+ *      conflito. Sem isso, bastaria declarar `application/pdf` num executável para
+ *      passar: ele não tem assinatura de PDF, mas também não tem nenhuma das que o
+ *      sniffer conhece, e "desconhecido" seria lido como "sem objeção".
+ *
+ * Conteúdo sem assinatura declarado como `text/csv` continua passando, que é o caso do
+ * `finance.statements.import`.
+ *
+ * ZIP merece nota: um `.docx` declarado como `application/zip` não é conflito, já que ele
+ * é literalmente um zip. O contrário também não, pelo mesmo motivo.
+ */
+export function findMimetypeConflict(
+  declared: string,
+  buffer: Buffer,
+): string | null {
+  if (!declared) {
+    return null;
+  }
+
+  const detected = detectMimetypeFromBytes(buffer);
+
+  if (detected) {
+    if (detected === declared || isEquivalent(detected, declared)) {
+      return null;
+    }
+
+    if (ZIP_FAMILY.includes(detected) && ZIP_FAMILY.includes(declared)) {
+      return null;
+    }
+
+    return detected;
+  }
+
+  const executable = describeExecutable(buffer);
+
+  if (executable) {
+    return executable;
+  }
+
+  if (VERIFIABLE_MIMETYPES.has(declared)) {
+    return `not recognizable as ${declared}`;
+  }
+
+  return null;
+}

package/src/file/remote-fetch.util.spec.ts

@@ -0,0 +1,117 @@
+import { describe, expect, it } from '@jest/globals';
+import { assertFetchableUrl, describeBlockedAddress } from './remote-fetch.util';
+
+/**
+ * A guarda de SSRF é a parte desta entrega com maior custo se estiver errada: `fileUrl` é
+ * a única superfície em que um endereço escolhido por quem chama vira requisição saindo de
+ * dentro do cluster. Estes testes cobrem a decisão de bloqueio e a validação da URL; o
+ * caminho de rede em si (redirects, teto de bytes) é exercido pelo teste de integração da
+ * tool, porque aqui ele viraria um mock testando outro mock.
+ */
+
+describe('describeBlockedAddress', () => {
+  it.each([
+    ['loopback v4', '127.0.0.1'],
+    ['loopback fora do .1', '127.99.1.5'],
+    ['privado 10/8', '10.0.0.1'],
+    ['privado 172.16/12', '172.16.5.4'],
+    ['privado 172.31 (limite superior)', '172.31.255.255'],
+    ['privado 192.168/16', '192.168.1.1'],
+    ['metadata da nuvem', '169.254.169.254'],
+    ['link-local fora do metadata', '169.254.1.1'],
+    ['this-network', '0.0.0.0'],
+    ['CGNAT', '100.64.0.1'],
+    ['multicast', '224.0.0.1'],
+    ['reservado', '240.0.0.1'],
+    ['documentação', '192.0.2.1'],
+    ['loopback v6', '::1'],
+    ['unspecified v6', '::'],
+    ['unique local v6', 'fc00::1'],
+    ['link-local v6', 'fe80::1'],
+    ['multicast v6', 'ff02::1'],
+  ])('bloqueia %s', (_label, address) => {
+    expect(describeBlockedAddress(address)).not.toBeNull();
+  });
+
+  it('bloqueia o metadata escrito como IPv6 mapeado', () => {
+    // Sem desempacotar o ::ffff:, o endpoint de metadados volta a ser alcançável só
+    // trocando a notação.
+    expect(describeBlockedAddress('::ffff:169.254.169.254')).not.toBeNull();
+    expect(describeBlockedAddress('::ffff:127.0.0.1')).not.toBeNull();
+    expect(describeBlockedAddress('::FFFF:10.0.0.1')).not.toBeNull();
+  });
+
+  it.each([
+    ['público', '8.8.8.8'],
+    ['logo acima da faixa 172.16/12', '172.32.0.1'],
+    ['logo abaixo da faixa 172.16/12', '172.15.255.255'],
+    ['fora do CGNAT', '100.128.0.1'],
+    ['v6 público', '2606:4700:4700::1111'],
+  ])('libera endereço %s', (_label, address) => {
+    expect(describeBlockedAddress(address)).toBeNull();
+  });
+
+  it('recusa o que não é endereço', () => {
+    expect(describeBlockedAddress('')).not.toBeNull();
+    expect(describeBlockedAddress('nao-e-um-ip')).not.toBeNull();
+  });
+});
+
+describe('assertFetchableUrl', () => {
+  it('aceita http e https', () => {
+    expect(assertFetchableUrl('https://exemplo.com/nota.pdf').hostname).toBe(
+      'exemplo.com',
+    );
+    expect(assertFetchableUrl('http://exemplo.com/nota.pdf').hostname).toBe(
+      'exemplo.com',
+    );
+  });
+
+  it.each([
+    ['file', 'file:///etc/passwd'],
+    ['gopher', 'gopher://exemplo.com/'],
+    ['ftp', 'ftp://exemplo.com/nota.pdf'],
+    ['data', 'data:text/plain;base64,YQ=='],
+  ])('recusa o esquema %s', (_label, url) => {
+    expect(() => assertFetchableUrl(url)).toThrow(/must use http or https/);
+  });
+
+  it('recusa URL malformada', () => {
+    expect(() => assertFetchableUrl('nao é uma url')).toThrow(/not a valid URL/);
+  });
+
+  it('recusa credencial embutida', () => {
+    // Ela viraria header de autenticação para um destino escolhido por quem chama, e
+    // apareceria no log de auditoria junto com o resto da entrada.
+    expect(() => assertFetchableUrl('https://user:senha@exemplo.com/a.pdf')).toThrow(
+      /must not carry credentials/,
+    );
+  });
+
+  describe('allowlist de hosts', () => {
+    const allow = ['sharepoint.com', 'drive.google.com'];
+
+    it('aceita o host exato e os subdomínios', () => {
+      expect(assertFetchableUrl('https://drive.google.com/x', allow)).toBeTruthy();
+      expect(assertFetchableUrl('https://hcode.sharepoint.com/x', allow)).toBeTruthy();
+    });
+
+    it('recusa host de fora', () => {
+      expect(() => assertFetchableUrl('https://exemplo.com/x', allow)).toThrow(
+        /host is not allowed/,
+      );
+    });
+
+    it('não cai no truque do sufixo colado', () => {
+      // `malsharepoint.com` termina com "sharepoint.com" como string, mas não é
+      // subdomínio dele — a comparação exige o ponto.
+      expect(() => assertFetchableUrl('https://malsharepoint.com/x', allow)).toThrow(
+        /host is not allowed/,
+      );
+    });
+
+    it('lista vazia libera qualquer host público', () => {
+      expect(assertFetchableUrl('https://exemplo.com/x', [])).toBeTruthy();
+    });
+  });
+});