Secret Management no Node.js

Secret management é o processo de criar, armazenar, distribuir, usar, rotacionar e revogar credenciais com segurança. Em aplicações Node.js, secrets incluem senhas de banco, tokens de API, chaves privadas, certificados, credenciais de cloud e chaves de criptografia.

Guardar secrets em código, repositório, imagem Docker ou arquivo compartilhado aumenta o risco de vazamento. Uma estratégia madura usa identidade da workload, secret manager, acesso mínimo, rotação e auditoria.

O que é secret

• senha de banco;
• API key;
• token OAuth;
• chave privada TLS;
• chave de assinatura JWT;
• credential de serviço;
• seed criptográfica;
• webhook secret;
• certificado de cliente;
• recovery code.

URLs e nomes de host normalmente são configuração, não secret, a menos que contenham credenciais.

Não hardcode

// Inseguro
const apiKey = 'sk_live_exemplo';

Mesmo repositório privado pode vazar por clone, backup, logs, CI, dependência comprometida ou acesso interno excessivo.

Variável de ambiente

const apiKey = process.env.PAYMENTS_API_KEY;

if (!apiKey) {
  throw new Error('PAYMENTS_API_KEY ausente');
}

É melhor que hardcode, mas variáveis podem aparecer em dumps, ferramentas de processo e configurações. Use quando a plataforma protege a injeção e o risco é aceito.

Secret manager

Serviços dedicados armazenam versões, políticas e auditoria. O fluxo ideal é:

1. workload obtém identidade sem secret estático;
2. solicita acesso ao secret autorizado;
3. recebe valor por canal seguro;
4. mantém em memória pelo tempo necessário;
5. renova ou busca nova versão;
6. revoga acesso quando a workload termina.

Evite secret zero

Se a aplicação precisa de uma senha longa para acessar o secret manager, você apenas moveu o problema. Prefira identidade de instância, service account, workload identity ou autenticação mTLS automatizada.

Princípio do menor privilégio

Uma aplicação deve acessar apenas secrets necessários:

orders-service → database/orders
orders-service → payments/client-token
orders-service ✗ database/admin

Separe ambientes, serviços e funções.

Não compartilhar credencial

Cada serviço deve ter identidade própria. Compartilhar uma senha entre dezenas de aplicações dificulta rotação e auditoria.

Carregamento no startup

async function loadSecrets(secretClient) {
  const [databasePassword, paymentToken] = await Promise.all([
    secretClient.get('database/orders/password'),
    secretClient.get('payments/orders/token'),
  ]);

  return Object.freeze({
    databasePassword,
    paymentToken,
  });
}

Defina timeout, retries limitados e falhe antes de marcar readiness.

Busca sob demanda

Para secrets raros ou rotacionados frequentemente, busque sob demanda com cache curto. Não consulte o secret manager em toda requisição de alto volume.

Cache em memória

Armazene apenas o tempo necessário. Um cache precisa de:

• TTL;
• renovação antecipada;
• limite;
• tratamento de versão;
• fallback controlado;
• limpeza no shutdown.

O valor continuará presente na memória e pode aparecer em dumps.

Rotação

Rotação segura geralmente possui sobreposição:

1. criar nova credencial;
2. permitir antiga e nova;
3. distribuir nova;
4. confirmar uso;
5. revogar antiga;
6. auditar resultado.

Trocar instantaneamente sem sobreposição pode causar indisponibilidade.

Rotação de senha de banco

Conexões existentes podem continuar autenticadas. Novas usam a senha nova. O pool precisa reciclar conexões gradualmente e suportar transição.

Dual credentials

Alguns sistemas permitem dois usuários ou chaves ativos durante rotação. Isso reduz risco e facilita rollback.

Versões

Secret managers costumam manter versões e aliases como current e previous. A aplicação pode registrar somente a versão, nunca o valor.

Reload

Alternativas:

• restart gradual após atualização;
• polling de versão;
• evento de rotação;
• arquivo montado atualizado;
• sidecar ou agent.

Restart gradual é simples e previsível. Reload dinâmico exige sincronização.

Arquivos montados

Certificados e chaves podem ser montados em volume somente leitura:

import { readFile } from 'node:fs/promises';

const privateKey = await readFile('/var/run/secrets/tls.key');

Restrinja permissões e não registre o conteúdo.

Atualização de arquivo

Volumes podem substituir arquivos de forma atômica. Não mantenha file descriptor antigo indefinidamente se precisa detectar rotação. Faça polling de metadata ou restart.

Kubernetes Secrets

Kubernetes Secret codifica dados em base64, mas isso não é criptografia. Proteja etcd, RBAC, namespaces, service accounts e acesso ao pod. Considere integração com secret manager externo.

