Protección con contraseña

A veces quieres que tu documentación esté en línea, sea descubrible, versionada en Git, pero no visible para todo el mundo. Runbooks, guías de prelanzamiento, documentos solo para socios, funciones de acceso anticipado. La protección con contraseña te proporciona una frase de contraseña compartida que controla el acceso a todo tu sitio o a un conjunto específico de páginas, sin mover nada de tu repositorio existente.

Las capturas de pantalla muestran la interfaz en inglés.

¿Qué modo debo elegir?

Jamdesk tiene dos modos de protección con contraseña. Elige uno según lo que sea público y lo que no.

Ambos modos comparten la misma tarjeta en el dashboard, la misma pantalla de acceso y los mismos controles de rotación y revocación. Puedes cambiar entre ellos en cualquier momento editando docs.json y haciendo push.

Proteger todo el sitio

{
  "$schema": "https://jamdesk.com/docs.json",
  "name": "Acme Docs",
  "theme": "jam",
  "auth": {
    "password": {
      "enabled": true,
      "hint": "Ask #docs-access on Slack"
    }
  }
}

git add docs.json
git commit -m "Turn on password protection"
git push

# Should respond with HTTP/1.1 401 and the unlock HTML
curl -I https://acme.jamdesk.app/

# Submit the password. On success, sets the jd_auth_<slug> cookie.
curl -i -X POST https://acme.jamdesk.app/jd/unlock \
  -d "password=your-passphrase&from=/"

Excepciones públicas

El modo para todo el sitio tiene una válvula de escape: puedes mantener páginas específicas públicas aunque el resto del sitio esté protegido. Así es como publicas una página de marketing o un formulario de registro junto a documentación privada.

Tienes tres formas de marcar una página como pública, y todas se fusionan en la misma lista de permitidos en cada build.

Frontmatter es la opción más granular. Agrega public: true a cualquier archivo .mdx y solo esa página escapa al control de acceso:

---
title: Get started
public: true
---

Los grupos de navegación cubren toda una sección a la vez. Establece public: true en un group o tab en la navegación de tu docs.json, y todas las páginas bajo él serán públicas. Útil para una pestaña de "Marketing" junto a documentación privada de ingeniería:

{
  "navigation": {
    "tabs": [
      {
        "tab": "Marketing",
        "public": true,
        "groups": [
          {
            "group": "Overview",
            "pages": ["landing", "pricing", "changelog"]
          }
        ]
      },
      {
        "tab": "Internal",
        "groups": [
          { "group": "Runbooks", "pages": ["deploys", "oncall"] }
        ]
      }
    ]
  }
}

Los globs explícitos en auth.password.public[] manejan lo que el frontmatter y la navegación no pueden: páginas de inicio de nivel superior, rutas generadas dinámicamente o un subárbol completo que prefieres no reescribir.

{
  "auth": {
    "password": {
      "enabled": true,
      "hint": "Ask #docs-access on Slack",
      "public": [
        "/landing",
        "/pricing",
        "/marketing/**",
        "/blog/*"
      ]
    }
  }
}

Los globs admiten * (un segmento de ruta) y ** (cualquier profundidad). Un / simple es rechazado en la validación: si Jamdesk lo aceptara, un solo error tipográfico podría desbloquear silenciosamente todo tu sitio. Después de cada build, la tarjeta del dashboard muestra la lista de permitidos resuelta, para que puedas verificar lo que el build realmente capturó.

Proteger solo algunas páginas

El modo para páginas específicas es el flujo opuesto: todo es público por defecto y tú decides qué páginas individuales quedan protegidas.

---
title: Incident Runbook
description: What to do when the deploys dashboard is on fire.
private: true
---

{
  "auth": {
    "password": {
      "hint": "Ask the on-call engineer",
      "private": ["/admin/runbook", "/internal/api-keys"]
    }
  }
}

git add content/runbook.mdx docs.json
git commit -m "Gate the incident runbook"
git push

Lo que ven los visitantes

Cuando alguien accede a una página protegida, ve una tarjeta de acceso centrada sin barra lateral, sin elementos de navegación y sin indicación de qué hay detrás, salvo el nombre del sitio y un hint opcional.

La tarjeta lleva la marca de tu sitio con el logo y el color primario de docs.json. El campo de contraseña tiene un botón para mostrar u ocultar el texto y recibe el foco automáticamente.

