Sua Chave de API Vazará. Como Tornar Isso Irrelevante

De acordo com o relatório "State of Secrets Sprawl" da GitGuardian, apenas em 2024, aproximadamente 23,7 milhões de segredos – incluindo chaves de API, tokens e senhas – vazaram para o GitHub público. A vasta maioria desses vazamentos não são resultado de invasões sofisticadas, mas sim de commits comuns, logs e pacotes de cliente. Assim que uma chave recém-gerada é exposta em um repositório público, bots começam a testá-la em menos de um minuto. A conclusão a que chegamos após múltiplos incidentes é clara: lutar para evitar que uma chave vaze é uma guerra perdida. A guerra que se ganha é tornar o vazamento inútil.

Por que as Chaves Vazaram Sempre

Em um projeto médio, uma única chave de API da OpenAI pode residir em até cinco locais simultaneamente: no arquivo .env nos notebooks dos desenvolvedores; nos segredos de CI (e, ocasionalmente, nos logs de CI – printenv em uma etapa de depuração); na configuração de produção; em scripts "só para testar" (como test_gpt.py com a chave diretamente no código); e, mais recentemente, no contexto de um agente de IA que "escreve código sozinho". Cada uma dessas cópias representa um ponto de falha independente. Embora as medidas clássicas de segurança funcionem, cada uma tem suas limitações:

• .env + .gitignore: Protege contra commits acidentais, mas não contra vazamentos em logs, CI, agentes ou scripts "só para testar".
• Scanners (gitleaks, trufflehog): Detectam vazamentos no Git antes do push, mas não cobrem outros canais.
• Gerenciadores de Segredos (Vault, ASM): Protegem o armazenamento e a entrega, mas a chave ainda reside no ambiente de runtime da aplicação.
• Chaves com Escopo de Provedor: Limitamm o raio de impacto, mas nem todos os provedores oferecem essa funcionalidade; o revogamento ainda afeta todos os consumidores da chave.

A característica comum a todos esses métodos é que a chave real, em algum momento, chega ao consumidor. E, consequentemente, vaza junto com ele.

O Esquema: Proxy de Credenciais

A ideia de um proxy de credenciais não é nova – é assim que funcionam, por exemplo, os tokenizadores de pagamento – mas, surpreendentemente, é pouco aplicada a chaves de API. A abordagem consiste em quebrar a ligação direta entre a aplicação e a chave real:

aplicação ──(passagem_vlt)──▶ proxy ──(chave_real)──▶ provedor │ status / IP / limites → log

Nesse esquema:

• Segredo (Secret): É a chave real. É inserida uma única vez, criptografada, e nunca é retornada para fora por nenhuma API.
• Passagem (Pass): É um token virtual vinculado ao segredo. Possui sua própria vinculação a IP, limites de RPM/RPD (requisições por minuto/dia) e um período de vida, além de um log associado. É essa passagem que as aplicações, scripts e agentes recebem.
• Proxy: Verifica a passagem, descriptografa o segredo na memória apenas para uma única requisição, o insere e transmite a resposta de volta.

As consequências dessa abordagem são significativas:

• A zona onde o original pode vazar é reduzida a um único servidor.
• Um vazamento de passagem não é um incidente: se vier de um IP incorreto, resulta em 403 (Forbidden); se exceder os limites, em 429 (Too Many Requests); o revogamento é feito com um clique, sem afetar o segredo original.
• Um bônus adicional: é possível monitorar quem está acessando e com que frequência cada consumidor está sendo utilizado, pois cada um possui sua própria passagem.

Para o código, a transição é simples: basta substituir api.openai.com por <proxy>/p/openai e a chave sk-... por vlt_.... O caminho, corpo, cabeçalhos e o streaming SSE são repassados integralmente.

Como Funciona Internamente (Nossa Implementação)

Implementamos essa arquitetura como um serviço chamado proxykey, utilizando Node.js 22, Fastify 5, PostgreSQL e Redis. Algumas soluções técnicas que podem ser interessantes independentemente do produto incluem:

