Gerenciar segredos e chaves

Use este inventário para decidir quais valores pertencem ao ambiente de execução, quais são gerados no banco de dados e quais são armazenados por plugins. Cada seção indica como a rotação afeta um site em execução.

No Node.js, coloque os segredos de execução no gerenciador de segredos da plataforma de hospedagem para que entrem em process.env quando o processo iniciar. Para um Worker, use wrangler secret put. Não coloque valores secretos em astro.config.mjs, wrangler.jsonc nem import.meta.env; o Vite pode incorporar valores de tempo de build no bundle do servidor.

Visão geral

A chave de criptografia

EMDASH_ENCRYPTION_KEY criptografa as configurações de plugin declaradas com type: "secret". O EmDash usa AES-GCM com o ID do plugin e a chave da configuração como dados autenticados. Um valor malformado produz uma mensagem de inicialização voltada ao operador, e as operações que precisam de configurações de plugin criptografadas falham de forma fechada. Requisições do site não relacionadas continuam funcionando.

O comando a seguir gera um valor no formato correto. Armazene-o no ambiente de execução ou como segredo do Worker se o seu deploy usar esta variável.

npx emdash secrets generate
# emdash_enc_v1_<43 base64url chars>

# Cloudflare:
wrangler secret put EMDASH_ENCRYPTION_KEY

O formato é emdash_enc_v1_ seguido de 32 bytes aleatórios em base64url sem preenchimento. O valor é fornecido pelo operador e não é armazenado no banco de dados. Guarde-o em um gerenciador de segredos e em um backup de recuperação separado.

Para rotacionar a chave, acrescente um novo valor no início e mantenha o valor antigo após uma vírgula:

EMDASH_ENCRYPTION_KEY=emdash_enc_v1_<new-key>,emdash_enc_v1_<old-key>

O EmDash criptografa valores novos e salvos novamente com a primeira chave. Ele usa a impressão digital kid armazenada para selecionar uma chave mais antiga nas leituras. Salve novamente cada segredo de plugin antes de remover a chave antiga e, em seguida, verifique essas integrações a partir de um deploy que contenha apenas a nova chave. Atualmente o EmDash não informa quais IDs de chave continuam em uso, então mantenha um inventário das credenciais que você salva novamente e não remova uma chave antiga até que cada integração tenha passado nessa verificação.

Segredos de site gerados

Dois segredos são gerados automaticamente no primeiro uso e persistidos na tabela options, de modo que ficam estáveis entre requisições, deploys e isolates. A geração é atômica — cold starts concorrentes convergem para um único valor.

Segredo de preview

Assina as URLs de preview (HMAC). Armazenado como emdash:preview_secret; 32 bytes aleatórios, base64url.

• Substituição: defina EMDASH_PREVIEW_SECRET (alias legado: PREVIEW_SECRET) se precisar do mesmo segredo em vários processos ou quiser fixá-lo por motivos de auditoria. O ambiente sempre prevalece sobre o valor armazenado.
• Rotação: exclua a linha emdash:preview_secret (ou altere a variável de ambiente) e faça um novo deploy. Impacto: os links de preview emitidos anteriormente deixam de ser validados. Nada mais quebra — um novo segredo é gerado (ou lido do ambiente) na próxima requisição de preview.
• Se for perdido: nada é irrecuperável. Os links de preview têm vida curta por design.

Consulte o guia de preview para saber como as URLs de preview são construídas e verificadas.

Sal de IP

Aplica sal ao hash SHA-256 dos endereços IP de quem comenta (ip_hash nos comentários), usado para o limite de taxa de comentários. Armazenado como emdash:ip_salt. É específico do site, portanto os hashes não podem ser correlacionados entre instalações do EmDash.

• Substituição: defina EMDASH_IP_SALT. Por compatibilidade com versões anteriores, EMDASH_AUTH_SECRET / AUTH_SECRET também são consultados — instalações que historicamente derivavam o sal dessas variáveis mantêm hashes estáveis.
• Rotação: altere a variável de ambiente ou exclua a linha emdash:ip_salt e, em seguida, faça um novo deploy. Impacto: os novos envios de comentários geram hashes diferentes, então a contagem do limite de taxa recomeça para todos. Os comentários existentes e seus hashes armazenados permanecem intactos.
• Se for perdido: sem perda de dados. Apenas a continuidade do limite de taxa é reiniciada.

Tokens de sessão e API

