Gestão de segredos com Claude Code: do .env à rotação em produção

API keys, URLs de banco de dados, OAuth client secrets e credenciais de deploy em cloud são necessárias em qualquer aplicação real. Também são os valores que ficam no histórico do Git, logs de CI, screenshots, tickets, README e rascunhos de artigos depois de um copiar e colar descuidado. Quando você usa Claude Code para debugar, migrar, fazer deploy ou documentar, a primeira regra precisa ser clara: Claude Code pode ajudar a construir o sistema seguro, mas não deve ver, imprimir, armazenar nem reutilizar segredos reais.

Gestão de segredos não é apenas guardar senhas em um cofre. É separar configuração do código, isolar local, desenvolvimento, staging e produção, aplicar menor privilégio, validar a configuração na inicialização, mascarar logs e ter rotação antes de um incidente forçar pressa. O princípio de Config do The Twelve-Factor App continua sendo a base: configuração vem do ambiente, não do repositório. Na prática, você também precisa de .gitignore, .env.example, um loader validado, CI/CD secrets, um secret store cloud e uma checklist de rotação.

flowchart LR
  Dev["Local .env"] --> Loader["Validated config loader"]
  CI["CI/CD secrets"] --> Deploy["Deployment runtime"]
  Store["AWS / GCP / Azure secret store"] --> Deploy
  Deploy --> App["Application process"]
  App --> Logs["Redacted logs"]

1. Decida o que fica onde

O erro de iniciante é tratar todas as variáveis de ambiente como iguais. Use este teste: se o vazamento de um valor permite que alguém gaste dinheiro, envie emails, leia dados, escreva dados, faça deploy ou se passe por um usuário, trate como segredo. URLs públicas, nomes de feature flags e OAuth client IDs costumam ter menor sensibilidade porque não dão permissão sozinhos.

Caso de uso	Exemplos	Desenvolvimento local	Produção
Email e APIs	SendGrid API key, Stripe secret key, GitHub token	Use keys sandbox ou test em .env	Injete via CI/CD secrets ou secret store
Banco de dados	DATABASE_URL, usuário, senha	Usuário local ou só de dev	Separe leitura/escrita e rotacione senhas
Deploy cloud	Credenciais AWS/GCP/Azure	Evite keys locais de longa duração	Use OIDC ou role só de deploy
OAuth e webhooks	OAUTH_CLIENT_SECRET, webhook signing secret	App local separada	Secrets de produção fora do repo

O ponto central é separação por ambiente. Não reutilize a key de produção do Stripe localmente. Não coloque no CI um token pessoal do GitHub com acesso amplo à organização. Não dê permissão administrativa para uma credencial que só precisa fazer deploy. Isso é menor privilégio: escopo mínimo, no ambiente certo e, se possível, com validade limitada.

2. Commit o formato, nunca o valor

.env é útil localmente, mas não deve entrar no Git. O repositório deve conter .env.example, documentando nomes, formatos, origem e finalidade. Para onboarding, combine com o guia de variáveis de ambiente e reduza perguntas repetidas.

# Local secrets
.env
.env.*
!.env.example
!.env.test.example

# Logs and generated output that may contain tokens
npm-debug.log*
yarn-debug.log*
coverage/
dist/

# .env.example - placeholders only, never real values
NODE_ENV=development
APP_BASE_URL=http://localhost:3000

# Use a local database user, not production credentials.
DATABASE_URL=postgres://app_user:replace-me@localhost:5432/app_dev

# Use test/sandbox keys for local development.
SENDGRID_API_KEY=SG.xxxxxx
STRIPE_SECRET_KEY=sk_test_xxxxxx
GITHUB_TOKEN=ghp_xxxxxx

# OAuth secrets must be separated by environment.
OAUTH_CLIENT_ID=local-client-id
OAUTH_CLIENT_SECRET=replace-me

# Deployment reads these from CI or a cloud secret store.
AWS_REGION=ap-northeast-1
DEPLOY_ROLE_ARN=arn:aws:iam::123456789012:role/app-deploy-dev

Quando chamar Claude Code, escreva o limite: ele pode ler .env.example, manifests de deploy, package scripts e nomes de variáveis; não pode abrir .env, copiar valores reais no chat nem escrever credenciais em documentação. Se a implementação precisar de um valor real, você configura fora do prompt, em local, CI ou secret store, e informa apenas o nome da variável.

