Segredos

O Chinaski mantém seus valores de segredo importantes (o segredo mestre em que roda e as credenciais dos serviços com que fala) fora do texto puro e fora de vista. Esta página explica como funciona o CHINASKI_SECRET, quais configurações são armazenadas criptografadas e o que acontece se você rotacionar o segredo mestre.

A variável de ambiente CHINASKI_SECRET

Este é o único segredo mestre de uma instância Chinaski, e ele precisa existir antes de o servidor iniciar: sem ele, o CMS se recusa a rodar.

Ele protege duas coisas:

1. Sessões de admin. O cookie de sessão do seu login é assinado criptograficamente com esta chave. Os usuários nunca a veem nem a manipulam.
2. Armazenamento criptografado. A chave de criptografia que protege as credenciais armazenadas no banco de dados é derivada dele. Essas credenciais nunca são gravadas em disco em texto puro.

Gerá-lo é um passo único que o instalador faz por você no deployment padrão: o valor é gravado em um arquivo de env com permissões restritas (0600, dentro de um diretório 0700) que somente o usuário de serviço do CMS pode ler. No fluxo de instalação offline, a receita é:

export CHINASKI_SECRET=$(openssl rand -hex 32)    # do this once; save the value

Nunca o commite em repositórios, não o compartilhe entre instâncias e guarde uma cópia em um lugar seguro: você não consegue recuperá-lo a partir do sistema em execução.

O que é armazenado criptografado

Várias configurações da área de admin são valores sensíveis para a segurança e ficam criptografadas no banco de dados. As configurações de segredo registradas são:

• Senha SMTP
• Segredo de webhook
• Chave secreta S3 de deploy
• Chave secreta do Turnstile
• Chave secreta de backup (Spaces)
• Segredo de cliente OAuth

A criptografia é autenticada (AES-256-GCM com um nonce aleatório por valor e uma tag de integridade). Os valores criptografados são armazenados com um prefixo de versão, para que o formato possa evoluir. Se uma linha foi gravada em texto puro por uma versão mais antiga, o sistema a tolera até a próxima vez que a configuração for salva, quando ela é atualizada para a forma criptografada.

Segredos e a API

A API de leitura nunca retorna configurações de segredo: elas são removidas da resposta mesmo para chaves de API autenticadas. Escritas via API criptografam um novo valor da mesma forma que a UI de admin. Integrações de terceiros não conseguem ler suas credenciais armazenadas pela API.

Rotacionando o segredo mestre

Alterar o CHINASKI_SECRET é uma operação séria, com consequências conhecidas:

• Todos são desconectados. Os cookies de sessão existentes foram assinados com a chave antiga e se tornam inválidos no momento em que a nova chave entra em vigor: todos os admins e editores precisam entrar novamente. Não há sobreposição nem chave de fallback.
• As credenciais armazenadas deixam de funcionar. As credenciais criptografadas do banco de dados (SMTP, webhook, Turnstile, OAuth, S3, backup) foram criptografadas com uma chave derivada do segredo antigo. Com o novo segredo, elas não podem ser descriptografadas.
• Corrigir significa salvar de novo. Após a rotação, abra as configurações relevantes na área de admin e salve novamente cada valor de credencial, para que seja recriptografado com a nova chave. Essa mesma ação atualiza quaisquer valores legados em texto puro que você ainda possa ter.

Não há um comando embutido para automatizar a migração dos segredos armazenados durante uma rotação na versão atual, então planeje a rotação: escolha uma janela de manutenção, rotacione o valor do env, reinicie a instância, entre novamente e salve de novo cada configuração afetada. Depois, teste o e-mail, os webhooks e qualquer outra integração configurada.

Práticas de higiene que o sistema impõe

• Os segredos vivem apenas no ambiente ou em valores criptografados do banco de dados; a aplicação mantém uma cópia em texto puro na memória somente onde for necessário para falar com um serviço.
• O arquivo do banco de dados e o arquivo de env são legíveis apenas pelo dono; o diretório de backup é exclusivo do dono. Instalações padrão os colocam dentro de diretórios que apenas o usuário de serviço chinaski pode acessar.
• A ferramenta de setup por script prefere ler a senha de admin de uma variável de ambiente em vez de uma flag de linha de comando, para que a senha não apareça na lista de processos durante o setup.
• Para hosts isolados/airgapped, definir CHINASKI_AIRGAP=1 desativa toda chamada de saída que o CMS poderia fazer: nada no seu deployment precisa sair da máquina para o core rodar.