Protección con contraseña

A veces quieres documentación que permanezca en Git y en línea pero que no sea visible para todos. Ejemplos comunes incluyen runbooks, guías de prelanzamiento, documentación exclusiva para partners y funciones de acceso anticipado. La protección con contraseña te da una única frase de contraseña compartida que restringe el acceso a todo tu sitio o a un conjunto específico de páginas, sin mover nada fuera de tu repositorio existente.

¿Qué modo debo elegir?

Jamdesk tiene dos modos para la protección con contraseña. Elige uno según qué sea público y qué 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 vía de escape: puedes mantener páginas específicas públicas incluso mientras el resto del sitio está restringido. Así es como publicas una landing page 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 combinan en la misma lista de permitidos en cada build.

El frontmatter es la opción más granular. Agrega public: true a cualquier archivo .mdx y solo esa página escapa del bloqueo:

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

Los grupos de navegación cubren toda una sección a la vez. Configura public: true en un group o tab en la navegación de tu docs.json, y cada página debajo de él es pública. Útil para una pestaña "Marketing" que está junto a documentación interna 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 todo lo que el frontmatter y la navegación no pueden: landing pages de nivel superior, rutas generadas dinámicamente, o un subárbol completo que prefieras 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 se rechaza en la validación: si Jamdesk lo honrara, 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 qué recogió realmente el build.

Protege solo algunas 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 el bloqueo.

---
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

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

Cuando alguien llega a una página restringida, ve una tarjeta de desbloqueo centrada. Muestra solo el nombre del sitio y una pista opcional, sin barra lateral ni navegación.

La tarjeta lleva la marca del logo y el color primario de tu sitio desde docs.json. El campo de contraseña tiene un botón para mostrarla y autofocus.

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, así que nada en la página distingue "contraseña incorrecta" de "aún no se ingresó contraseña".

Una vez que un 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

Una contraseña compartida eventualmente necesita cambiar, por ejemplo después de haber sido compartida ampliamente o cuando alguien deja el equipo.

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 tengan la contraseña anterior quedan bloqueados en su siguiente solicitud; todos los que tengan la nueva pueden entrar. La rotación surte efecto de inmediato y no requiere un nuevo build.

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

Desactivar la protección

La protección se controla mediante docs.json, así que desactivarla significa editar el archivo y hacer push.

• Sitio completo: elimina auth.password.enabled (o configúralo como false).
• Páginas específicas: elimina todo marcador private: true y borra auth.password.private.

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

Reglas de precedencia

Una sola página puede verse 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 queda restringido. private: true en páginas individuales se vuelve redundante.
• Si una página está marcada tanto como public: true como private: true, gana public. El valor predeterminado más seguro es el que no filtra una página por accidente.
• El frontmatter public: true, el public: true de grupo de navegación y los globs de auth.password.public[] se combinan en una sola lista de permitidos. No hay 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á configurado pero auth.password.enabled no lo está, Jamdesk activa automáticamente el modo de páginas específicas. No necesitas hacer nada más.

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

Esta sección cubre la cookie de sesión, los límites de velocidad y el almacenamiento de contraseñas.

La cookie de sesión. Al desbloquear con éxito, Jamdesk establece una cookie llamada jd_auth_<slug> (por ejemplo, jd_auth_acme). Es HttpOnly, Secure, SameSite=Lax, limitada 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, así que cualquier manipulación falla la validación. La vida útil predeterminada es de 30 días, y se renueva 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, así que un intento de fuerza bruta no puede consumir CPU ni filtrar información de tiempo. Alcanzar cualquiera de los dos límites devuelve 429 Too Many Requests con un encabezado Retry-After.

Almacenamiento. Tu contraseña se protege con hash scrypt y se almacena en el Firestore del dashboard. Nunca llega a tu repositorio, a 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 en vivo de R2 y la configuración en vivo. La protección con contraseña no se aplica en el servidor de desarrollo local, así que puedes previsualizar páginas restringidas sin conocer la contraseña. Esto es deliberado: tú eres el autor, ya tienes las llaves del repositorio, y bloquear la vista previa local con un muro de contraseña sería fricción sin beneficio de seguridad.

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

Solución de problemas

¿Qué sigue?