Gestão de secrets para times pequenos que vão crescer

Todo projeto começa com um arquivo .env. Isso não é erro. Um .env no começo é a quantidade certa de cerimônia para um time de dois. O erro é o dia em que ninguém percebe que o time agora tem oito pessoas, o .env foi colado em quatro conversas de chat e a senha do banco de produção é a mesma da primeira semana.

Eu audito sistemas como profissão, e secrets são onde encontro as falhas que ninguém mais encontra. Não porque os times sejam descuidados. Porque a passagem de 'pequeno' para 'não tão pequeno' aconteceu sem ninguém decidir que tinha acontecido.

Os três estágios

Estágio um é o arquivo .env, no gitignore, com um .env.example commitado listando cada chave com valor vazio. O arquivo de exemplo é a parte importante. Ele é o contrato que diz quais secrets existem. Se um secret novo é adicionado sem mexer no exemplo, o setup do próximo dev quebra de um jeito confuso em vez de um jeito claro.

Estágio dois é o secret store da plataforma. Toda plataforma de hospedagem séria tem um. Os secrets são definidos por dashboard ou CLI, injetados como variáveis de ambiente em runtime e nunca vivem num arquivo no notebook de ninguém. A transição aqui é barata: o código não muda nada, só muda de onde o process.env tira os valores. A maioria dos times deveria estar aqui quando tiver o primeiro cliente em produção.

Estágio três é um gerenciador de secrets dedicado, com versionamento, log de auditoria, rotação automática e identidade por serviço. É para onde você vai quando tem vários serviços, vários ambientes e perguntas de compliance. O código muda um pouco: os secrets são buscados na subida ou sob demanda em vez de lidos do ambiente. O modelo mental não muda se você fez os estágios um e dois direito.

As regras que sobrevivem a todo estágio

O motivo de esses três estágios não exigirem reescrita é um punhado de regras que valem desde o primeiro dia. Secrets são lidos em exatamente um módulo, validados na subida e expostos ao resto do código como um objeto de configuração tipado. Nada mais encosta em process.env. Num projeto TypeScript isso é um arquivo só com um schema, e a aplicação se recusa a subir se um secret obrigatório está faltando ou malformado. Esse hábito sozinho transforma uma falha silenciosa às 3 da manhã numa falha barulhenta de deploy.

A segunda regra é que secrets são por ambiente e por propósito. Desenvolvimento, staging e produção nunca compartilham credencial. A API key de envio de email não é a API key de leitura de analytics, mesmo que o provedor deixe usar uma só. Quando uma vazar, e uma vai vazar, o raio de explosão é do tamanho daquele propósito.

A terceira regra é que todo secret tem um caminho de rotação conhecido antes de ser criado. Não um cronograma, um caminho. Qual serviço usa, onde está definido, o que quebra durante a rotação e em que ordem atualizar as coisas. Escreva isso num comentário ao lado da chave no arquivo de exemplo. Quando o vazamento acontecer, você não vai estar pensando com clareza, e o comentário vai pensar por você.

As coisas que eu sempre encontro

• Secrets commitados no repositório em algum ponto do histórico, ainda válidos, nunca rotacionados depois de removidos da árvore atual.
• Um único usuário de banco compartilhado com privilégio total usado pela aplicação, pelas migrations, pelo job de analytics e pelo notebook de um dev.
• Tokens de longa duração para APIs de terceiros com escopo amplo, criados num protótipo e ainda em uso.
• Secrets impressos no log por um debug que serializa o objeto de configuração inteiro.
• Pipelines de CI que fazem echo de variáveis de ambiente, com a saída retida por meses.

Nenhum desses exige um atacante sofisticado. Exigem um log vazado, um ex-contratado, um repositório público que era privado ano passado.

O que fazer esta semana

Varra o histórico git de cada repositório atrás de secrets. Rotacione tudo que encontrar, independente de acreditar que vazou. Mova os secrets de produção para o store da plataforma e apague de todos os notebooks. Divida o usuário do banco em pelo menos um papel de aplicação e um de migration. Adicione a validação na subida. São alguns dias de trabalho, e te levam do estágio um para um estágio dois estável sem reescrita. O estágio três pode esperar até o time precisar, e quando precisar, a forma do código já vai estar certa.