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, documentación solo para socios, funciones de acceso anticipado. La protección con contraseña te ofrece una frase de contraseña compartida que protege ya sea todo el sitio o un conjunto específico de páginas, sin mover nada de tu repositorio existente.

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

Nota: Las capturas de pantalla en esta página fueron creadas en inglés; tu interfaz puede aparecer de forma diferente si tienes el idioma configurado en otro idioma.

¿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 del dashboard, la misma pantalla de desbloqueo y los mismos controles de rotación y revocación. Puedes cambiar entre ellos en cualquier momento editando docs.json y haciendo push.

Protege todo tu 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 de sitio completo tiene una salida de emergencia: puedes mantener páginas específicas públicas incluso mientras el resto del sitio está bloqueado. Así es como publicas una página de destino 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.

El frontmatter es la opción más granular. Añade public: true a cualquier archivo .mdx y solo esa página escapa de la puerta:

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

Los grupos de navegación cubren una sección completa de una vez. Establece public: true en un group o tab en la navegación de tu docs.json, y cada página bajo él es pública. Útil para una pestaña de "Marketing" que está junto a documentación de ingeniería privada:

{
  "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 bajo auth.password.public[] manejan lo que el frontmatter y la navegación no pueden: páginas de destino 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 respetara, 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 recogió.

Protege solo unas pocas páginas

El modo de páginas específicas es el flujo de trabajo opuesto: todo es público por defecto, y tú incluyes páginas individuales en la puerta.

---
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, obtiene una tarjeta de desbloqueo centrada sin barra lateral, sin chrome y sin indicación de qué hay detrás de la puerta, excepto el nombre del sitio y una sugerencia opcional.

La tarjeta tiene 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/ocultar y autoenfoque.

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 llegan a la misma pantalla, por lo que nada en la página distingue "contraseña incorrecta" de "aún no se ha ingresado una contraseña".

Una vez que un visitante ingresa la contraseña correcta, obtiene una cookie firmada y puede navegar normalmente hasta que la sesión expire o la revoques.

Rotar y revocar sesiones

Las contraseñas se comparten. La gente se va. Querrás cambiarla eventualmente.

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 próxima solicitud; todos los que tienen la nueva contraseña entran. La rotación tiene efecto inmediato y no requiere una reconstrucción.

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

Deshabilitar la protección

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

• Sitio completo: elimina auth.password.enabled (o establécelo en false).
• Páginas específicas: elimina todos los marcadores private: true y limpia auth.password.private.

En el próximo build, Jamdesk elimina el hash de contraseña almacenado y devuelve la tarjeta al estado Off. No queda ningún estado "inactivo". Si vuelves a habilitar la protección más adelante, deberás elegir una nueva contraseña.

Reglas de precedencia

Una sola página puede ser 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 tanto con public: true como con private: true, público gana. El valor predeterminado más seguro es el que no filtra accidentalmente una página.
• El frontmatter public: true, el grupo de navegación public: true y los globs de auth.password.public[] se fusionan en una sola lista de permitidos. No hay una regla de "el más específico gana". Si alguna señal dice que una página es pública, es pública.
• Si auth.password.private[] está establecido pero auth.password.enabled no lo está, Jamdesk activa el modo de páginas específicas automáticamente. No necesitas hacer nada más.

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

Tres preguntas surgen con cualquier nuevo sistema de autenticación.

La cookie de sesión. En un desbloqueo exitoso, 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 vida útil predeterminada es de 30 días, renovada en cada desbloqueo exitoso.

Limitación de velocidad. El endpoint de desbloqueo 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, por lo que un intento de fuerza bruta no puede quemar CPU ni filtrar información de tiempo. Alcanzar 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, tu docs.json ni a un artefacto de build. Si la pierdes, rótala. No existe una 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 previsualizar páginas protegidas sin conocer la contraseña. Esto es deliberado: eres el autor, ya tienes las llaves del repositorio, y bloquear la preview local con una contraseña sería fricción sin ningún beneficio de seguridad.

Si quieres verificar la puerta 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?