@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, signerDocument, cpfCnpj e documento 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.

Segredo no CAMINHO da URL, não só na query string: maskUrl também troca por **** o segmento que é credencial em rotas conhecidas — hoje public/collection/{token} e /envio/{token}, as duas formas do link que abre a página do destinatário. Quem tem o token abre a página, vê os documentos e assina, então ele não é id: é a credencial inteira. A tabela é PATH_SECRET_ROUTES, e a regra é posicional (qual segmento depois do prefixo), não "parece um token" — senão id de item seria mascarado junto e a linha deixaria de servir para investigar.

O segmento termina na primeira barra ou no primeiro espaço em branco: o link costuma vir dentro de uma frase (o corpo da mensagem), e sem o corte no espaço a raspagem levava o resto da frase junto.

Erro de cliente HTTP é resumido, não percorrido (1.6.0). Um AxiosError — ou err.toJSON(), ou err.response — que chegue a maskLogMeta/maskSensitive vira { name, message, code, status, method, url, stack }, com a url já passada por maskUrl. Mascarar por nome de chave não bastava: o mesmo Bearer que saía **** em config.headers.Authorization saía em claro em request._header, junto com o usuario:senha do basic auth em request._options.auth. config, request, cause e response.data ficam de fora — o último porque gateway reflete o header recebido no corpo do erro. Quem precisa do corpo extrai os campos que conhece.

Credencial que viaja na própria URL (1.6.0): maskUrl tira o userinfo (amqp://usuario:senha@host -> amqp://****@host) e mascara os parâmetros de URL_SECRET_PARAMS — assinatura da presign do S3/GCS e key= da API do Google. A mesma raspagem vale para qualquer folha de texto do metadado (rabbitmqUrl, uma frase com o link dentro). key só é credencial como parâmetro de URL; como nome de campo é o objeto do S3, e por isso a lista é separada de SENSITIVE_FIELDS.

Erro comum também é resumido (1.7.0). message, stack e cause de um Error não são enumeráveis, e até a 1.6.0 logger.error('falhou', e) saía {}. Agora qualquer Error vira { name, message, code, stack, cause, …demais propriedades mascaradas }, com credencial de URL raspada. Não é preciso chamar describeError no catch: logue o erro como sempre. Erros que carregam valor na mensagem têm tratamento próprio: do Prisma (PrismaClient*) sai só a última linha, o motivo, e só os frames da stack; do Mongo E11000, o valor da chave duplicada vira ****.

code com forma de código de erro sai legível em log (1.8.0). code segue sensível (no body é código de login e authorization code do OAuth), mas em metadado de log um valor com forma de código de erro (ECONNREFUSED, ERR_*, P2002, CERT_*) sai legível. É o que o logger.error(err) espalha no topo da linha. Dígitos, base64 e callback OIDC (code com idToken/state ao lado) seguem ****.

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.