3. Valide na inicialização e mascare logs

A aplicação deve falhar rápido quando um segredo obrigatório falta ou está malformado. Ela também deve dificultar que alguém imprima um token em debug. Este loader Node.js usa dotenv e envalid para validar o ambiente e fornece redactConfig para logs, health checks e suporte.

import { config as loadDotenv } from "dotenv";
import { cleanEnv, str, url } from "envalid";

const envFile = process.env.NODE_ENV === "test" ? ".env.test" : ".env";
loadDotenv({ path: envFile });

const secretKeyPattern = /(KEY|TOKEN|SECRET|PASSWORD|DATABASE_URL|PRIVATE)/i;

const env = cleanEnv(process.env, {
  NODE_ENV: str({
    choices: ["development", "test", "staging", "production"],
    default: "development",
  }),
  APP_BASE_URL: url({ default: "http://localhost:3000" }),
  DATABASE_URL: url(),
  SENDGRID_API_KEY: str(),
  STRIPE_SECRET_KEY: str(),
  GITHUB_TOKEN: str(),
  OAUTH_CLIENT_ID: str(),
  OAUTH_CLIENT_SECRET: str(),
  AWS_REGION: str({ default: "ap-northeast-1" }),
  DEPLOY_ROLE_ARN: str(),
});

export function appConfig() {
  return Object.freeze({
    nodeEnv: env.NODE_ENV,
    appBaseUrl: env.APP_BASE_URL,
    databaseUrl: env.DATABASE_URL,
    sendgridApiKey: env.SENDGRID_API_KEY,
    stripeSecretKey: env.STRIPE_SECRET_KEY,
    githubToken: env.GITHUB_TOKEN,
    oauthClientId: env.OAUTH_CLIENT_ID,
    oauthClientSecret: env.OAUTH_CLIENT_SECRET,
    awsRegion: env.AWS_REGION,
    deployRoleArn: env.DEPLOY_ROLE_ARN,
  });
}

export function redactValue(key, value) {
  if (!secretKeyPattern.test(key)) return value;
  if (!value) return "<empty>";
  const text = String(value);
  if (text.length <= 8) return "<redacted>";
  return `${text.slice(0, 4)}...${text.slice(-4)}`;
}

export function redactConfig(config) {
  return Object.fromEntries(
    Object.entries(config).map(([key, value]) => [key, redactValue(key, value)]),
  );
}

if (process.argv[1] === new URL(import.meta.url).pathname) {
  console.log(redactConfig(appConfig()));
}

Um erro comum é adicionar console.log(process.env) durante um incidente e depois colar o log de CI em um ticket ou chat. Se você pedir a Claude Code para resumir logs crus, ele pode recolocar segredos em testes, docs ou artigos. Redija primeiro, peça ajuda depois. Screenshots também precisam ser cortados ou borrados antes de qualquer upload.

4. Dê limites explícitos ao Claude Code

Claude Code quase nunca precisa dos valores reais. Ele precisa de nomes, formatos, erros já mascarados e o objetivo de cada permissão. Cole este bloco no início de tarefas de segurança, deploy ou debug.

You may inspect .env.example, package.json, deployment manifests, and secret names.
Do not open, print, summarize, store, or copy .env, CI/CD secret values, cloud credentials, production dumps, or screenshots containing tokens.
When you need a value, ask me to set it outside chat and confirm only the variable name.
If a secret appears in command output, stop, redact it, and report which file or command exposed it.
Before changing permissions, explain the least-privilege scope and ask for approval.
Do not paste real secrets into prompts, logs, documentation, code comments, tests, tickets, or articles.

Limite comandos também. printenv, cat .env, CLIs cloud que mostram credenciais, logs completos de CI e screenshots devem exigir confirmação. Com .env.example, tipos, erros mascarados e documentação oficial, Claude Code consegue resolver a maioria das mudanças sem valores reais.

5. Use CI/CD secrets e cofres cloud com intenção

Uma separação prática é .env no local, CI/CD secrets nos pipelines e secret store cloud no runtime de produção. Na AWS, use AWS Secrets Manager. No Google Cloud, Secret Manager. No Azure, Key Vault. Em repositórios GitHub, habilite secret scanning para detectar tokens vazados rapidamente.

name: deploy

