0002 — Acceso a la documentación interna
Estado: aceptada · Fecha: 2026-09-09
Contexto
La documentación técnica describe la arquitectura interna, los nombres de las variables de entorno, las particularidades de la infraestructura y las decisiones de seguridad. No contiene secretos, pero es un mapa útil para quien quiera atacar el sistema, y no tiene ningún valor publicarla.
La aplicación ya tiene autenticación con Supabase, así que la pregunta obvia es por qué no reutilizarla.
Decisión
El sitio interno se sirve como HTML estático desde nginx, sin ninguna línea de código de autenticación, y se protege con Cloudflare Access delante.
Configuración, toda en el panel de Cloudflare y nada en el repositorio:
- Registros DNS de
devdocs.xenpia.com(prod) ydevdocstest.xenpia.com(test), con el proxy activado, cada uno al servidor correspondiente. - Zero Trust → Access → Applications → Self-hosted, con ambos hostnames.
- Política de permitir con la regla de correos que terminan en el dominio de la empresa, o la lista explícita del equipo. Login por código de un solo uso al correo, o Google.
- En nginx (en ambos servidores), el bloque de
devdocs*restringido a los rangos de IP de Cloudflare, para que nadie alcance el origen por IP directa saltándose Access.
Por qué no el login de Supabase
Porque un build de Docusaurus es HTML plano servido por nginx. Comprobar la sesión requiere que alguien ejecute código en cada petición, antes de responder, para leer la cookie y validar el token. Ahí no hay nadie ejecutando nada.
Hacerlo desde el navegador no protege: para cuando ese script corre, el HTML ya salió del servidor. Y el índice del buscador de Docusaurus es un único JSON con el texto completo de todas las páginas, descargable directamente.
La alternativa real sería poner el sitio interno detrás de una ruta autenticada del frontend de Next.js, lo que significa acoplar el ciclo de vida de la documentación al de la aplicación y perder la ventaja de que sea estático. No compensa.
Consecuencias
A favor. Cero código de autenticación que mantener. Access filtra antes de que la petición llegue al servidor. Gratis hasta 50 usuarios. Dar y quitar acceso es cambiar una lista en un panel.
En contra. Dependencia de Cloudflare para acceder a la documentación: si Access cae, el equipo se queda sin ella. Como mitigación, el contenido siempre se puede leer en el repositorio, que es donde vive.
Riesgo. Si alguien apunta un DNS al origen sin proxy, o si se olvida la restricción por IP en nginx, el sitio queda expuesto. Por eso la restricción de IP es parte de la decisión y no un extra opcional.
Regla que se mantiene
Aunque el sitio esté protegido, aquí no van secretos. Ni contraseñas, ni tokens, ni llaves. Solo nombres de variables y dónde obtener su valor. Una capa de acceso no es excusa para relajar eso.