@gyramais/log-redaction

O que não pode sair no log dos serviços gyra-*: quais chaves são credencial, quais são dado pessoal, quais são ambíguas e decididas pelo valor, e como cada categoria é mascarada em body, headers e query string.

import {
  maskSensitive,
  maskUrl,
  pickSafeHeaders,
  describeError,
} from '@gyramais/log-redaction';

Esses quatro são os usados por todas as 9 variantes da classe LoggingInterceptor na frota. Os predicados (isSensitive, isPii, isAmbiguousPii, isOauthCallbackOnly, isOidcCallbackShape, normalizeKey, looksPersonal, maskPii) e as constantes também são exportados, para quem precise compor caso específico ou testar direto.

Documento sai parcial: cpf, cnpj, document, documents, newDocument e signerDocument preservam os 3 primeiros e os 2 últimos dígitos (11122233344 -> 111******44; 12ABC34501DE35 -> 12A*********35, preservando as letras do CNPJ alfanumérico), em vez de virarem ****. Só valor com forma de documento — 11 ou 14 caracteres — sai parcial; o resto vai para mascaramento total. É a convenção que já existia em gyra-integration/src/common/utils/mask-document.ts, e os casos da spec daquele arquivo são testados aqui para as implementações não divergirem. As outras chaves de PII seguem em mascaramento total.

Sem dependência de runtime.

As listas exportadas são imutáveis

SAFE_HEADERS, SENSITIVE_FIELDS, PII_FIELDS, DOCUMENT_FIELDS e as demais passam por Object.freeze desde a 0.3.0, e o tipo é readonly string[]. Elas definem o que não pode vazar: ir por referência deixava um consumidor desligar o mascaramento do processo inteiro com um SENSITIVE_FIELDS.push(), em silêncio.

Ao migrar um serviço, isto é o único ponto que pode deixar de compilar:

const campos: string[] = SENSITIVE_FIELDS;    // erro
const campos: readonly string[] = SENSITIVE_FIELDS;   // ok
const campos = [...SENSITIVE_FIELDS];         // ok, se precisar mutar mesmo

Para exercitar outra lista num teste, mocke quem consome a lista — não a lista.

Proveniência

src/index.ts é cópia byte-a-byte do bloco que existia duplicado e idêntico nos 15 serviços após a GYR-1541 (md5 cc04916718f5db4c776d256fc05068b3, 313 linhas). A única diferença é a palavra export.

O arquivo está no .prettierignore de propósito: formatá-lo destruiria a propriedade que torna a migração verificável — durante a adoção, cada serviço pode conferir que o bloco que está removendo é exatamente o que o pacote passa a fornecer.

Os comentários registram seis rodadas de revisão e três revisões humanas: por que allowlist e não denylist, por que documentType fica fora, por que to é decidido por valor e não por chave, por que state só é mascarado no body sob assinatura de callback OIDC, por que some e não every, e por que o seen sai do conjunto ao desempilhar. Não remover.