Como proteger chaves e credenciais numa aplicação feita com IA
Para proteger chaves e credenciais numa aplicação feita com IA, identifica os acessos necessários, guarda os segredos fora do código público e confirma que o browser nunca os recebe. Define permissões limitadas, separa testes de produção e verifica o comportamento da aplicação com exemplos controlados antes de a publicares.
Pedir à IA para criar uma aplicação pode levar rapidamente a um formulário que funciona, a uma lista com dados e a um botão que executa uma ação. A ligação ao serviço externo fica menos visível. É precisamente nessa ligação que deves perceber quem está a usar a credencial e o que consegue fazer com ela.
Vamos trabalhar com um exemplo fictício: uma aplicação interna consulta um catálogo de materiais reservado à equipa. O serviço do catálogo exige uma chave privada para ler os registos. O objetivo é mostrar os materiais permitidos a cada utilizador, sem entregar essa chave a quem abre a página.
O exemplo serve para organizar uma revisão com o teu assistente de programação. Não envolve uma conta real nem demonstra que uma aplicação concreta está segura. Vais sair com perguntas, casos de verificação e um registo que permite distinguir o que foi confirmado do que ainda falta testar.
Começa por inventariar os acessos da aplicação
Antes de criares variáveis ou copiares valores, identifica cada serviço ligado ao projeto e a operação que a aplicação precisa de executar. Regista o nome da credencial, a finalidade, o ambiente e o responsável. Mantém o valor secreto fora deste inventário, para poderes partilhar a documentação sem partilhar o acesso.
No catálogo fictício, escreve que a aplicação precisa de consultar materiais. Se não vai editar preços, apagar registos ou gerir utilizadores, essas operações não fazem parte do pedido. Esta frase ajuda a rever uma proposta da IA que peça uma chave administrativa apenas porque é mais fácil de configurar.
Acrescenta o local onde a credencial é configurada e os componentes que a consomem. O nome CATALOGO_API_KEY pode aparecer na documentação; o valor correspondente fica no mecanismo apropriado de segredos. Saber onde procurar uma configuração é diferente de publicar aquilo que permite autenticar o pedido.
| Elemento | Registo do exemplo | O que confirmar |
|---|---|---|
| Serviço | Catálogo interno fictício | Origem autorizada dos dados |
| Operação | Consultar materiais | Sem edição ou eliminação |
| Credencial | CATALOGO_API_KEY | Valor nunca incluído na documentação |
| Ambiente | Testes ou produção | Valores e permissões adequados |
| Responsável | Pessoa que gere a integração | Capacidade de substituir e revogar |
Nem tudo o que contém a palavra chave é necessariamente secreto. Alguns fornecedores disponibilizam identificadores ou chaves publicáveis, concebidos para uso no browser e dependentes de outros controlos. Confirma a classificação na documentação do serviço; não uses o nome do campo como prova de que pode ser divulgado.
Separa o browser do servidor no desenho da integração
Desenha o percurso de um pedido desde a página até ao serviço externo e de volta ao utilizador. No nosso exemplo, o servidor guarda a chave privada, verifica o acesso do utilizador e consulta o catálogo. A resposta enviada ao browser contém apenas os dados que esse utilizador pode receber.
A pessoa abre a aplicação, autentica-se e pede a lista de materiais. O browser contacta uma rota da própria aplicação. Essa rota valida a sessão, aplica as permissões e só depois faz a consulta externa. A chave de serviço participa nesta última ligação, sem ser devolvida na resposta da página.
Há duas perguntas diferentes para fazer ao agente: onde fica a chave e quem pode acionar a operação? Esconder a chave num servidor não resolve uma rota que permite a qualquer visitante executar consultas privadas. Da mesma forma, ter um ecrã de login não demonstra que todas as rotas verificam autorização.
Imagina duas contas de teste, A e B, com acesso a conjuntos distintos de materiais. A aplicação deve decidir no servidor que registos pertencem a cada conta. Um identificador enviado pelo browser é informação recebida; não passa a ser uma permissão só porque veio de um botão da interface.
Pede ao assistente que te indique os ficheiros responsáveis por cada etapa. Esse mapa permite rever alterações de código sugeridas pela IA com um objetivo concreto: confirmar a separação entre apresentação, controlo de acesso e comunicação com o serviço.
Usa variáveis de ambiente com a classificação correta
As variáveis de ambiente permitem fornecer configuração à aplicação sem escrever os valores diretamente no código. Precisam, ainda assim, de ser usadas no local certo. Uma variável pode acabar numa resposta, num ficheiro entregue ao browser ou num registo de execução se a implementação a copiar para esses destinos.
No Next.js, o prefixo NEXT_PUBLIC_ identifica variáveis destinadas ao browser e os seus valores podem ser incorporados no JavaScript durante a construção. Uma chave privada do catálogo não deve receber esse prefixo. A documentação de variáveis de ambiente do Next.js explica esta distinção e o efeito do momento de construção.
O nome sem prefixo público também não substitui a revisão do código. Se uma função no servidor devolver o segredo dentro de um objeto, a resposta continua a expô-lo. Pede uma verificação do percurso completo do valor, incluindo tratamento de erros, páginas de diagnóstico e dados serializados para componentes.
Na Vercel, a documentação distingue atualmente variáveis Config e Secret. As Secret ficam sem leitura do valor depois de guardadas, enquanto as Config se destinam a configuração consultável por membros com acesso. Consulta a classificação de variáveis da Vercel para aplicar a opção adequada ao projeto e ao ambiente.
Esta escolha protege a gestão da configuração, mas a aplicação continua responsável pelo uso que faz do valor. No exercício, a informação a documentar é simples: variável privada, consumida pela rota do servidor, sem retorno ao cliente. Evita transformar a captura do painel de configuração numa prova suficiente de toda a integração.
Dá ao agente contexto sem colar a credencial
Explica ao assistente o nome da variável, a operação permitida e a forma como o serviço autentica pedidos, usando valores fictícios nos exemplos. Para preparar o código, o agente precisa do contrato da integração e das restrições do projeto. Não precisa de receber o segredo numa mensagem partilhada para compreender a tarefa.
Podes começar com um pedido deste género, adaptado ao teu projeto:
Prepara a consulta do catálogo no servidor. A variável CATALOGO_API_KEY contém uma chave privada e será configurada no ambiente autorizado. Usa um marcador fictício nos exemplos. Confirma autenticação, autorização por utilizador e dados devolvidos. Não imprimas valores de credenciais. Identifica os ficheiros alterados e os casos que faltam testar.
Acrescenta a fase autorizada. Se estás a preparar o código localmente, diz que as ligações reais e a publicação ficam para uma etapa definida. Se já autorizaste a integração e o deployment, mantém essa decisão no contexto e pede que o relatório distinga implementação, teste e publicação.
Trabalhar num editor instalado no computador não significa que todo o processamento fique nesse computador. É preciso conhecer as ferramentas, as permissões e o destino dos dados. Por isso, protege também anexos, capturas, mensagens de erro e ficheiros que o agente possa ler, em vez de te preocupares apenas com o texto do prompt.
Guarda estas regras nas instruções do projeto que o agente consegue seguir. Uma instrução útil descreve comportamento observável: não mostrar valores, usar exemplos sintéticos e apresentar resultados de verificação. Uma frase vaga como “aplica segurança máxima” deixa as decisões importantes por explicar.
Confirma o que entra no repositório e na publicação
Antes de guardar uma versão ou publicar, revê os ficheiros incluídos e os dados produzidos pela aplicação. Código, documentação, exemplos e artefactos podem seguir percursos diferentes. Verifica cada destino relevante para evitar que uma configuração local, um relatório ou uma cópia de diagnóstico seja enviada juntamente com a funcionalidade.
Um ficheiro de exemplo deve ensinar quais são as variáveis necessárias sem conter valores reais. Podes documentar CATALOGO_API_KEY=VALOR_FICTICIO como indicação de configuração. A pessoa que recupera o projeto percebe o requisito e obtém o acesso através do processo autorizado, sem procurar uma chave antiga no código.
Revê também os ficheiros que já estão a ser acompanhados pelo Git. Acrescentar uma regra ao ficheiro de exclusões não apaga automaticamente conteúdo que entrou em versões anteriores. O guia do GitHub sobre remoção de dados sensíveis distingue a resposta à exposição da reescrita do histórico e explica os efeitos desta última.
Na publicação, identifica a revisão de código, o ambiente e o endereço que estás a testar. Uma configuração correta no computador não demonstra que o deployment recebeu a configuração certa. Uma página que abre também não demonstra que a rota privada está protegida ou que a chave ficou ausente dos ficheiros públicos.
O procedimento de publicar uma aplicação na Vercel e confirmar que funciona ajuda a ligar estas peças. Acrescenta ao registo da entrega a confirmação da integração, sem copiar o valor da variável para o relatório.
Prepara testes que mostrem o limite de acesso
Usa contas e dados de teste para verificar o caminho autorizado e as situações que devem ser recusadas. Define o resultado esperado antes de executar cada caso. Guarda a versão testada, o comportamento observado e as limitações, sem transformar os registos em novas cópias das credenciais que estás a proteger.
No catálogo fictício, o primeiro caso é a conta A consultar os materiais de A. O segundo é a mesma conta tentar obter um material reservado a B. O resultado esperado muda: a aplicação deve permitir o primeiro acesso e recusar o segundo, mesmo que o pedido seja construído fora dos botões habituais.
Experimenta também a ausência de sessão, uma sessão inválida e um identificador inexistente. O objetivo é verificar o comportamento das rotas na tua aplicação autorizada. Não é necessário usar dados de clientes para provar que a decisão de acesso acontece no servidor e que as falhas têm uma resposta compreensível.
Para procurar exposição, usa um marcador sintético num ambiente isolado e inspeciona os ficheiros enviados ao browser, as respostas de rede e os erros. Se o marcador aparece num destino público, tens um problema concreto para corrigir. A ausência num conjunto de testes é evidência limitada à cobertura realizada, não uma garantia universal.
Nos registos, pede o nome da operação, o estado e um identificador de diagnóstico adequado. Evita descarregar objetos completos de configuração ou pedidos autenticados. A orientação da OWASP para gestão de segredos inclui controlo de acesso, ciclo de vida e cuidados de auditoria sem exposição dos valores.
Prepara a substituição antes de precisares dela
Documenta como substituir uma credencial, onde atualizar a configuração e quem confirma o funcionamento depois da alteração. Distingue uma rotação planeada de uma exposição suspeita. A primeira permite preparar a transição; a segunda exige conter o acesso indevido com prioridade, seguindo o procedimento do fornecedor e a situação concreta.
Numa rotação planeada do catálogo, identifica primeiro todos os consumidores da chave. Podem existir a aplicação, um processo de importação e uma tarefa de manutenção. Se atualizares apenas a aplicação, os restantes continuam dependentes do valor anterior e a revogação pode interromper trabalho que não tinhas incluído no inventário.
Quando o fornecedor permite a transição entre credenciais, prepara a nova configuração, testa o consumidor autorizado e confirma a desativação da antiga. Se houver suspeita de exposição, não adies a contenção apenas para manter uma transição confortável. A prioridade e os passos dependem do incidente, não de uma receita cega.
Guarda no registo a data, os componentes afetados, o responsável e os resultados. Não guardes as duas chaves para “facilitar a próxima vez”. Um registo de manutenção deve permitir compreender o que mudou e recuperar o serviço pelo processo autorizado, sem se tornar outro local de distribuição de acessos.
A revisão fica utilizável quando consegues responder a quatro perguntas: que operação está autorizada, onde é usada a credencial, como verificaste o limite e como a substituis? Se alguma resposta depende de procurar um segredo numa conversa antiga, tens uma melhoria concreta para fazer antes de aumentar o projeto.
Como podes aprender a construir estas integrações no Laboratório
No Laboratório da IA, podes aprender a transformar uma ideia numa aplicação com contexto, integrações e critérios de revisão. As aulas semanais e os Zooms de acompanhamento semanais permitem trabalhar dúvidas concretas sobre o teu projeto, perceber o percurso dos dados e organizar os passos necessários para publicar com mais controlo.
Traz o mapa da integração e os casos de teste, sem valores privados. É material suficiente para discutir a arquitetura, identificar lacunas e melhorar o pedido que fazes ao agente. O objetivo é compreender as decisões que estás a delegar e conseguir verificar o resultado.
Referências e âmbito da revisão
As referências seguintes sustentam as distinções técnicas verificadas em 14 de outubro de 2026. O catálogo, as contas de teste e os pedidos apresentados são exemplos editoriais fictícios. Este artigo propõe um processo de revisão; não apresenta uma auditoria executada a uma aplicação real nem certifica a segurança de qualquer serviço.
Aprende a construir isto no Lab.
Trabalha o processo com aulas, materiais e acompanhamento. Leva o que estás a construir e esclarece as dúvidas da tua implementação.
- Mapear credenciais, operações e ambientes do projeto.
- Verificar limites de acesso e exposição com dados fictícios.
- Aprender a construir integrações nas aulas e Zooms semanais do Laboratório.
Aulas semanais para aprender e aplicar. Zooms de acompanhamento semanais para esclarecer dúvidas. Replay e materiais para retomar o trabalho ao teu ritmo.
Entrar no Laboratório da IA