Gestão de Segredos no Node.js

A Gestão de Segredos no Node.js protege senhas de banco, chaves de API, tokens, certificados e credenciais usadas pela aplicação. Esses valores não devem ficar em código-fonte, arquivos versionados, imagens Docker ou logs.

Um segredo seguro precisa ser armazenado em um serviço apropriado, entregue apenas ao processo autorizado, rotacionado, auditado e removido da memória quando possível. Variáveis de ambiente ajudam na configuração, mas não resolvem sozinhas versionamento, rotação, controle de acesso e vazamento em diagnósticos.

Neste guia, você aprenderá a identificar segredos, usar gerenciadores, carregar valores no Node.js, aplicar privilégio mínimo, rotacionar sem indisponibilidade, proteger Docker e Kubernetes, redigir logs e responder a incidentes.

O que é um segredo?

Segredo é qualquer valor que concede acesso ou permite realizar uma operação sensível:

• senha de banco;
• chave de API;
• private key;
• token OAuth;
• pepper de senha;
• credencial SMTP;
• certificado cliente;
• chave de criptografia;
• cookie signing key.

A OWASP Secrets Management Cheat Sheet descreve práticas essenciais. A metodologia Twelve-Factor App recomenda separar configuração do código.

O que não é segredo?

Nome do serviço, porta, ambiente e flags públicas podem ser configuração, mas não precisam ser protegidos como credenciais. Classificar tudo como segredo aumenta complexidade e dificulta auditoria.

Nunca versionar

DATABASE_URL=postgres://user:password@host/db
API_KEY=valor-secreto

Arquivos como .env não devem ser enviados ao Git. Adicione ao .gitignore, mas lembre que isso não apaga segredos já commitados.

Segredo commitado

Remover o arquivo do commit atual não basta. O valor pode permanecer no histórico, clones, caches e pipelines. Revogue imediatamente, gere outro valor e depois limpe o histórico quando necessário.

Variáveis de ambiente

const databaseUrl = process.env.DATABASE_URL;

if (!databaseUrl) {
  throw new Error('DATABASE_URL não configurada');
}

Variáveis de ambiente são uma interface de entrega, não um cofre. Elas podem aparecer em dumps, ferramentas de diagnóstico e configurações da plataforma.

Validação da configuração

const config = {
  databaseUrl: requireSecret('DATABASE_URL'),
  apiKey: requireSecret('PARTNER_API_KEY'),
  sessionSecret: requireSecret('SESSION_SECRET')
};

Falhe no startup quando um segredo obrigatório estiver ausente. Não use valores fracos como fallback em produção.

Gerenciador de segredos

Serviços como AWS Secrets Manager, Google Secret Manager, Azure Key Vault e HashiCorp Vault fornecem controle de acesso, versionamento, auditoria e rotação.

A aplicação autentica com uma identidade de workload e solicita apenas os segredos necessários.

Identidade de workload

Evite armazenar uma chave estática apenas para acessar o cofre. Em cloud, prefira roles, service accounts, managed identities ou mecanismos equivalentes.

Privilégio mínimo

Um serviço de relatórios deve ler somente a credencial de leitura. Ele não precisa acessar a chave de pagamentos ou o certificado administrativo.

Carregamento no startup

const secrets = await secretProvider.load([
  'database/url',
  'sessions/signing-key'
]);

await startServer({ secrets });

Essa estratégia simplifica o runtime, mas uma rotação pode exigir reinício.

Carregamento sob demanda

Buscar o segredo em cada requisição adiciona latência e dependência externa. Use cache curto, versão e renovação controlada.

Cache de segredos

class SecretCache {
  constructor(provider, ttlMs) {
    this.provider = provider;
    this.ttlMs = ttlMs;
  }
}

O cache deve ficar apenas em memória e nunca ser serializado em disco ou logs.

Rotação

Uma rotação segura costuma aceitar duas versões temporariamente:

1. Criar o segredo novo.
2. Permitir antigo e novo no serviço de destino.
3. Atualizar aplicações.
4. Confirmar uso da nova versão.
5. Revogar a antiga.
6. Auditar a operação.

Rotação de senha do banco

Alguns bancos permitem dois usuários ou credenciais sobrepostas. Outra opção é usar credenciais dinâmicas com vida curta emitidas pelo cofre.

Credenciais dinâmicas

Um cofre pode criar usuário temporário com TTL de minutos. Se a credencial vaza, o período de uso é limitado.

Pool de conexões

Rotacionar a senha não encerra imediatamente conexões existentes. O pool precisa criar conexões novas com a credencial atual e drenar as antigas.

Consulte Pool PostgreSQL no Node.js.

Chaves de assinatura

Para JWT ou cookies, use identificador de chave e mantenha uma janela de verificação:

{
  "kid": "signing-2026-08",
  "alg": "EdDSA"
}

Assine com a chave nova e valide tokens antigos com a anterior até a expiração.

Chaves de criptografia

Use envelope encryption: uma chave de dados cifra o conteúdo, e uma chave protegida por KMS cifra a chave de dados. Isso facilita rotação sem recifrar tudo imediatamente.

Pepper de senha

O pepper deve ficar fora do banco de hashes. Veja Argon2 no Node.js.

API keys