• Criptografia Envelopada: Para cada segredo, utiliza-se uma chave de criptografia de dados (DEK) própria (AES-256-GCM, AAD = ID do segredo), que é, por sua vez, criptografada por uma chave de criptografia de chaves (KEK) do ambiente. A descriptografia ocorre na memória apenas durante uma requisição; o texto plano não é cacheado nem logado em nenhum lugar, e a DEK é zerada após o uso.
• Tokens Não Armazenados: O banco de dados armazena apenas hashes SHA-256 das passagens. O caminho de acesso rápido valida contra um cache Redis (com TTL de 300 segundos), com fallback para o PostgreSQL.
• Degradação Diferenciada: Se o PostgreSQL cair, o sistema continua operando com o cache (fail-closed para tokens não cacheados). Se o Redis cair, a validação é feita pelo PostgreSQL, mas os limites de taxa podem ser abertos (fail-open), enquanto a validação não é comprometida.
• Proteção SSRF (Server-Side Request Forgery): URLs base customizadas são resolvidas e verificadas contra intervalos de IP privados/de metadados. Sem essa proteção, um proxy com upstream configurado pelo usuário se torna um vetor SSRF pronto.
• Logs de Requisições: O PostgreSQL é particionado por mês, e os metadados são armazenados sem cabeçalhos de autorização ou valores de chave.
• Bots do Telegram: Representam um desafio particular, pois o token reside no caminho da URL. Bibliotecas como aiogram/grammY validam o formato do token antes da primeira requisição. Nosso proxy aceita o formato bot<digits>:vlt_..., ignorando os dígitos e substituindo o token real no servidor, permitindo que a validação das bibliotecas do cliente seja bem-sucedida.

Agentes de IA: O Novo Principal Consumidor de Chaves

Os agentes de IA (como Claude Code, Cursor, etc.) são uma razão fundamental pela qual nos dedicamos a essa solução. Eles frequentemente precisam configurar serviços e bots, o que exige chaves de API. No entanto, tudo o que entra no contexto de um modelo de IA deve ser considerado publicado: o contexto é logado, rastreado e pode ser extraído através de ataques de prompt injection. A solução é fornecer ao agente não um segredo, mas uma ferramenta: um servidor de armazenamento MCP (Managed Credential Proxy). O agente se conecta via URL com um token mcp_... e pode emitir, rotacionar, revogar passagens e ler logs. A operação de "ler a chave real" simplesmente não existe no conjunto de ferramentas disponíveis, sendo uma propriedade do protocolo de acesso, não uma promessa.

Um cenário ideal é o "segredo adiado": um agente configura um bot do Telegram cujo token ainda não existe. O agente cria uma passagem pendente, a configura no arquivo de configuração e fornece um link ao usuário. O usuário insere o token real no painel, a passagem é ativada e o bot entra em funcionamento. O agente conclui seu trabalho sem nunca ter visto o segredo.

Trade-offs Honrosos

• Ponto Crítico: O proxy é um ponto crítico. Se ele cair, todas as chamadas falham. Isso pode ser mitigado com réplicas e cache de validação, mas é um fator a ser considerado.
• Visibilidade do Tráfego: O proxy tem visibilidade do tráfego. A questão não é "se ele vê", mas "o que ele loga". Em nossa implementação, apenas metadados são registrados; a visualização de corpos de requisição é opcional e configurável por passagem. Se o modelo de ameaças não permitir uma terceira parte, essa arquitetura pode ser implementada internamente, pois o padrão é replicável.
• Latência: Um salto adicional e uma verificação de cache adicionam apenas milissegundos, o que é insignificante em comparação com as centenas de milissegundos de latência na geração de LLMs. Para APIs de baixa latência que não sejam LLMs, o impacto deve ser avaliado individualmente.

Disclaimer

Somos os autores do proxykey (proxykey.org). O serviço é gratuito e não requer cartão de crédito. O painel, o proxy e o servidor MCP descritos neste artigo são apresentados de forma honesta, incluindo suas limitações. A arquitetura de proxy de credenciais é replicável sem a necessidade de nossos serviços – se você optar por implementar sua própria solução, lembre-se de incluir a proteção SSRF e a estratégia fail-closed para validações.