Docker

Não use:

ENV DATABASE_PASSWORD=senha

O valor pode ficar em camadas e metadados. Injete no runtime ou use secret mount.

CI/CD

O pipeline deve usar credenciais curtas e escopadas. Evite secrets em argumentos de linha de comando, pois podem aparecer em logs.

OIDC no CI

Quando disponível, CI usa OIDC para obter credenciais temporárias da cloud sem armazenar access key permanente.

Credenciais temporárias

Tokens de curta duração reduzem impacto de vazamento. A aplicação precisa renovar antes de expirar e lidar com falha de renovação.

Chaves de criptografia

Uma chave usada para criptografar dados não deve ficar junto dos dados. Use KMS, envelope encryption e políticas de uso. Não exporte chave mestra quando o serviço pode operar sem revelá-la.

Envelope encryption

Uma data key criptografa o dado; uma master key do KMS protege a data key. Isso permite rotação e controle central sem enviar grandes dados ao KMS.

JWT

Para assinatura, prefira chaves assimétricas quando múltiplos serviços verificam tokens. O emissor guarda a chave privada; verificadores recebem apenas a pública.

JWKS

Publique chaves públicas com identificadores e suporte rotação. Validadores devem cachear com TTL e aceitar período de sobreposição.

Webhook secret

Valide assinatura sobre o corpo bruto, timestamp e tolerância de replay. Faça comparação em tempo constante quando aplicável.

Logs

Redija:

• Authorization;
• Cookie;
• password;
• token;
• apiKey;
• privateKey;
• connection string com credencial.

Não registre o objeto process.env.

Erros

Mensagens de erro de clientes podem incluir URL e headers. Sanitize antes do log. Não devolva detalhes ao usuário.

Dumps e Process Reports

Heap snapshots, core dumps e process reports podem conter secrets em memória e variáveis. Trate como dados altamente sensíveis, controle acesso e retenção.

Debugging

Não peça para alguém colar secret em chat ou ticket. Use ferramenta segura para verificar presença, versão e permissão.

Scanning

Use scanners no pre-commit, CI e repositório. Detectar um secret não basta: revogue e rotacione, pois remover do commit atual não apaga o histórico.

Secret vazado

1. revogar imediatamente;
2. emitir nova credencial;
3. identificar acessos;
4. conter impacto;
5. remover de logs e artefatos quando permitido;
6. corrigir o fluxo;
7. documentar incidente.

Não confiar em apagar commit

O secret pode ter sido clonado, indexado ou armazenado em cache. Rotação é obrigatória.

Auditoria

Registre quem ou qual workload leu, alterou ou revogou um secret. Alertas devem detectar acesso fora do padrão.

Break glass

Acesso de emergência deve ser temporário, auditado, aprovado e revogado após uso.

Separação de funções

Quem desenvolve não precisa necessariamente acessar secrets de produção. Use ambientes e papéis separados.

Backups

Backups de secrets devem ser criptografados e testados. A recuperação precisa preservar controle de acesso.

Disponibilidade

Secret manager é dependência crítica. Use redundância, cache controlado e estratégia de startup. Não deixe a aplicação operar indefinidamente com credencial expirada.

Fail open ou fail closed

Para autenticação e criptografia, falhe fechado. Para uma integração opcional, pode ser possível iniciar em modo degradado sem o secret específico.

Readiness

Marque pronto somente quando secrets essenciais e conexões dependentes estiverem válidos. Uma rotação falha deve gerar alerta antes da expiração.

Métricas

Meça sem valores:

• leituras por secret lógico;
• erros;
• latência;
• versão ativa;
• tempo até expiração;
• renovações;
• falhas de rotação;
• acessos negados.

Testes

Use secrets falsos em ambiente isolado. Teste ausência, permissão negada, rotação, expiração, indisponibilidade, arquivo atualizado e redaction.

Desenvolvimento local

Use conta de desenvolvimento com privilégios mínimos, arquivo ignorado ou ferramenta local integrada ao secret manager. Nunca copie secret de produção.

Erros comuns

• hardcode;
• versionar .env;
• usar secret compartilhado;
• não rotacionar;
• guardar credencial longa no CI;
• registrar process.env;
• usar base64 como criptografia;
• não proteger dumps;
• apagar commit sem revogar;
• acesso amplo ao secret manager.

Fluxo recomendado

Use identidade da workload, secret manager, acesso mínimo e credenciais temporárias. Automatize rotação, redija logs e trate dumps como sensíveis. Combine com Variáveis de Ambiente, Pino, TLS e HTTPS e Graceful Shutdown.

Consulte o Secrets Management Cheat Sheet da OWASP e a documentação oficial do secret manager escolhido.