Armazene apenas hash quando o servidor precisa comparar, não recuperar. Consulte API Keys no Node.js.

Docker

Não use:

ENV DATABASE_PASSWORD=segredo

O valor pode ficar em camadas da imagem. Entregue no runtime por Secret, arquivo temporário ou integração com o provedor.

Build arguments

ARG também pode aparecer no histórico de build. Use secret mounts suportados pelo builder para acessar registries e dependências privadas.

Kubernetes Secrets

Secrets do Kubernetes não são automaticamente criptografados em todos os ambientes. Configure encryption at rest, RBAC, acesso por namespace e integração com um cofre externo quando necessário.

Arquivo montado

const password = await fs.readFile(
  '/run/secrets/database_password',
  'utf8'
);

Arquivos montados permitem atualização sem alterar o ambiente do processo. A aplicação pode observar versão ou recarregar de forma segura.

Permissões do arquivo

Restrinja owner e mode. Um segredo disponível para todos os usuários do container ou host perde valor.

CI/CD

Pipelines precisam acessar apenas segredos do ambiente e da etapa. Pull requests não confiáveis não devem receber credenciais de produção.

Mascaramento em logs

O masking do provedor ajuda, mas não é garantia. Valores transformados, codificados ou concatenados podem escapar. Evite imprimir a configuração.

Logs da aplicação

logger.info({
  databaseHost: config.database.host,
  databasePassword: '[REDACTED]'
}, 'Configuração carregada');

Configure redaction para Authorization, cookies, chaves e campos conhecidos. Consulte Logs com Pino no Node.js.

Erros

Não inclua connection strings completas em mensagens. Bibliotecas podem anexar opções e credenciais ao erro.

Tracing

Não coloque segredo em atributos de span, baggage ou headers propagados. Traces atravessam múltiplos serviços e fornecedores.

Dumps e snapshots

Heap snapshots e core dumps podem conter segredos em memória. Restrinja acesso, retenção e uso em produção.

Minimizar tempo em memória

JavaScript não oferece garantia simples de apagar strings imutáveis. Evite cópias, conversões e logs. Quando uma API aceita Buffer, sobrescreva-o depois do uso, sabendo que cópias podem existir.

SSRF e metadata

Um ataque SSRF pode tentar acessar metadata da cloud e obter credenciais. Restrinja rede, use tokens modernos do provedor e identidades com privilégio mínimo.

Auditoria

Registre leitura administrativa, criação, alteração, rotação, falha de acesso e revogação. Não registre o valor.

Veja Logs de Auditoria no Node.js.

Métricas

Monitore falhas de leitura, versões antigas em uso, segredos próximos da expiração, rotação incompleta e chamadas ao cofre.

Alertas

Acesso fora do horário, por identidade inesperada, volume anormal ou tentativa de ler segredo não autorizado deve gerar alerta.

Inventário

Mantenha uma lista com owner, finalidade, sistema, ambiente, data de rotação, TTL e plano de revogação.

Segredos órfãos

Credenciais de serviços removidos, ex-funcionários e ambientes antigos devem ser revogadas. Inventários desatualizados geram acessos invisíveis.

Detecção em repositórios

Use scanners no pre-commit, CI e plataforma Git. Padrões próprios, como prefixos de API key, ajudam a detectar vazamentos.

Plano de incidente

1. Revogar o segredo.
2. Emitir nova versão.
3. Identificar onde foi usado.
4. Analisar logs e auditoria.
5. Rotacionar credenciais relacionadas.
6. Corrigir a origem do vazamento.
7. Documentar o incidente.

Testes

Teste startup sem segredo, acesso negado ao cofre, rotação, cache expirado e revogação.

Teste de logs

Injete um valor conhecido, cause erros e pesquise esse valor em logs, traces e respostas. O segredo não pode aparecer.

Teste de rotação

Mantenha conexões ativas, altere a credencial e confirme que novas conexões usam a versão atual sem interromper requisições.

Teste de privilégio

Uma identidade do serviço A não deve ler segredos do serviço B.

Erros comuns

• Segredo no Git: permanece no histórico.
• Variável de ambiente tratada como cofre: falta controle e rotação.
• Credencial compartilhada: não há atribuição nem revogação individual.
• Secret no Dockerfile: fica em camadas.
• Logar configuração: credenciais aparecem em observabilidade.
• Sem sobreposição na rotação: aplicações param.
• Permissão ampla: um serviço comprometido acessa todos os segredos.

Boas práticas

• Separe código e segredo.
• Use identidade de workload.
• Aplique privilégio mínimo.
• Versione e rotacione.
• Evite valores estáticos longos.
• Não coloque segredos em imagens.
• Redija logs e traces.
• Audite acessos.
• Mantenha inventário.
• Teste vazamentos e revogação.

Conclusão

A Gestão de Segredos no Node.js reduz o risco de credenciais espalhadas em código, pipelines, containers e logs. Um cofre central, identidade de workload e privilégio mínimo permitem entregar apenas o valor necessário ao processo correto.

Rotação, auditoria, redaction e resposta a incidentes completam a proteção. Quando cada segredo possui owner, validade e plano de revogação, a aplicação deixa de depender de credenciais permanentes que ninguém sabe onde estão.