• As sessões usam o armazenamento de sessões do Astro (Workers KV na Cloudflare, sistema de arquivos no Node). Adaptadores que não configuram um armazenamento, como o Vercel, precisam de um driver de sessão em astro.config.mjs; sem ele, o login falha com um erro explicando que um driver de sessão é necessário. O cookie carrega um ID de sessão opaco; não há segredo de assinatura para gerenciar. Saia para encerrar uma sessão ou limpe o armazenamento de sessões (por exemplo, o namespace do KV) para forçar todos a entrar novamente.
• Os tokens de API (prefixos ec_pat_, ec_oat_, ec_ort_) são valores aleatórios opacos de 256 bits; somente o hash SHA-256 deles é armazenado. O texto simples é exibido uma vez, na criação. Rotacione revogando e recriando o token no admin.
• Os tokens de convite, de link mágico e de recuperação têm finalidade única, são armazenados como hashes SHA-256 em auth_tokens e têm tempo limitado (convites 7 dias, links mágicos 15 minutos).

Não há nada para fazer backup ou rotacionar de forma proativa: um vazamento do banco de dados expõe apenas hashes, e todo token pode ser revogado ou reemitido pelo admin.

Credenciais de serviço fornecidas pelo usuário

As credenciais de serviços externos são lidas do ambiente e nunca são gravadas no banco de dados. Rotacione-as no provedor, atualize a variável e faça um novo deploy.

Na Cloudflare, defina-as com wrangler secret put; para desenvolvimento local, coloque-as em .env. O Wrangler lê .dev.vars ou .env, não ambos, e .dev.vars tem precedência quando presente. O R2 por meio de um binding não precisa de variáveis de chave de acesso porque o binding concede acesso em tempo de execução. Consulte armazenamento de mídia.

No Node, o EmDash lê a chave secreta do Turnstile do ambiente de processo do servidor quando uma requisição chega, e nem astro dev nem o servidor compilado carregam .env nele. Defina a chave no ambiente do seu host, exporte-a no shell que executa astro dev ou inicie o servidor compilado com node --env-file=.env ./dist/server/entry.mjs.

Segredos de plugin

As configurações que um plugin declara com type: "secret" (chaves de API de provedores de e-mail, CAPTCHAs de formulários etc.) são inseridas na interface do admin e criptografadas na tabela options em plugin:<id>:settings:<key>. O admin recebe apenas a informação de se um segredo está definido, mesmo quando a chave de criptografia correspondente não está disponível, de modo que um administrador possa substituir uma credencial ilegível. O código do plugin lê o texto simples por meio de ctx.settings dentro do seu ambiente de execução isolado. Valores armazenados fora de um esquema de configurações declarado, incluindo entradas arbitrárias de KV e de estado do plugin, não usam esse caminho de criptografia.

• Rotação de credenciais: rotacione a credencial no provedor e cole o novo valor na página de configurações do plugin. Ao salvar, um novo envelope criptografado é gravado.
• Migração de texto simples: segredos armazenados por uma versão anterior do EmDash continuam legíveis. Salve cada valor novamente para criptografá-lo.
• Se a chave de criptografia for perdida: restaure a EMDASH_ENCRYPTION_KEY correspondente a partir do backup de chaves separado. Se não existir nenhuma cópia, substitua cada credencial afetada no respectivo provedor e insira os substitutos depois de configurar uma nova chave de criptografia.

Credenciais de CLI

A CLI emdash armazena os tokens do site em ~/.config/emdash/auth.json (respeitando XDG_CONFIG_HOME) com permissões somente para o proprietário (0600). emdash login autentica na sua instância do EmDash por meio de um device flow OAuth e armazena o token indexado pela URL da instância. emdash logout o remove; a cada invocação, --token ou EMDASH_TOKEN substitui o token armazenado.

Perder o arquivo é inofensivo: execute emdash login novamente.

Credenciais de CLI do registro de plugins

A CLI separada emdash-plugin (pacote @emdash-cms/plugin-cli) tem como alvo o registro AT Protocol experimental. A publicação lá está vinculada à sua identidade AT Protocol (seu DID de publicador) — o site em si não guarda credenciais de publicação, e as instalações verificam os artefatos com base nos checksums de registros de release atribuídos a esse DID.

• Ela se autentica por meio de OAuth atproto. Os blobs de sessão/estado do OAuth ficam em ~/.emdash/oauth/, e a identidade do publicador (DID, handle, PDS) é armazenada em cache em ~/.emdash/credentials.json; ambos são gravados com permissões somente para o proprietário.
• Em CI, forneça a identidade por meio de EMDASH_PUBLISHER_DID, EMDASH_PUBLISHER_HANDLE e EMDASH_PUBLISHER_PDS; EMDASH_REGISTRY_URL substitui o host do registro. Um publish automatizado a partir de CI ainda precisa dos arquivos de sessão OAuth em ~/.emdash/oauth/ no runner — as variáveis de ambiente sozinhas não carregam a sessão OAuth.
• A rotação ou revogação do acesso de publicação acontece na sua conta AT Protocol (por exemplo, senhas de aplicativo), não no EmDash. Consulte Atmosphere auth.

Referência rápida de rotação