@gyramais/log-redaction 0.1.0

package/README.md

@@ -0,0 +1,39 @@
+# @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.
+
+```ts
+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.
+
+Sem dependência de runtime.
+
+## 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.**

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+import type { IncomingHttpHeaders } from 'http';
+export declare const SAFE_HEADERS: string[];
+export declare const SENSITIVE_FIELDS: string[];
+export declare const OAUTH_CALLBACK_ONLY_FIELDS: string[];
+export declare const OIDC_CALLBACK_MARKERS: string[];
+export declare const PII_FIELDS: string[];
+export declare const AMBIGUOUS_PII_FIELDS: string[];
+export declare const LOOKS_PERSONAL: RegExp;
+export declare const FORMATTING_NOISE: RegExp;
+export declare const looksPersonal: (value: unknown) => boolean;
+export declare const REDACTED = "****";
+export declare const TRUNCATED = "[profundidade m\u00E1xima]";
+export declare const CIRCULAR = "[circular]";
+export declare const MAX_MASK_DEPTH = 4;
+export declare const normalizeKey: (key: string) => string;
+export declare const isSensitive: (key: string) => boolean;
+export declare const isPii: (key: string) => boolean;
+export declare const isAmbiguousPii: (key: string, value: unknown) => boolean;
+export declare const isOauthCallbackOnly: (key: string) => boolean;
+export declare const isOidcCallbackShape: (obj: Record<string, unknown>) => boolean;
+export declare const maskPii: (value: unknown) => unknown;
+export declare const pickSafeHeaders: (headers: IncomingHttpHeaders | undefined) => Record<string, unknown>;
+export declare const maskSensitive: <T>(value: T, depth?: number, seen?: WeakSet<object>) => T;
+export declare const maskUrl: (url: string) => string;
+export declare const describeError: (err: unknown) => {
+    name?: string;
+    message: string;
+    stack?: string;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,MAAM,CAAC;AAQhD,eAAO,MAAM,YAAY,UAMxB,CAAC;AAGF,eAAO,MAAM,gBAAgB,UAuB5B,CAAC;AAWF,eAAO,MAAM,0BAA0B,UAAY,CAAC;AAGpD,eAAO,MAAM,qBAAqB,UAAsB,CAAC;AAgBzD,eAAO,MAAM,UAAU,UActB,CAAC;AAQF,eAAO,MAAM,oBAAoB,UAAS,CAAC;AAM3C,eAAO,MAAM,cAAc,QAAqB,CAAC;AAKjD,eAAO,MAAM,gBAAgB,QAAa,CAAC;AAE3C,eAAO,MAAM,aAAa,GAAI,OAAO,OAAO,KAAG,OAEW,CAAC;AAE3D,eAAO,MAAM,QAAQ,SAAS,CAAC;AAC/B,eAAO,MAAM,SAAS,+BAA0B,CAAC;AACjD,eAAO,MAAM,QAAQ,eAAe,CAAC;AAIrC,eAAO,MAAM,cAAc,IAAI,CAAC;AAOhC,eAAO,MAAM,YAAY,GAAI,KAAK,MAAM,KAAG,MACH,CAAC;AAUzC,eAAO,MAAM,WAAW,GAAI,KAAK,MAAM,KAAG,OACH,CAAC;AACxC,eAAO,MAAM,KAAK,GAAI,KAAK,MAAM,KAAG,OAA0C,CAAC;AAY/E,eAAO,MAAM,cAAc,GAAI,KAAK,MAAM,EAAE,OAAO,OAAO,KAAG,OAEkB,CAAC;AAEhF,eAAO,MAAM,mBAAmB,GAAI,KAAK,MAAM,KAAG,OACD,CAAC;AAElD,eAAO,MAAM,mBAAmB,GAAI,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,OACM,CAAC;AAK1E,eAAO,MAAM,OAAO,GAAI,OAAO,OAAO,KAAG,OAgBxC,CAAC;AAIF,eAAO,MAAM,eAAe,GAC1B,SAAS,mBAAmB,GAAG,SAAS,KACvC,MAAM,CAAC,MAAM,EAAE,OAAO,CAcxB,CAAC;AAcF,eAAO,MAAM,aAAa,GAAI,CAAC,EAC7B,OAAO,CAAC,EACR,cAAS,EACT,sBAA4B,KAC3B,CA4CF,CAAC;AAMF,eAAO,MAAM,OAAO,GAAI,KAAK,MAAM,KAAG,MA8BrC,CAAC;AAOF,eAAO,MAAM,aAAa,GACxB,KAAK,OAAO,KACX;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAUlD,CAAC"}

package/dist/index.js

@@ -0,0 +1,274 @@
+"use strict";
+/* eslint-disable @typescript-eslint/no-explicit-any */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeError = exports.maskUrl = exports.maskSensitive = exports.pickSafeHeaders = exports.maskPii = exports.isOidcCallbackShape = exports.isOauthCallbackOnly = exports.isAmbiguousPii = exports.isPii = exports.isSensitive = exports.normalizeKey = exports.MAX_MASK_DEPTH = exports.CIRCULAR = exports.TRUNCATED = exports.REDACTED = exports.looksPersonal = exports.FORMATTING_NOISE = exports.LOOKS_PERSONAL = exports.AMBIGUOUS_PII_FIELDS = exports.PII_FIELDS = exports.OIDC_CALLBACK_MARKERS = exports.OAUTH_CALLBACK_ONLY_FIELDS = exports.SENSITIVE_FIELDS = exports.SAFE_HEADERS = void 0;
+// Allowlist: só o que está listado aqui chega ao log. Uma denylist
+// (`delete headers.authorization`) falharia em silêncio no dia em que alguém
+// adicionasse um header novo carregando credencial.
+// Ficam de fora, por serem credencial viva: `authorization`, `cookie`,
+// `gyra-client-secret`. O `gyra-client-id` também fica de fora: sozinho é só
+// um identificador, mas emparelhado com o secret num mesmo log facilita ataque.
+exports.SAFE_HEADERS = [
+    'x-amzn-trace-id',
+    'x-forwarded-for',
+    'user-agent',
+    'content-type',
+    'content-length',
+];
+// Credencial: o valor não tem utilidade nenhuma no log, vai inteiro para `****`.
+exports.SENSITIVE_FIELDS = [
+    'password',
+    'token',
+    'accessToken',
+    'refreshToken',
+    'passwordResetToken',
+    'deletionToken',
+    'clientSecret',
+    'apiKey',
+    'apiSecret',
+    'secret',
+    'credentials',
+    'authorization',
+    // Fluxo OAuth: `code` é o authorization code, `idToken` o id token, `state`
+    // o nonce anti-CSRF — todos chegam por query no callback, que cai no
+    // interceptor global.
+    //
+    // `code` não é só OAuth: é o código de login de uso único do
+    // gyra-communication (`GoLoginCodePayload.code`, 6 dígitos, TTL de 5 min,
+    // lido de `payload.code` em `POST /communicate`). Nenhum DTO da plataforma
+    // usa `code` como campo não sensível.
+    'code',
+    'idToken',
+];
+// `state` é o nonce anti-CSRF do OAuth. Na query ele é sempre OAuth. No body só
+// é OAuth no callback OIDC com `responseMode: 'form_post'` — o do Microsoft
+// (`microsoft-oauth.strategy.ts:19`, `responseType: 'code id_token'`), numa rota
+// `@Post` com `@Req()` e sem DTO, que é por isso que uma varredura por DTO não
+// o enxerga. Fora dali, `state` é UF de endereço no domínio de bureau.
+//
+// No body, portanto, só mascara quando a assinatura do callback OIDC está
+// presente: `code` ou `idToken` no mesmo objeto. Um payload de endereço não tem
+// nenhum dos dois.
+exports.OAUTH_CALLBACK_ONLY_FIELDS = ['state'];
+// Presença destas chaves marca o objeto como callback OIDC.
+exports.OIDC_CALLBACK_MARKERS = ['code', 'idToken'];
+// Dado pessoal: categoria distinta de credencial. Não pode ir em plain text —
+// requisito LGPD já vigente na plataforma, registrado em
+// `gyra-integration/specs/001-scr-raw-data-api/spec.md:179` — mas, diferente de
+// credencial, aqui o domínio do e-mail é preservado: ele não identifica pessoa e
+// é o que diz de qual organização veio a chamada, a única atribuição que resta
+// nos serviços sem guard.
+//
+// `username` está aqui porque no gyra-auth ele É o e-mail ou o CPF: o
+// `IsUsername` valida `isEmail || isCPF`. Mascarar `email` e deixar `username`
+// em claro não mascararia nada em login, signup e reset de senha.
+//
+// `documentType` e `documentTypes` NÃO entram: são enums (CPF/CNPJ), não
+// valores. A comparação é por chave exata, então ficam de fora naturalmente —
+// um match por substring em "document" os pegaria e perderia informação útil.
+exports.PII_FIELDS = [
+    'email',
+    'signerEmail',
+    'username',
+    'cpf',
+    'cnpj',
+    'document',
+    'documents',
+    'newDocument',
+    'signerDocument',
+    'phone',
+    'phoneNumber',
+    'signerPhoneNumber',
+    'signerName',
+];
+// Chaves cujo significado varia entre os 15 serviços. Aqui a decisão é pelo
+// VALOR, não pelo nome: `to` é destinatário de e-mail no gyra-communication, mas
+// é data ISO em `UsageQueryDto.to` (gyra-billing) e limite de faixa numérica em
+// `CreateDto.to: number` (gyra-core e gyra-credit-policy, 6 DTOs). Mascarar por
+// nome apagaria o campo que se quer ver ao depurar faixa de risco ou intervalo
+// de cobrança — a mesma disciplina já aplicada ao `documentType`.
+exports.AMBIGUOUS_PII_FIELDS = ['to'];
+// Casa e-mail e telefone; não casa data ISO nem número pequeno. Erra para o
+// lado de mascarar: um epoch em milissegundos tem 13 dígitos e seria mascarado —
+// aceitável, porque nenhum `to` da plataforma carrega epoch hoje e o custo de
+// errar para o outro lado é vazar dado pessoal.
+exports.LOOKS_PERSONAL = /@|^\+?\d{10,14}$/;
+// Espaço, parêntese e hífen saem antes do teste, senão `(81) 99999-9999` passa.
+// Isto não reabre o falso-positivo de data: `2026-01-31` sem hífen tem 8
+// dígitos, abaixo do mínimo de 10.
+exports.FORMATTING_NOISE = /[\s()-]/g;
+const looksPersonal = (value) => typeof value === 'string' &&
+    exports.LOOKS_PERSONAL.test(value.replace(exports.FORMATTING_NOISE, ''));
+exports.looksPersonal = looksPersonal;
+exports.REDACTED = '****';
+exports.TRUNCATED = '[profundidade máxima]';
+exports.CIRCULAR = '[circular]';
+// Profundidade máxima do mascaramento. Limita o custo por requisição e é o que
+// impede laço infinito em objeto cíclico.
+exports.MAX_MASK_DEPTH = 4;
+// Comparação normalizada — minúsculas e sem separador. Sem isto a lista é uma
+// denylist frágil: `Password`, `Token`, `Authorization`, `access_token`,
+// `client_secret`, `api_key` e `refresh_token` passariam inteiros, por não
+// baterem exatamente com o camelCase da lista. Nenhum DTO atual usa esses
+// nomes, mas a lista não pode depender disso.
+const normalizeKey = (key) => key.toLowerCase().replace(/[_-]/g, '');
+exports.normalizeKey = normalizeKey;
+const SENSITIVE_KEYS = new Set(exports.SENSITIVE_FIELDS.map(exports.normalizeKey));
+const OAUTH_CALLBACK_ONLY_KEYS = new Set(exports.OAUTH_CALLBACK_ONLY_FIELDS.map(exports.normalizeKey));
+const OIDC_MARKER_KEYS = new Set(exports.OIDC_CALLBACK_MARKERS.map(exports.normalizeKey));
+const PII_KEYS = new Set(exports.PII_FIELDS.map(exports.normalizeKey));
+const AMBIGUOUS_PII_KEYS = new Set(exports.AMBIGUOUS_PII_FIELDS.map(exports.normalizeKey));
+const isSensitive = (key) => SENSITIVE_KEYS.has((0, exports.normalizeKey)(key));
+exports.isSensitive = isSensitive;
+const isPii = (key) => PII_KEYS.has((0, exports.normalizeKey)(key));
+exports.isPii = isPii;
+// Chave ambígua: só é PII se o valor parecer dado pessoal.
+//
+// O ramo de array é obrigatório, não conveniência: `InternalAlertDto.to` é
+// `string | string[]` (`@IsArray()` + `@IsString({ each: true })`), e o
+// controller exige `@` em todo destinatário. Sem ele o array cai no ramo comum
+// do `maskSensitive`, que devolve as strings intactas.
+//
+// `some` e não `every`: numa lista mista basta um destinatário parecer pessoal
+// para a lista inteira precisar de mascaramento, e o `maskPii` já preserva o
+// domínio elemento a elemento.
+const isAmbiguousPii = (key, value) => AMBIGUOUS_PII_KEYS.has((0, exports.normalizeKey)(key)) &&
+    ((0, exports.looksPersonal)(value) || (Array.isArray(value) && value.some(exports.looksPersonal)));
+exports.isAmbiguousPii = isAmbiguousPii;
+const isOauthCallbackOnly = (key) => OAUTH_CALLBACK_ONLY_KEYS.has((0, exports.normalizeKey)(key));
+exports.isOauthCallbackOnly = isOauthCallbackOnly;
+const isOidcCallbackShape = (obj) => Object.keys(obj).some((key) => OIDC_MARKER_KEYS.has((0, exports.normalizeKey)(key)));
+exports.isOidcCallbackShape = isOidcCallbackShape;
+// `null`/`undefined` passam intactos, para a linha continuar dizendo que o campo
+// veio vazio. Qualquer valor que não seja string vira `****` — não há como
+// preservar domínio de um número ou de um objeto.
+const maskPii = (value) => {
+    if (Array.isArray(value)) {
+        return value.map(exports.maskPii);
+    }
+    if (value === null || value === undefined) {
+        return value;
+    }
+    if (typeof value !== 'string') {
+        return exports.REDACTED;
+    }
+    const at = value.lastIndexOf('@');
+    return at > 0 ? `${exports.REDACTED}${value.slice(at)}` : exports.REDACTED;
+};
+exports.maskPii = maskPii;
+// Node normaliza os nomes dos headers de entrada para minúsculas em
+// `req.headers`, então a comparação é direta.
+const pickSafeHeaders = (headers) => {
+    const safeHeaders = {};
+    if (!headers) {
+        return safeHeaders;
+    }
+    for (const name of exports.SAFE_HEADERS) {
+        if (headers[name] !== undefined) {
+            safeHeaders[name] = headers[name];
+        }
+    }
+    return safeHeaders;
+};
+exports.pickSafeHeaders = pickSafeHeaders;
+// Recursivo até `MAX_MASK_DEPTH`: nem todo DTO da plataforma tem o campo
+// sensível na raiz — `credentials: { username, password }` e
+// `payload: { passwordResetToken }` são reais e ficariam de fora de um
+// mascaramento de um nível só.
+//
+// Além do limite, o subobjeto é substituído por um marcador em vez de voltar
+// cru: se voltasse cru, um segredo mais fundo que o limite escaparia — que é
+// exatamente o que esta função existe para impedir.
+//
+// O `seen` corta ciclo. Body vindo de `JSON.parse` é sempre árvore, mas
+// payload de mensagem não precisa ser, e um ciclo aqui derrubaria a
+// serialização do Winston em runtime, não só o mascaramento.
+const maskSensitive = (value, depth = 0, seen = new WeakSet()) => {
+    if (!value || typeof value !== 'object') {
+        return value;
+    }
+    if (depth > exports.MAX_MASK_DEPTH) {
+        return exports.TRUNCATED;
+    }
+    if (seen.has(value)) {
+        return exports.CIRCULAR;
+    }
+    seen.add(value);
+    try {
+        if (Array.isArray(value)) {
+            return value.map((item) => (0, exports.maskSensitive)(item, depth + 1, seen));
+        }
+        const masked = {
+            ...value,
+        };
+        const oidcCallback = (0, exports.isOidcCallbackShape)(masked);
+        for (const [key, nested] of Object.entries(masked)) {
+            if ((0, exports.isSensitive)(key) || (oidcCallback && (0, exports.isOauthCallbackOnly)(key))) {
+                masked[key] = exports.REDACTED;
+            }
+            else if ((0, exports.isPii)(key) || (0, exports.isAmbiguousPii)(key, nested)) {
+                masked[key] = (0, exports.maskPii)(nested);
+            }
+            else {
+                masked[key] = (0, exports.maskSensitive)(nested, depth + 1, seen);
+            }
+        }
+        return masked;
+    }
+    finally {
+        // Sai do `seen` ao desempilhar: o conjunto passa a representar o caminho
+        // atual, não tudo que já foi visitado. Sem isto, `{ a: shared, b: shared }`
+        // — mesmo objeto referenciado duas vezes, sem ciclo nenhum — saía com
+        // `b: "[circular]"`.
+        seen.delete(value);
+    }
+};
+exports.maskSensitive = maskSensitive;
+// `request.url` carrega a query string, e há rota que recebe token por query
+// (`GET /user?passwordResetToken=…`) e rota que recebe o próprio username
+// (`FindUserDto.username` em `GET /user`). Mascara o valor e preserva a chave,
+// para a linha continuar dizendo qual parâmetro veio.
+const maskUrl = (url) => {
+    if (typeof url !== 'string') {
+        return url;
+    }
+    const separator = url.indexOf('?');
+    if (separator === -1) {
+        return url;
+    }
+    const path = url.slice(0, separator);
+    const params = new URLSearchParams(url.slice(separator + 1));
+    const masked = new URLSearchParams();
+    // Percorre par a par e reconstrói: `params.set` mantinha só a primeira
+    // ocorrência da chave e descartava o resto, então `?document=111&document=222`
+    // saía como `document=****` — a linha perdia a informação de que vieram dois
+    // valores.
+    for (const [key, value] of params) {
+        if ((0, exports.isSensitive)(key) || (0, exports.isOauthCallbackOnly)(key)) {
+            masked.append(key, exports.REDACTED);
+        }
+        else if ((0, exports.isPii)(key) || (0, exports.isAmbiguousPii)(key, value)) {
+            masked.append(key, String((0, exports.maskPii)(value)));
+        }
+        else {
+            masked.append(key, value);
+        }
+    }
+    return `${path}?${masked.toString()}`;
+};
+exports.maskUrl = maskUrl;
+// Nunca o objeto de erro inteiro: um AxiosError carrega
+// `config.headers.Authorization`. `name` e `stack` não carregam header nenhum
+// e são o que torna a linha acionável para quem está de plantão.
+// O `String(err)` cobre rejeição que não é `Error` — sem ele a linha sairia
+// com `error: undefined` e o operador não teria nada.
+const describeError = (err) => {
+    const error = err;
+    return {
+        name: error?.name,
+        message: error?.message ?? String(err),
+        stack: error?.stack,
+    };
+};
+exports.describeError = describeError;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@gyramais/log-redaction",
+  "version": "0.1.0",
+  "description": "Mascaramento de credencial e dado pessoal no log dos servicos gyra-*",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gyramais/gyra-libs.git",
+    "directory": "packages/log-redaction"
+  },
+  "license": "ISC",
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json && node ../../scripts/verify-build.js",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "jest --randomize",
+    "test:cov": "jest --coverage",
+    "prepack": "npm run build"
+  }
+}

package/src/index.ts

@@ -0,0 +1,339 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+/*
+  Padrao de mascaramento de log dos servicos gyra-*.
+
+  PROVENIENCIA: extraido byte a byte de
+  gyra-core/src/common/interceptors/logging-interceptor.ts apos a GYR-1541, onde o
+  mesmo bloco existia duplicado e identico nos 15 servicos
+  (md5 cc04916718f5db4c776d256fc05068b3, 313 linhas, conferido nos 15 em main).
+
+  A unica alteracao em relacao a fonte e a visibilidade: as declaracoes ganharam
+  `export`. Nenhuma assinatura, nenhum comportamento e nenhum comentario foi
+  alterado — os comentarios registram seis rodadas de revisao e tres revisoes
+  humanas, e explicam decisoes que ja foram questionadas e defendidas.
+
+  API que os servicos consomem: maskSensitive, maskUrl, pickSafeHeaders,
+  describeError — os quatro usados por todas as 9 variantes da classe
+  LoggingInterceptor. O resto e exportado para a suite exercitar cada predicado
+  direto, em vez de dirigir o interceptor.
+
+  A classe LoggingInterceptor NAO faz parte deste pacote: sao 9 variantes entre os
+  15 servicos, e cada um mantem a sua.
+*/
+
+import type { IncomingHttpHeaders } from 'http';
+
+// Allowlist: só o que está listado aqui chega ao log. Uma denylist
+// (`delete headers.authorization`) falharia em silêncio no dia em que alguém
+// adicionasse um header novo carregando credencial.
+// Ficam de fora, por serem credencial viva: `authorization`, `cookie`,
+// `gyra-client-secret`. O `gyra-client-id` também fica de fora: sozinho é só
+// um identificador, mas emparelhado com o secret num mesmo log facilita ataque.
+export const SAFE_HEADERS = [
+  'x-amzn-trace-id',
+  'x-forwarded-for',
+  'user-agent',
+  'content-type',
+  'content-length',
+];
+
+// Credencial: o valor não tem utilidade nenhuma no log, vai inteiro para `****`.
+export const SENSITIVE_FIELDS = [
+  'password',
+  'token',
+  'accessToken',
+  'refreshToken',
+  'passwordResetToken',
+  'deletionToken',
+  'clientSecret',
+  'apiKey',
+  'apiSecret',
+  'secret',
+  'credentials',
+  'authorization',
+  // Fluxo OAuth: `code` é o authorization code, `idToken` o id token, `state`
+  // o nonce anti-CSRF — todos chegam por query no callback, que cai no
+  // interceptor global.
+  //
+  // `code` não é só OAuth: é o código de login de uso único do
+  // gyra-communication (`GoLoginCodePayload.code`, 6 dígitos, TTL de 5 min,
+  // lido de `payload.code` em `POST /communicate`). Nenhum DTO da plataforma
+  // usa `code` como campo não sensível.
+  'code',
+  'idToken',
+];
+
+// `state` é o nonce anti-CSRF do OAuth. Na query ele é sempre OAuth. No body só
+// é OAuth no callback OIDC com `responseMode: 'form_post'` — o do Microsoft
+// (`microsoft-oauth.strategy.ts:19`, `responseType: 'code id_token'`), numa rota
+// `@Post` com `@Req()` e sem DTO, que é por isso que uma varredura por DTO não
+// o enxerga. Fora dali, `state` é UF de endereço no domínio de bureau.
+//
+// No body, portanto, só mascara quando a assinatura do callback OIDC está
+// presente: `code` ou `idToken` no mesmo objeto. Um payload de endereço não tem
+// nenhum dos dois.
+export const OAUTH_CALLBACK_ONLY_FIELDS = ['state'];
+
+// Presença destas chaves marca o objeto como callback OIDC.
+export const OIDC_CALLBACK_MARKERS = ['code', 'idToken'];
+
+// Dado pessoal: categoria distinta de credencial. Não pode ir em plain text —
+// requisito LGPD já vigente na plataforma, registrado em
+// `gyra-integration/specs/001-scr-raw-data-api/spec.md:179` — mas, diferente de
+// credencial, aqui o domínio do e-mail é preservado: ele não identifica pessoa e
+// é o que diz de qual organização veio a chamada, a única atribuição que resta
+// nos serviços sem guard.
+//
+// `username` está aqui porque no gyra-auth ele É o e-mail ou o CPF: o
+// `IsUsername` valida `isEmail || isCPF`. Mascarar `email` e deixar `username`
+// em claro não mascararia nada em login, signup e reset de senha.
+//
+// `documentType` e `documentTypes` NÃO entram: são enums (CPF/CNPJ), não
+// valores. A comparação é por chave exata, então ficam de fora naturalmente —
+// um match por substring em "document" os pegaria e perderia informação útil.
+export const PII_FIELDS = [
+  'email',
+  'signerEmail',
+  'username',
+  'cpf',
+  'cnpj',
+  'document',
+  'documents',
+  'newDocument',
+  'signerDocument',
+  'phone',
+  'phoneNumber',
+  'signerPhoneNumber',
+  'signerName',
+];
+
+// Chaves cujo significado varia entre os 15 serviços. Aqui a decisão é pelo
+// VALOR, não pelo nome: `to` é destinatário de e-mail no gyra-communication, mas
+// é data ISO em `UsageQueryDto.to` (gyra-billing) e limite de faixa numérica em
+// `CreateDto.to: number` (gyra-core e gyra-credit-policy, 6 DTOs). Mascarar por
+// nome apagaria o campo que se quer ver ao depurar faixa de risco ou intervalo
+// de cobrança — a mesma disciplina já aplicada ao `documentType`.
+export const AMBIGUOUS_PII_FIELDS = ['to'];
+
+// Casa e-mail e telefone; não casa data ISO nem número pequeno. Erra para o
+// lado de mascarar: um epoch em milissegundos tem 13 dígitos e seria mascarado —
+// aceitável, porque nenhum `to` da plataforma carrega epoch hoje e o custo de
+// errar para o outro lado é vazar dado pessoal.
+export const LOOKS_PERSONAL = /@|^\+?\d{10,14}$/;
+
+// Espaço, parêntese e hífen saem antes do teste, senão `(81) 99999-9999` passa.
+// Isto não reabre o falso-positivo de data: `2026-01-31` sem hífen tem 8
+// dígitos, abaixo do mínimo de 10.
+export const FORMATTING_NOISE = /[\s()-]/g;
+
+export const looksPersonal = (value: unknown): boolean =>
+  typeof value === 'string' &&
+  LOOKS_PERSONAL.test(value.replace(FORMATTING_NOISE, ''));
+
+export const REDACTED = '****';
+export const TRUNCATED = '[profundidade máxima]';
+export const CIRCULAR = '[circular]';
+
+// Profundidade máxima do mascaramento. Limita o custo por requisição e é o que
+// impede laço infinito em objeto cíclico.
+export const MAX_MASK_DEPTH = 4;
+
+// Comparação normalizada — minúsculas e sem separador. Sem isto a lista é uma
+// denylist frágil: `Password`, `Token`, `Authorization`, `access_token`,
+// `client_secret`, `api_key` e `refresh_token` passariam inteiros, por não
+// baterem exatamente com o camelCase da lista. Nenhum DTO atual usa esses
+// nomes, mas a lista não pode depender disso.
+export const normalizeKey = (key: string): string =>
+  key.toLowerCase().replace(/[_-]/g, '');
+
+const SENSITIVE_KEYS = new Set(SENSITIVE_FIELDS.map(normalizeKey));
+const OAUTH_CALLBACK_ONLY_KEYS = new Set(
+  OAUTH_CALLBACK_ONLY_FIELDS.map(normalizeKey),
+);
+const OIDC_MARKER_KEYS = new Set(OIDC_CALLBACK_MARKERS.map(normalizeKey));
+const PII_KEYS = new Set(PII_FIELDS.map(normalizeKey));
+const AMBIGUOUS_PII_KEYS = new Set(AMBIGUOUS_PII_FIELDS.map(normalizeKey));
+
+export const isSensitive = (key: string): boolean =>
+  SENSITIVE_KEYS.has(normalizeKey(key));
+export const isPii = (key: string): boolean => PII_KEYS.has(normalizeKey(key));
+
+// Chave ambígua: só é PII se o valor parecer dado pessoal.
+//
+// O ramo de array é obrigatório, não conveniência: `InternalAlertDto.to` é
+// `string | string[]` (`@IsArray()` + `@IsString({ each: true })`), e o
+// controller exige `@` em todo destinatário. Sem ele o array cai no ramo comum
+// do `maskSensitive`, que devolve as strings intactas.
+//
+// `some` e não `every`: numa lista mista basta um destinatário parecer pessoal
+// para a lista inteira precisar de mascaramento, e o `maskPii` já preserva o
+// domínio elemento a elemento.
+export const isAmbiguousPii = (key: string, value: unknown): boolean =>
+  AMBIGUOUS_PII_KEYS.has(normalizeKey(key)) &&
+  (looksPersonal(value) || (Array.isArray(value) && value.some(looksPersonal)));
+
+export const isOauthCallbackOnly = (key: string): boolean =>
+  OAUTH_CALLBACK_ONLY_KEYS.has(normalizeKey(key));
+
+export const isOidcCallbackShape = (obj: Record<string, unknown>): boolean =>
+  Object.keys(obj).some((key) => OIDC_MARKER_KEYS.has(normalizeKey(key)));
+
+// `null`/`undefined` passam intactos, para a linha continuar dizendo que o campo
+// veio vazio. Qualquer valor que não seja string vira `****` — não há como
+// preservar domínio de um número ou de um objeto.
+export const maskPii = (value: unknown): unknown => {
+  if (Array.isArray(value)) {
+    return value.map(maskPii);
+  }
+
+  if (value === null || value === undefined) {
+    return value;
+  }
+
+  if (typeof value !== 'string') {
+    return REDACTED;
+  }
+
+  const at = value.lastIndexOf('@');
+
+  return at > 0 ? `${REDACTED}${value.slice(at)}` : REDACTED;
+};
+
+// Node normaliza os nomes dos headers de entrada para minúsculas em
+// `req.headers`, então a comparação é direta.
+export const pickSafeHeaders = (
+  headers: IncomingHttpHeaders | undefined,
+): Record<string, unknown> => {
+  const safeHeaders: Record<string, unknown> = {};
+
+  if (!headers) {
+    return safeHeaders;
+  }
+
+  for (const name of SAFE_HEADERS) {
+    if (headers[name] !== undefined) {
+      safeHeaders[name] = headers[name];
+    }
+  }
+
+  return safeHeaders;
+};
+
+// Recursivo até `MAX_MASK_DEPTH`: nem todo DTO da plataforma tem o campo
+// sensível na raiz — `credentials: { username, password }` e
+// `payload: { passwordResetToken }` são reais e ficariam de fora de um
+// mascaramento de um nível só.
+//
+// Além do limite, o subobjeto é substituído por um marcador em vez de voltar
+// cru: se voltasse cru, um segredo mais fundo que o limite escaparia — que é
+// exatamente o que esta função existe para impedir.
+//
+// O `seen` corta ciclo. Body vindo de `JSON.parse` é sempre árvore, mas
+// payload de mensagem não precisa ser, e um ciclo aqui derrubaria a
+// serialização do Winston em runtime, não só o mascaramento.
+export const maskSensitive = <T>(
+  value: T,
+  depth = 0,
+  seen = new WeakSet<object>(),
+): T => {
+  if (!value || typeof value !== 'object') {
+    return value;
+  }
+
+  if (depth > MAX_MASK_DEPTH) {
+    return TRUNCATED as T;
+  }
+
+  if (seen.has(value as object)) {
+    return CIRCULAR as T;
+  }
+
+  seen.add(value as object);
+
+  try {
+    if (Array.isArray(value)) {
+      return value.map((item) => maskSensitive(item, depth + 1, seen)) as T;
+    }
+
+    const masked: Record<string, unknown> = {
+      ...(value as Record<string, unknown>),
+    };
+
+    const oidcCallback = isOidcCallbackShape(masked);
+
+    for (const [key, nested] of Object.entries(masked)) {
+      if (isSensitive(key) || (oidcCallback && isOauthCallbackOnly(key))) {
+        masked[key] = REDACTED;
+      } else if (isPii(key) || isAmbiguousPii(key, nested)) {
+        masked[key] = maskPii(nested);
+      } else {
+        masked[key] = maskSensitive(nested, depth + 1, seen);
+      }
+    }
+
+    return masked as T;
+  } finally {
+    // Sai do `seen` ao desempilhar: o conjunto passa a representar o caminho
+    // atual, não tudo que já foi visitado. Sem isto, `{ a: shared, b: shared }`
+    // — mesmo objeto referenciado duas vezes, sem ciclo nenhum — saía com
+    // `b: "[circular]"`.
+    seen.delete(value as object);
+  }
+};
+
+// `request.url` carrega a query string, e há rota que recebe token por query
+// (`GET /user?passwordResetToken=…`) e rota que recebe o próprio username
+// (`FindUserDto.username` em `GET /user`). Mascara o valor e preserva a chave,
+// para a linha continuar dizendo qual parâmetro veio.
+export const maskUrl = (url: string): string => {
+  if (typeof url !== 'string') {
+    return url;
+  }
+
+  const separator = url.indexOf('?');
+
+  if (separator === -1) {
+    return url;
+  }
+
+  const path = url.slice(0, separator);
+  const params = new URLSearchParams(url.slice(separator + 1));
+  const masked = new URLSearchParams();
+
+  // Percorre par a par e reconstrói: `params.set` mantinha só a primeira
+  // ocorrência da chave e descartava o resto, então `?document=111&document=222`
+  // saía como `document=****` — a linha perdia a informação de que vieram dois
+  // valores.
+  for (const [key, value] of params) {
+    if (isSensitive(key) || isOauthCallbackOnly(key)) {
+      masked.append(key, REDACTED);
+    } else if (isPii(key) || isAmbiguousPii(key, value)) {
+      masked.append(key, String(maskPii(value)));
+    } else {
+      masked.append(key, value);
+    }
+  }
+
+  return `${path}?${masked.toString()}`;
+};
+
+// Nunca o objeto de erro inteiro: um AxiosError carrega
+// `config.headers.Authorization`. `name` e `stack` não carregam header nenhum
+// e são o que torna a linha acionável para quem está de plantão.
+// O `String(err)` cobre rejeição que não é `Error` — sem ele a linha sairia
+// com `error: undefined` e o operador não teria nada.
+export const describeError = (
+  err: unknown,
+): { name?: string; message: string; stack?: string } => {
+  const error = err as
+    | { name?: string; message?: string; stack?: string }
+    | undefined;
+
+  return {
+    name: error?.name,
+    message: error?.message ?? String(err),
+    stack: error?.stack,
+  };
+};
+