on:
  workflow_dispatch:

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write
    env:
      NODE_ENV: production
      AWS_REGION: ap-northeast-1
    steps:
      - uses: actions/checkout@v4
      - name: Validate required secret names
        run: test -n "${{ secrets.DEPLOY_ROLE_ARN }}" && test -n "${{ secrets.DATABASE_URL }}"
      - name: Deploy without echoing secrets
        env:
          DATABASE_URL: ${{ secrets.DATABASE_URL }}
          DEPLOY_ROLE_ARN: ${{ secrets.DEPLOY_ROLE_ARN }}
        run: npm run deploy

A armadilha no CI é “vamos dar echo só para ver”. GitHub Actions mascara muitos valores exatos, mas não protege sempre strings derivadas, URLs codificadas, JSON, screenshots ou valores que nunca foram cadastrados como secret. Peça a Claude Code nomes de variáveis e passos de validação, não valores. Se ele sugerir permissões amplas, exija justificativa e reduza o escopo.

6. Rotacione antes de ser obrigado

Rotação deve ser manutenção normal, não apenas resposta a incidente. SendGrid, Stripe, GitHub tokens, senhas de banco, OAuth client secrets, webhook signing secrets e trust policies cloud precisam de owner, ambiente, consumidores, última rotação e próxima revisão.

## Secret rotation checklist
- [ ] Identify owner, environment, consumers, and business impact.
- [ ] Create a new secret with the smallest required scope.
- [ ] Store it in CI/CD secrets or the cloud secret store.
- [ ] Deploy one service or job with the new value.
- [ ] Confirm logs and metrics without printing the secret.
- [ ] Revoke the old secret.
- [ ] Scan Git history, tickets, docs, screenshots, and chat snippets.
- [ ] Record the rotation date and next review date.

Claude Code é útil para transformar isso em issue template, runbook ou plano de migração. Não passe o valor antigo nem o novo. Peça algo como: “Encontre todas as referências a SENDGRID_API_KEY e prepare um plano seguro para trocar pela key v2”.

7. Revise falhas antes de publicar

Pare publicação ou deploy se qualquer item for verdadeiro:

• .env ou .env.production foi commitado e a key exposta não foi revogada.
• Screenshots, logs de CI, relatórios de erro ou exemplos de artigo contêm tokens, DB URLs ou OAuth secrets.
• Uma key cloud tem permissão de administrador quando deploy-only bastaria.
• Credenciais de produção de Stripe, SendGrid, banco ou GitHub são reutilizadas localmente.
• OAuth client secrets ou webhook signing secrets não têm owner nem runbook de rotação.
• Uma IA recebeu valores reais e depois os reutilizou em README, testes, tickets ou rascunhos.

Incidentes de segurança nascem tanto de processo quanto de código. Use a checklist de auditoria de segurança, revise os casos de falha de segurança, conecte com o guia de desenvolvimento de API e, para SendGrid ou email transacional, veja o artigo de automação de email.

8. Introduza no time por etapas

Não comece migrando todos os serviços para secret store em uma semana. Escolha uma aplicação e feche o caminho inteiro: .gitignore, .env.example, loader validado, logs mascarados, CI/CD secrets, secret store de produção e registro de rotação. Depois migre os tipos recorrentes: SendGrid, Stripe, GitHub token, DATABASE_URL, OAuth client secret e credenciais de deploy.

Treinamentos e consultorias da ClaudeCodeLab trabalham com o formato real do seu repositório, mas sem receber segredos reais. Definimos o que Claude Code pode inspecionar, desenhamos limites de CI/CD secrets, ativamos GitHub secret scanning, planejamos AWS/GCP/Azure secret stores e deixamos prompts e runbooks reutilizáveis. Isso ajuda mais do que uma palestra genérica porque o time aplica no code review do dia seguinte.

Em resumo: gestão de segredos não é só esconder strings. É separar valores do código, isolar ambientes, validar na inicialização, mascarar logs, reduzir permissões e praticar rotação. Claude Code pode construir e revisar esse sistema, mas não deve virar mais um lugar onde segredos são copiados.

Ao testar o fluxo no app Node.js de exemplo do Masa, o loader encontrou valores ausentes, redactConfig manteve a URL do banco e as API keys fora dos logs de CI, e o workflow de deploy não precisou mais de permissões amplas de escrita. A surpresa foi um screenshot antigo com uma Stripe test key visível; a key foi reemitida antes da publicação. A lição prática: revisar logs, imagens e rascunhos com a mesma desconfiança usada no código-fonte.