Segredos: chaves que o código do site precisa

#O que é um segredo

Um segredo é um valor com um nome. O valor costuma ser uma chave de API: a senha que um programa usa para falar com outro, como a chave que um serviço de e-mail marketing entrega a você. O nome é como o código do seu site a pede, por exemplo MAILING_LIST_KEY.

A parte do seu site que lê segredos roda no servidor, por trás de suas rotas (endereços sob /api/ que executam código em vez de mostrar uma página). O valor fica lá. Ele não está nas páginas do site, não é enviado aos navegadores dos visitantes e não está no código que você pode baixar.

Depois de salvo, um valor nunca mais pode ser exibido, por ninguém, nem mesmo por você. O estúdio guarda apenas o nome, quem salvou e quando. Mantenha sua própria cópia em um lugar seguro, como um gerenciador de senhas.

Você só precisa de segredos quando o código do seu site trabalha com algo que exige uma chave. Um site institucional com formulário de contato não precisa de nenhum.

#Antes de começar

• Publique o site uma vez. Os segredos ficam guardados apenas no site publicado, nunca no estúdio. Até a primeira publicação, a página mostra Publish the site first e nada pode ser adicionado.
• Confira o seu papel. Editors, Admins e Owners adicionam, alteram e excluem segredos. Viewers veem os nomes e quando cada um foi salvo.
• Escolha um nome. Letras, dígitos e sublinhados, começando com uma letra, com até 128 caracteres. O estilo comum é maiúsculas com sublinhados. Nomes que começam com BRIKS_ são reservados ao estúdio.
• Atenção aos limites. Um valor pode ter até 5 KB, o bastante para qualquer chave ou certificado. Um projeto comporta até 100 segredos, incluindo os do próprio estúdio.

#Adicionar um segredo

#Importar vários de um arquivo .env

Um arquivo .env é um arquivo de texto simples com linhas NOME=valor, uma para cada segredo. Desenvolvedores costumam ter um. Se você tiver um, pode trazer todas as linhas de uma vez.

#Alterar ou remover um segredo

As mudanças chegam ao site no ar na hora: você vê The live site has it now ou, em caso de exclusão, The live site no longer has it. Com muitos segredos, a caixa Search secrets encontra um pelo nome. A tabela mostra o Name e o Last saved de cada um, com quem o salvou.

Algumas linhas trazem a etiqueta Managed. O estúdio define essas linhas para os próprios serviços, como os e-mails do site, e elas não podem ser alteradas nem excluídas aqui.

#Como a construção usa um segredo

O código do seu site lê um segredo pelo nome toda vez que roda, então uma construção nunca precisa do valor. Quando você pede ao estúdio para conectar seu site a outro serviço, como uma lista de e-mails ou um modelo de IA, o código lê a chave desse serviço por um nome claro, como MAILING_LIST_KEY. Você adiciona o valor aqui, com esse nome.

#Quando pedem uma chave antes de construir

• Uma mudança em um site publicado. Quando o seu pedido conecta outro serviço, o status mostra Checking which keys this needs por um instante. Se o site ainda não tem valor para uma chave, o estúdio pergunta antes de criar. O cartão na conversa tem um campo para cada chave, até 3 para uma mudança. Cole o valor e clique em Save and build: ele vai direto para os Secrets do site, nunca para a conversa, e a mudança começa. Clique em Add it later para criar sem ele.
• Uma mensagem enviada enquanto ele espera entra na alteração. Chaves que você já salvou ou escolheu adicionar depois nunca são pedidas de novo: se a sua nova mensagem conecta outro serviço, só a chave dele é pedida, depois que o primeiro cartão for concluído.
• Um site novo. Os Secrets precisam de um site publicado, então uma primeira construção ainda não consegue receber uma chave. Entre as perguntas antes de construir, ele pode perguntar se deve construir a conexão agora e adicionar a chave quando o site estiver no ar, ou deixar essa parte de fora por enquanto.
• No Telegram, o cartão tem um botão para cada chave que abre Secrets no estúdio, e Build para continuar. Uma chave nunca é enviada por chat.

#Exigida pelo site

Depois de cada publicação, o Briks lê quais nomes de segredos o código do próprio site pede. Os que ainda não têm valor aparecem primeiro nesta página, marcados com Needed by the site. Pressione Add value em um deles e o formulário abre com o nome já preenchido. Enquanto um nome não tiver valor, a parte do site que o usa não funciona.

A resposta a uma criação ou mudança também os cita, por exemplo: O site lê MAILING_LIST_KEY, que ainda não tem valor: adicione em Project Settings → Secrets. Cada nome tem seu próprio botão, como Add MAILING_LIST_KEY, que abre esta página com o nome já preenchido. A mesma frase vem na notificação e no Telegram, quando ele avisa que uma criação terminou.

#Uma chave colada em uma mensagem

O Briks reconhece os formatos usuais de chaves e tokens de serviços. Uma chave colada no chat do estúdio, na descrição de um novo projeto, no briefing de um projeto, em uma mensagem para um agente ou nas instruções dele, no Ask AI do Visual Editor ou em uma conversa com o bot é removida antes de a mensagem ser guardada ou lida, e substituída por [key removed: add it in Settings → Secrets]. O estúdio avisa na hora: A key was removed from your message so it isn't stored. Add it in Project Settings → Secrets. A resposta traz um botão Open Secrets que leva a esta página. Na conversa de um agente que trabalha em todos os projetos, Open Secrets lista seus projetos para você escolher aquele a que a chave pertence. Algo que um agente deva lembrar é recusado se contiver uma chave.

Antes de um site ser publicado, o Briks lê o próprio código em busca de chaves escritas em arquivos: valores que parecem chaves pelo formato e valores atribuídos a qualquer item com nome de chave, token ou senha. Se encontrar algum, a compilação volta para retirar o valor e ler o segredo pelo nome.

#Regras de segurança que o Briks aplica

• Os valores vão direto para o lado do servidor do site publicado, criptografados. O estúdio nunca os guarda, nunca os mostra de novo e nunca os grava em seus logs.
• Os valores nunca aparecem nas páginas do site, nos navegadores dos visitantes nem no código que você baixa.
• Só Editors, Admins e Owners podem adicionar, alterar ou excluir segredos.
• Nomes que começam com BRIKS_ pertencem ao estúdio, e os segredos gerenciados não podem ser alterados.
• Um projeto pode fazer até 60 alterações nos segredos por minuto. Acima disso você vê: Isso é muita alteração de uma vez. Espere um minuto e tente de novo.

#Quando um segredo some

Os segredos pertencem ao endereço do site. Se você mudar o endereço (veja Endereço do seu site), seus segredos ficam com o antigo. A mensagem do estúdio os lista e pede que você os insira de novo em Settings, Secrets, e cada linha mostra Not on the site · enter again. Escolha Edit value em cada um e cole o valor dele.

Se o código do site pedir um segredo que não existe, essa parte do site responde: Part of this site is not set up yet. Confira se o nome é idêntico, com as mesmas maiúsculas, e se a linha não diz Not on the site.

#Exemplo prático: substituir uma chave vazada

Só então apagaram a chave antiga no serviço de envio de e-mails, então o site nunca ficou um instante sem uma chave funcionando. Nada precisou ser reconstruído, porque o código pede a chave pelo nome.