Las contraseñas incorrectas muestran la misma tarjeta con un mensaje de error, un campo nuevo y un pequeño retraso entre intentos. Una contraseña incorrecta y una solicitud sin contraseña muestran la misma pantalla, por lo que nada en la página distingue "contraseña incorrecta" de "aún no se ha ingresado ninguna contraseña".

Una vez que el visitante ingresa la contraseña correcta, recibe una cookie firmada y puede navegar con normalidad hasta que la sesión expire o la revoques.

Rotación y revocación de sesiones

Las contraseñas se comparten. Las personas se van. Querrás cambiarla tarde o temprano.

Abre la tarjeta Password Protection, escribe una nueva frase de contraseña en el campo Rotate password y haz clic en Save new password. Todos los que tenían la contraseña anterior quedan bloqueados en su siguiente solicitud; todos los que tienen la nueva contraseña pueden acceder. La rotación tiene efecto inmediato y no requiere un rebuild.

Si solo quieres forzar el cierre de sesión de todas las sesiones activas sin cambiar la frase de contraseña (por ejemplo, si el portátil de alguien desapareció), haz clic en Revoke all sessions. Esto incrementa un contador de versión del lado del servidor, lo que invalida todas las cookies emitidas antes del incremento. Los visitantes vuelven a ingresar la contraseña actual y recuperan el acceso.

Desactivar la protección

La protección está controlada por docs.json, por lo que desactivarla implica editar el archivo y hacer push.

• Todo el sitio: elimina auth.password.enabled (o establécelo en false).
• Páginas específicas: elimina todos los marcadores private: true y vacía auth.password.private.

En el siguiente build, Jamdesk elimina el hash de contraseña almacenado y vuelve a mostrar la tarjeta en estado Off. No queda ningún estado "inactivo". Si vuelves a activar la protección más adelante, necesitarás elegir una nueva contraseña.

Reglas de precedencia

Una sola página puede estar afectada por varias señales a la vez. El orden de resolución, de más a menos específico:

• Si auth.password.enabled es true, todo el sitio está protegido. private: true en páginas individuales se vuelve redundante.
• Si una página está marcada como public: true y private: true al mismo tiempo, public gana. El valor predeterminado más seguro es el que no filtra accidentalmente una página.
• El frontmatter public: true, el public: true de grupos de navegación y los globs de auth.password.public[] se fusionan en una sola lista de permitidos. No existe una regla de "más específico gana". Si cualquier señal indica que una página es pública, es pública.
• Si auth.password.private[] está configurado pero auth.password.enabled no lo está, Jamdesk activa el modo para páginas específicas automáticamente. No necesitas hacer nada más.

Cómo funcionan las sesiones y la limitación de solicitudes

Surgen tres preguntas con cualquier nuevo sistema de autenticación.

La cookie de sesión. Al desbloquear correctamente, Jamdesk establece una cookie llamada jd_auth_<slug> (por ejemplo, jd_auth_acme). Es HttpOnly, Secure, SameSite=Lax, con alcance al host y firmada con HMAC-SHA256. El payload incluye el slug del proyecto, el contador de versión actual y una marca de tiempo de expiración, por lo que cualquier manipulación falla la validación. La duración predeterminada es de 30 días, renovada en cada acceso exitoso.

Limitación de solicitudes. El endpoint de acceso aplica dos contadores por hora: 10 intentos por IP y 100 intentos por proyecto. Ambos se aplican antes de la verificación del hash scrypt para que un intento de fuerza bruta no pueda consumir CPU ni filtrar información de tiempo. Superar cualquiera de los límites devuelve 429 Too Many Requests con un encabezado Retry-After.

Almacenamiento. Tu contraseña se hashea con scrypt y se almacena en el Firestore del dashboard. Nunca llega a tu repositorio, a tu docs.json ni a un artefacto del build. Si la pierdes, rótala. No existe ninguna ruta de recuperación.

Pruebas durante el desarrollo local

jamdesk dev ejecuta tu documentación contra el contenido R2 en vivo y la configuración en vivo. La protección con contraseña no se aplica en el servidor de desarrollo local, por lo que puedes hacer preview de las páginas protegidas sin conocer la contraseña. Esto es deliberado: eres el autor, ya tienes acceso al repositorio, y bloquear el preview local con una contraseña sería fricción sin ningún beneficio de seguridad.

Si quieres verificar el acceso real, accede al sitio desplegado en <slug>.jamdesk.app (o tu dominio personalizado) desde una ventana del navegador que aún no tenga la cookie.

Solución de problemas

¿Qué sigue?