HTTPS local para desarrollo: una CA privada, almacenes de confianza y la excepción de localhost

Objetivo

Servir la aplicación en local por HTTPS con un certificado que los navegadores y las herramientas de línea de comandos acepten, de modo que las cookies Secure, las reglas de contenido mixto y los URI de redirección de OAuth se comporten como en producción, sin advertencias de certificado y sin certificados públicos para nombres que no te pertenecen.

Requisitos previos

Saber cuándo no es necesario: la especificación Secure Contexts considera que un origen es potencialmente confiable cuando su host es una dirección de 127.0.0.0/8 o ::1/128 y, en los agentes de usuario que resuelven los nombres localhost a loopback, como exige la especificación, cuando es localhost o termina en .localhost; por tanto, http://localhost sin cifrar ya recibe las API de contexto seguro en esos navegadores. El HTTPS local compensa cuando pruebas comportamientos específicos de TLS, usas un nombre de host de desarrollo que no es de loopback o ejecutas varios servicios bajo un mismo nombre comodín. La recomendación de Let's Encrypt para localhost es generar tu propio certificado, autofirmado o firmado por una raíz local, y añadirlo como confiable en el almacén de confianza del sistema operativo.

Pasos

1. Crea una CA privada una sola vez por equipo de desarrollo. Según su README, mkcert -install crea una CA local y la instala en el almacén de confianza del sistema y en el de Firefox, si está presente. No subas ni compartas nunca la clave de la CA; el README advierte de que rootCA-key.pem otorga poder total para interceptar las peticiones seguras de tu equipo.
2. Emite certificados de hoja solo para nombres de desarrollo, por ejemplo mkcert app.localhost "*.dev.example.test" 127.0.0.1; nunca para nombres de host de producción.
3. Configura el servidor local o el proxy inverso con el certificado y la clave; el README indica que mkcert no configura los servidores por ti. Mantén esos archivos fuera del control de versiones y de las imágenes de contenedor.
4. Haz que los clientes que no son navegadores confíen en la CA. El README documenta NODE_EXTRA_CA_CERTS para Node.js, que debe apuntar al archivo raíz de la carpeta que muestra mkcert -CAROOT; otros entornos de ejecución leen el almacén del sistema o necesitan su propia variable. Registra la variable de cada herramienta en el script de configuración.
5. En un segundo equipo o en un contenedor de desarrollo, repite el paso 1; cada equipo tiene su propia CA, así que los certificados de hoja se regeneran, no se copian.
6. Añade una comprobación al script de configuración: una petición al endpoint HTTPS local debe tener éxito sin desactivar la verificación.

Resultado esperado

El navegador muestra un certificado válido para el origen de desarrollo, las cookies Secure funcionan y nadie se acostumbra a ignorar las advertencias de certificado.

Límites y base de verificación

Una CA privada en el almacén del sistema es una decisión de seguridad que afecta a ese equipo; mantén la clave legible solo por su usuario. Los dispositivos móviles requieren importar aparte el archivo raíz, como describe el README de mkcert, que además incluye entre sus almacenes de raíces Java (cuando JAVA_HOME está definido) y el almacén NSS que usa Firefox, seleccionables con TRUST_STORES. Procedimiento elaborado a partir de los documentos citados; no se afirma ninguna medición.