HTTPS local para desenvolvimento: uma CA privada, repositórios de confiança e a exceção do localhost

Objetivo

Servir a aplicação localmente via HTTPS, com um certificado aceito por navegadores e ferramentas de linha de comando, para que cookies Secure, regras de conteúdo misto e URIs de redirecionamento OAuth se comportem como em produção, sem avisos de certificado e sem certificados públicos para nomes que você não possui.

Pré-requisitos

Saiba quando isso é desnecessário: a especificação Secure Contexts trata uma origem como potencialmente confiável quando o host é um endereço em 127.0.0.0/8 ou ::1/128 e, para user agents que resolvem nomes localhost para loopback, como a especificação exige, quando o host é localhost ou termina em .localhost; assim, http://localhost simples já recebe as APIs de contexto seguro nesses navegadores. O HTTPS local compensa o esforço quando você testa comportamento específico de TLS, usa um nome de host de desenvolvimento fora do loopback ou executa vários serviços sob um único nome com curinga. A orientação do Let's Encrypt para localhost é gerar o seu próprio certificado, autoassinado ou assinado por uma raiz local, e confiar nele no repositório de confiança do sistema operacional.

Passos

1. Crie uma CA privada uma única vez por máquina de desenvolvedor. mkcert -install cria uma CA local e, segundo o README, a instala no repositório de confiança do sistema e no do Firefox, quando presente. Nunca faça commit nem compartilhe a chave da CA; o README avisa que rootCA-key.pem dá poder total para interceptar requisições seguras da sua máquina.
2. Emita certificados finais apenas para nomes de desenvolvimento, por exemplo mkcert app.localhost "*.dev.example.test" 127.0.0.1; nunca para nomes de host de produção.
3. Configure o servidor local ou o proxy reverso com o certificado e a chave; o README afirma que o mkcert não configura servidores por você. Mantenha os arquivos fora do controle de versão e das imagens de contêiner.
4. Faça os clientes que não são navegadores confiarem na CA. O README documenta NODE_EXTRA_CA_CERTS para Node.js, apontando para o arquivo da raiz na pasta exibida por mkcert -CAROOT; outros runtimes leem o repositório do sistema ou precisam de uma variável própria. Registre a variável de cada ferramenta no script de configuração.
5. Em uma segunda máquina ou em um contêiner de desenvolvimento, repita o passo 1; cada máquina tem a sua própria CA, então os certificados finais são gerados de novo, não copiados.
6. Adicione uma verificação ao script de configuração: uma requisição ao endpoint HTTPS local deve ter sucesso sem desativar a verificação.

Resultado esperado

O navegador mostra um certificado válido para a origem de desenvolvimento, os cookies Secure funcionam e ninguém se acostuma a ignorar avisos de certificado.

Limites e base de verificação

Uma CA privada no repositório de confiança do sistema é uma decisão de segurança para aquela máquina; mantenha a chave legível apenas pelo seu usuário. Dispositivos móveis exigem uma importação separada do arquivo da raiz, descrita no README do mkcert, que também lista Java (quando JAVA_HOME está definido) e o repositório NSS usado pelo Firefox entre os seus repositórios de raiz, selecionáveis com TRUST_STORES. Procedimento sintetizado a partir dos documentos citados; nenhuma medição é alegada.