Gerenciar segredos e chaves

Use este inventário para decidir quais valores pertencem ao ambiente de runtime, 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 segredos de runtime 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 ou import.meta.env; o Vite pode incorporar valores de build no bundle do servidor.

Visão geral

A chave de criptografia

EMDASH_ENCRYPTION_KEY criptografa 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 operações que precisam de configurações criptografadas do plugin falham em fechamento. Solicitações do site não relacionadas continuam funcionando.

O comando a seguir gera um valor corretamente formatado. Armazene-o no ambiente de runtime ou como segredo Worker se sua implantação usar essa 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 como base64url sem padding. O valor é fornecido pelo operador e não é armazenado no banco de dados. Mantenha-o em um gerenciador de segredos e em um backup de recuperação separado.

Para rotacionar a chave, anteponha um valor novo e retenha 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 ressalvos com a primeira chave. Usa a impressão kid armazenada para selecionar uma chave mais antiga nas leituras. Ressalve cada segredo de plugin antes de remover a chave antiga e verifique essas integrações a partir de uma implantação que contenha apenas a chave nova. O EmDash atualmente não informa quais IDs de chave ainda estão em uso, então mantenha um inventário das credenciais que você ressalva 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 são estáveis entre solicitações, implantações e isolates. A geração é atômica — inicializações a frio concorrentes convergem em um valor.

Segredo de preview

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

• Override: defina EMDASH_PREVIEW_SECRET (alias legado: PREVIEW_SECRET) se precisar do mesmo segredo em vários processos ou quiser fixá-lo por auditoria. O ambiente sempre vence o valor armazenado.
• Rotação: exclua a linha emdash:preview_secret (ou altere a variável de env) e reimplante. Impacto: links de preview emitidos antes param de validar. Nada mais quebra — um segredo novo é gerado (ou lido do env) na próxima solicitação de preview.
• Se perdido: nada é irrecuperável. Links de preview são de curta duração por design.

Veja o guia de preview sobre como as URLs de preview são construídas e verificadas.

Sal de IP

Salga o hash SHA-256 dos endereços IP de comentaristas (ip_hash em comentários) usado para o rate-limit de comentários. Armazenado como emdash:ip_salt. Específico do site, de modo que hashes não são correlacionáveis entre instalações EmDash.

• Override: defina EMDASH_IP_SALT. Para compatibilidade retroativa, EMDASH_AUTH_SECRET / AUTH_SECRET também são consultados — instalações que historicamente derivavam o sal delas mantêm hashes estáveis.
• Rotação: altere a variável de env ou exclua a linha emdash:ip_salt. Impacto: novos envios de comentários fazem hash para valores diferentes, então a contagem do rate-limit reinicia para todos. Comentários existentes e seus hashes armazenados ficam intactos.
• Se perdido: sem perda de dados. Só a continuidade do rate-limit reinicia.

Tokens de sessão e API

• Sessões usam o armazenamento de sessão do Astro (Workers KV no Cloudflare, sistema de arquivos no Node). 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ão (ex.: o namespace KV) para forçar todos a entrar de novo.
• Tokens de API (prefixos ec_pat_, ec_oat_, ec_ort_) são valores aleatórios opacos de 256 bits; apenas o hash SHA-256 é armazenado. O texto plano é mostrado uma vez na criação. Rotacione revogando e recriando no admin.
• Tokens de convite, magic-link e recuperação são de propósito único, armazenados como hashes SHA-256 em auth_tokens, e com limite de tempo (convites 7 dias, magic links 15 minutos).

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

Credenciais de serviço fornecidas pelo usuário

Credenciais para serviços externos são lidas do ambiente e nunca escritas no banco de dados. Rotacione-as no provedor, atualize a variável, reimplante.

No 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. R2 por binding não precisa de variáveis de access key porque o binding concede acesso em runtime. Veja armazenamento de mídia.

Segredos de plugin

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

• Rotação de credencial: rotacione a credencial no provedor e cole o novo valor na página de configurações do plugin. O salvamento escreve um novo envelope criptografado.
• Migração de texto plano: segredos armazenados por uma versão anterior do EmDash permanecem legíveis. Salve cada valor de novo para criptografá-lo.
• Se a chave de criptografia for perdida: restaure o EMDASH_ENCRYPTION_KEY correspondente do backup separado da chave. Se nenhuma cópia existir, substitua cada credencial afetada no provedor e insira as substituições após configurar uma nova chave de criptografia.

Credenciais de CLI

A CLI emdash guarda dois tipos de credenciais, ambas em ~/.config/emdash/auth.json (respeitando XDG_CONFIG_HOME), criadas com permissões apenas do proprietário (0600):

• Tokens de site — emdash login autentica contra sua instância EmDash via fluxo de dispositivo OAuth e armazena o token resultante indexado por URL da instância. emdash logout o remove; por invocação, --token ou EMDASH_TOKEN substituem o token armazenado.
• Tokens de Marketplace — emdash plugin publish autentica no EmDash Marketplace via fluxo de dispositivo do GitHub e armazena o JWT resultante indexado por marketplace:<origin>. Para publicação em CI, defina EMDASH_MARKETPLACE_TOKEN em vez disso — tem prioridade sobre a credencial armazenada.

Perder o arquivo é inofensivo: execute emdash login (ou emdash plugin publish, que reexecuta o fluxo de dispositivo) de novo.

Credenciais de CLI do registro de plugins

A CLI separada emdash-plugin (pacote @emdash-cms/plugin-cli) aponta para o registro AT Protocol experimental. Publicar lá está ligado à sua identidade AT Protocol (seu DID de publisher) — o site em si não guarda credenciais de publicação, e as instalações verificam artefatos contra checksums de registros de release atribuídos a esse DID.

• Autentica via OAuth atproto. Os blobs de sessão/estado OAuth vivem em ~/.emdash/oauth/, e a identidade do publisher (DID, handle, PDS) é armazenada em cache em ~/.emdash/credentials.json; ambos são escritos com permissões apenas do proprietário.
• Em CI, forneça a identidade via EMDASH_PUBLISHER_DID, EMDASH_PUBLISHER_HANDLE e EMDASH_PUBLISHER_PDS; EMDASH_REGISTRY_URL substitui o host do registro. O publish automatizado de CI ainda precisa dos arquivos de sessão OAuth em ~/.emdash/oauth/ no runner — as variáveis de env sozinhas não carregam a sessão OAuth.
• Rotacionar ou revogar o acesso de publicação acontece na sua conta AT Protocol (ex.: senhas de app), não no EmDash. Veja auth Atmosphere.

Referência rápida de rotação