guias
Segurança

Variáveis de Ambiente Seguras

Como gerenciar secrets sem vazar chaves de API no código.

O erro mais comum de vibecoders: colocar chaves de API direto no código. Este guia mostra como fazer certo.

O problema

// ❌ NUNCA faça isso
const supabase = createClient(
  "https://xxxx.supabase.co",
  "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
);

Se esse código for para o GitHub, qualquer pessoa pode ver suas chaves. Bots vasculham repositórios públicos constantemente procurando secrets expostos.

A solução: variáveis de ambiente

// ✅ Correto
const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
);

Os valores ficam fora do código — definidos no ambiente de execução.

Como configurar

1. Criar arquivo .env.local

Para desenvolvimento local:

# .env.local (NUNCA commitar este arquivo)
DATABASE_URL=postgres://user:pass@localhost:5432/mydb
STRIPE_SECRET_KEY=sk_test_...
NEXT_PUBLIC_SUPABASE_URL=https://xxxx.supabase.co

2. Adicionar ao .gitignore

# .gitignore
.env
.env.local
.env.production
.env*.local

Verificação: Rode git status e confirme que seus arquivos .env NÃO aparecem na lista.

3. Criar .env.example

Crie um arquivo de exemplo (sem valores reais) para documentar quais variáveis o projeto precisa:

# .env.example (este sim pode ir para o Git)
DATABASE_URL=
STRIPE_SECRET_KEY=
NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_ANON_KEY=

4. Definir na Veloz

veloz env set DATABASE_URL=postgres://user:pass@host:5432/db
veloz env set STRIPE_SECRET_KEY=sk_live_...
veloz env set NEXT_PUBLIC_SUPABASE_URL=https://xxxx.supabase.co

Público vs Secreto

Variáveis públicas (client-side)

Prefixos que expõem a variável no navegador:

Framework Prefixo
Next.js NEXT_PUBLIC_
Vite VITE_
Create React App REACT_APP_

Essas variáveis são embutidas no JavaScript do build — qualquer pessoa pode vê-las no DevTools.

Use apenas para:

  • URLs públicas de API
  • Chaves públicas (anon keys do Supabase, publishable keys do Stripe)
  • IDs de tracking (Google Analytics)

Variáveis secretas (server-side)

Variáveis SEM prefixo público só existem no servidor:

# Secretas — só o servidor vê
DATABASE_URL=postgres://...
STRIPE_SECRET_KEY=sk_live_...
JWT_SECRET=meu-segredo-ultra-secreto
API_KEY_INTERNA=...
 
# Públicas — o browser também vê
NEXT_PUBLIC_STRIPE_KEY=pk_live_...
NEXT_PUBLIC_API_URL=https://api.meuapp.com

Regra: Se a chave dá acesso a dados ou permite ações, ela é secreta. Nunca use prefixo público.

O que NUNCA colocar no código

  • Senhas de banco de dados
  • Secret keys de API (Stripe, OpenAI, etc.)
  • Tokens de autenticação
  • Chaves de criptografia
  • Credenciais de email (SMTP)
  • Webhooks secrets

Já vazou? O que fazer

Se você acidentalmente commitou um secret:

1. Revogar imediatamente

Vá ao dashboard do serviço (Supabase, Stripe, etc.) e gere novas chaves. As antigas devem ser invalidadas.

2. Remover do histórico do Git

Apenas deletar o arquivo não basta — o secret continua no histórico. Use:

# Instalar BFG Repo Cleaner
brew install bfg
 
# Remover arquivo do histórico inteiro
bfg --delete-files .env
 
# Limpar
git reflog expire --expire=now --all
git gc --prune=now --aggressive
git push --force

3. Atualizar na Veloz

veloz env set CHAVE_COMPROMETIDA=novo-valor-seguro
veloz deploy

Rotação de secrets

Boas práticas:

  • Troque secrets periodicamente (a cada 90 dias)
  • Use secrets diferentes para desenvolvimento e produção
  • Nunca compartilhe secrets via Slack, Discord ou email — use um gerenciador de senhas

Checklist

  • Nenhum secret hardcoded no código
  • .env.local no .gitignore
  • .env.example commitado (sem valores reais)
  • Variáveis de produção definidas na Veloz (veloz env set)
  • Secrets separados entre dev e produção
  • Chaves públicas usam o prefixo correto do framework

Próximos passos