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 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 ou 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 atualmente não criptografa segredos de plugins nem outros dados armazenados. Se a variável estiver definida, o EmDash verifica seu formato durante a inicialização. Um valor malformado produz uma mensagem de log para o operador, mas o site continua processando requisições.

O comando a seguir gera um valor corretamente formatado. Armazene-o no ambiente de execução ou como Worker secret se sua implantação usa essa variável.

npx emdash secrets generate
# emdash_enc_v1_<43 caracteres base64url>

# 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. Perdê-lo não tem impacto na recuperação de dados porque nenhum dado armazenado depende dele.

Segredos do site gerados

Dois segredos são gerados automaticamente no primeiro uso e persistidos na tabela options, então são estáveis entre requisições, implantações e isolates. A geração é atômica — cold starts concorrentes convergem em um valor.

Preview secret

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 entre múltiplos processos ou quiser fixá-lo por razões de auditoria. O ambiente sempre tem prioridade sobre o valor armazenado.
• Rotação: exclua a linha emdash:preview_secret (ou mude a variável de env) e reimplante. Impacto: links de preview emitidos anteriormente param de validar. Nada mais quebra — um novo segredo é gerado (ou lido do env) na próxima requisição de preview.
• Se perdido: nada é irrecuperável. Links de preview são de curta duração por design.

Veja o guia de preview para como URLs de preview são construídos e verificados.

IP salt

Adiciona salt ao hash SHA-256 dos endereços IP dos comentaristas (ip_hash em comentários) usado para rate limiting de comentários. Armazenado como emdash:ip_salt. Específico do site, então 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 derivaram o salt deles mantêm hashes estáveis.
• Rotação: mude a variável de env ou exclua a linha emdash:ip_salt. Impacto: novas submissões de comentários geram hashes diferentes, então a contagem de rate-limit recomeça para todos. Comentários existentes e seus hashes armazenados não são afetados.
• Se perdido: sem perda de dados. Apenas a continuidade do rate-limiting é resetada.

Session e API tokens

• Sessions usam o session store do Astro (Workers KV no Cloudflare, filesystem no Node). O cookie carrega um ID de sessão opaco; não há segredo de assinatura para gerenciar. Faça logout para encerrar uma sessão, ou limpe o session store (ex. o namespace KV) para forçar todos a fazerem login novamente.
• API tokens (prefixos ec_pat_, ec_oat_, ec_ort_) são valores opacos aleatórios de 256 bits; apenas seu hash SHA-256 é armazenado. O texto puro é mostrado uma vez na criação. Rotacione revogando e recriando no admin.
• Tokens de convite, magic-link e recuperação são de uso único, armazenados como hashes SHA-256 em auth_tokens, e limitados no tempo (convites 7 dias, magic links 15 minutos).

Não há nada para fazer backup ou rotacionar proativamente: um vazamento de banco de dados expõe apenas hashes, e cada token pode ser revogado ou reemitido pelo 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 via binding não precisa de variáveis de access-key porque o binding concede acesso em runtime. Veja storage de mídia.

Segredos de plugins

Configurações que um plugin declara com type: "secret" (chaves de API para provedores de email, CAPTCHAs de formulários, etc.) são inseridas na UI do admin e armazenadas no banco de dados — na tabela options em plugin:<id>:settings:<key>, ou no storage chave-valor do plugin. Se um segredo armazenado é devolvido à UI do admin depende do plugin; plugins bem implementados retornam apenas um flag “valor está definido” em vez do segredo em si (o plugin de formulários incluído faz isso).

• Rotação: rotacione a chave no provedor e cole o novo valor na página de configurações do plugin. Tem efeito imediato.
• Se perdido: reinsira o valor no admin. Nada mais depende dele.

Credenciais CLI

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

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

Perder o arquivo é inofensivo: execute emdash login (ou emdash plugin publish, que re-executa o fluxo de dispositivo) novamente.

Credenciais CLI do plugin registry

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

• Autentica via atproto OAuth. 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 somente do proprietário.
• Em CI, forneça a identidade via EMDASH_PUBLISHER_DID, EMDASH_PUBLISHER_HANDLE e EMDASH_PUBLISHER_PDS; EMDASH_REGISTRY_URL sobrescreve o host do registro. O publish automatizado do 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 Autenticação Atmosphere.

Referência rápida de rotação