Gerenciamento de segredos e variáveis de ambiente

Em uma aplicação React, as variáveis de ambiente se dividem em duas classes: do lado do servidor (nunca enviadas ao navegador) e do lado do cliente (incorporadas ao pacote JavaScript). Entender a qual classe as suas variáveis pertencem é o primeiro passo para gerenciar segredos, pois as variáveis do lado do cliente se tornam efetivamente públicas assim que o pacote é implantado.

Em projetos Vite, somente as variáveis com o prefixo VITE_ são incluídas no pacote do cliente. VITE_PUBLIC_API_URL=https://api.example.com pode ser acessada no código do navegador por meio de import.meta.env.VITE_PUBLIC_API_URL. Todas as outras variáveis são removidas do pacote durante a compilação e permanecem disponíveis apenas no servidor.

No Next.js, o prefixo NEXT_PUBLIC_ expõe uma variável ao JavaScript do navegador. NEXT_PUBLIC_ANALYTICS_ID=UA-123 é incorporada ao pacote do cliente. Variáveis sem o prefixo (como DATABASE_URL) só podem ser acessadas no código do lado do servidor (componentes do servidor, rotas de API e ações do servidor) e nunca são enviadas ao navegador.

Uma variável sem prefixo ainda pode ficar acessível se for serializada acidentalmente. Por exemplo, se um componente do servidor passar todo o seu objeto de configuração como uma propriedade para um componente do cliente, e essa configuração incluir DATABASE_URL, o segredo aparecerá no HTML enviado ao navegador. O encadeamento cuidadoso de propriedades e a auditoria da serialização evitam isso.

Os itens a seguir nunca devem aparecer no pacote do cliente: strings de conexão e senhas de bancos de dados, chaves secretas de APIs de terceiros (chave secreta do Stripe, chave de API da OpenAI), chaves privadas RSA/EC, segredos de assinatura JWT e tokens internos de autenticação de serviços. Se algum deles for necessário para uma chamada de API, encaminhe essa chamada por um endpoint do servidor.

O padrão de servidor para a interface (BFF) coloca uma camada fina de servidor entre a aplicação React e serviços externos sensíveis. O cliente chama /api/stripe/charge, o servidor BFF anexa a chave secreta do Stripe e chama a API do Stripe, e o BFF retorna apenas os dados de resposta necessários. Os segredos permanecem permanentemente no servidor.

dotenv-vault criptografa o seu arquivo .env e permite compartilhá-lo e implantá-lo com segurança entre ambientes, sem armazenar segredos em texto simples no controle de versões. Entre as alternativas para produção estão o HashiCorp Vault (empresarial), o armazenamento de parâmetros da AWS (SSM) e o gerenciador de segredos da GCP — todos oferecem recuperação de segredos por API durante a execução, em vez de durante a compilação.

As plataformas de CI/CD (GitHub Actions, GitLab CI) oferecem armazenamento criptografado de segredos, acessível como variáveis de ambiente durante as compilações. Armazene os segredos em GitHub Secrets e faça referência a eles nos fluxos de trabalho como ${{ secrets.STRIPE_SECRET_KEY }}. Os segredos são ocultados nos registros e nunca são incluídos no artefato compilado.

Next.js e Vite oferecem suporte a vários arquivos .env: .env (todos os ambientes), .env.local (substituições locais, ignorado pelo Git), .env.development e .env.production. O arquivo local substitui os valores do arquivo compartilhado, permitindo uma configuração específica para cada desenvolvedor sem afetar os outros ambientes.

Depois da compilação, audite o pacote JavaScript em busca de segredos expostos acidentalmente. Execute grep -r "password|secret|api_key" dist/ ou use uma ferramenta específica, como a análise com strings, nos arquivos compilados. Alguns segredos, se forem incluídos acidentalmente, podem ser identificados claramente pelo formato (UUIDs, cadeias em base64 ou prefixos de chave como sk_live_).

Cada ambiente e cada serviço devem ter acesso somente aos segredos de que precisam. O cliente React não precisa de segredo algum — deve receber apenas identificadores públicos. O servidor BFF precisa somente dos segredos necessários para as APIs que chama. Os ambientes de desenvolvimento devem usar chaves de API que não sejam de produção, com permissões limitadas e limites de gastos.

O que acontece com uma variável de ambiente do Next.js que tem o prefixo NEXT_PUBLIC_?

O Vite usa VITE_ e o Next.js usa NEXT_PUBLIC_ para expor variáveis ao pacote do navegador. Todas as outras variáveis ficam disponíveis somente no servidor. Nunca inclua senhas de bancos de dados, chaves secretas de APIs ou segredos de assinatura JWT no código do cliente. Use o padrão BFF para encaminhar chamadas de API sensíveis. Use dotenv-vault, o armazenamento de parâmetros da AWS ou GitHub Secrets para gerenciar segredos em produção. Audite os pacotes compilados em busca de segredos expostos acidentalmente.