metis-desk/docs/proxy-tls-y-sesiones.md

Proxy TLS y sesiones del servidor

El entrypoint actual escucha HTTP en loopback. En producción necesita un terminador TLS autorizado delante de Node. Esta guía define el contrato de la aplicación; no acredita una instalación productiva ni incorpora un proxy de despliegue nuevo.

Configuración y confianza

TRUSTED_PROXY_CIDRS contiene direcciones IP o redes CIDR explícitas, separadas por comas, con un máximo de 32 entradas. Admite IPv4 e IPv6; elimina duplicados y espacios exteriores. Rechaza hosts, alias como loopback, números de saltos, entradas vacías, prefijos inválidos y confianza universal (/0, incluida la representación IPv4 mapeada en IPv6).

• Con NODE_ENV=production, la lista es obligatoria. Su ausencia o invalidez bloquea el arranque antes de abrir el puerto.
• En desarrollo puede omitirse: Express mantiene trust proxy=false y permite el recorrido HTTP de desarrollo.
• El administrador debe proporcionar las direcciones reales desde las que Node recibe conexiones del proxy. No copiar direcciones sintéticas de los tests ni confiar en una red más amplia de lo necesario.
• No se utiliza trust proxy=true ni confianza por número de saltos.

El terminador confiable debe sobrescribir X-Forwarded-Proto con un único valor canónico https o http, X-Forwarded-For con la dirección observada del cliente y X-Forwarded-Host con el host autorizado. Debe retirar cabeceras Forwarded aportadas por el cliente y validar el host público según la configuración del destino. La aplicación rechaza con 400 las cabeceras de protocolo repetidas, listas y valores distintos de http/https, antes del middleware de sesión. Una cabecera válida procedente de una dirección no confiable no hace que Express considere segura la conexión.

Restringir por red el acceso al backend. Una IP confiable no es una credencial: procesos locales o fuentes que compartan la IP/NAT del proxy no pueden distinguirse por esta política. Conservar APP_ORIGIN con el origen HTTPS público real para la protección de origen/CSRF. No deducirlo de cabeceras del cliente.

La topología verificada es cliente HTTPS → un terminador TLS → backend HTTP. No se ha aprobado una cadena productiva de varios proxies; antes de utilizarla deben verificarse sus direcciones, recorridos alternativos y sobrescritura de cabeceras. El test de cadena inyectada demuestra que el terminador de prueba la sobrescribe; no certifica una infraestructura de varios saltos.

Cookies y autenticación

Identity utiliza express-session y su almacén SQL. En producción la cookie metis.sid es Secure, HttpOnly, SameSite=Strict, Path=/, sin Domain y con duración de ocho horas. Si el proxy no permite reconocer HTTPS, el middleware no emite una cookie de producción insegura. Comprobar el login en el destino: una lista válida de IPs no demuestra que el proxy esté enviando las cabeceras correctamente.

El logout destruye la sesión SQL y borra la cookie conservando los atributos de seguridad, incluido Secure en producción. El login posterior regenera la sesión. Se mantiene la política existente de renovación; no se ha activado rolling. La emisión posterior conserva Secure. En desarrollo HTTP la cookie mantiene HttpOnly y SameSite=Strict, sin Secure.

Compilación y comprobación aislada

Desde WSL, con Node 24 y el PNPM fijado en package.json:

pnpm --filter @metis/server build
pnpm --filter @metis/server check:build
pnpm --filter @metis/server test:http
pnpm test:server-runtime
pnpm test:global-operating-systems:closure

El build limpia y genera apps/server/dist/index.js en ESM para Node 24, y ejecuta siempre node --check. sharp queda externo: instalar las dependencias runtime del servidor y los binarios nativos adecuados para la plataforma de destino. No distribuir únicamente el fichero JavaScript ni omitir las dependencias nativas opcionales necesarias. El banner conserva el puente CommonJS con un nombre de importación propio.

test:http necesita OpenSSL y puertos loopback. test:server-runtime necesita además Docker/MariaDB: compila, prepara un contenedor único con metis_desk_test, inicia el entrypoint compilado mediante node, verifica TLS con certificado local validado, sesiones SQL, autenticación, CSRF, imágenes y cierre por SIGTERM. Retira el contenedor y los certificados al terminar; no carga .env. Sus evidencias en .artifacts/server-runtime-security/ solo incluyen nombres/atributos de cookies. El proxy local es exclusivamente una fixture.

Para ejecutar el artefacto bajo un supervisor con el entorno previamente validado e inyectado se utiliza node apps/server/dist/index.js. Esto requiere persistencia preparada, secreto de sesión, origen y proxies reales configurados; este documento no autoriza el arranque ni migraciones en producción.

Verificación del destino pendiente

Antes de desplegar: identificar release y plataforma nativa, instalar dependencias runtime, verificar esquema MariaDB y gates efectivos, aprobar IPs/CIDRs y origen, restringir acceso al backend y comprobar HTTPS, login, emisión/borrado de cookie, expiración, CSRF y cierre del proceso mediante el supervisor real. Registrar atributos de cookies sin valores de sesión. El ensayo local no sustituye estas comprobaciones ni la validación visual pendiente del frontend.