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 habituales 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 acceso compartida que protege todo tu sitio o un conjunto específico de páginas, sin mover nada fuera 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 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 sitio completo tiene una vía de escape: puedes mantener páginas específicas públicas incluso mientras el resto del sitio está protegido. 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 allow-list 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 protección:

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

Los grupos de navegación cubren toda una sección de una vez. Define public: true en un group o un tab en la navegación de tu docs.json, y todas las páginas debajo se vuelven públicas. Útil para un tab "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[] gestionan todo lo que el frontmatter y la navegación no pueden: páginas de aterrizaje 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). Una / sola es rechazada en la validación: si Jamdesk la aceptara, un solo error tipográfico podría desbloquear silenciosamente todo tu sitio. Después de cada build, la tarjeta del dashboard muestra la allow-list resuelta, para que puedas verificar qué recogió realmente el build.

Protege solo algunas páginas

El modo páginas específicas sigue el flujo de trabajo opuesto: todo es público por defecto, y tú decides qué páginas proteger individualmente.

---
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. Solo muestra el nombre del sitio y una pista opcional, sin barra lateral ni navegación.

La tarjeta está personalizada con el logo de tu sitio y el color principal de 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 vacío, 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 "todavía no se ha introducido ninguna contraseña".

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

Herramientas de IA y claves de API

Las herramientas que no pueden introducir la contraseña, como un cliente MCP o un script que descarga llms.txt, pueden usar una clave de API del proyecto en su lugar. La clave funciona para el servidor MCP, las URL de páginas .md y los archivos llms. Nunca abre las páginas HTML ni el chat de IA.

Rotación y revocación de sesiones

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

Abre la tarjeta Password Protection, escribe una nueva frase de acceso 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 contraseña pueden entrar. La rotación tiene efecto 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 acceso (por ejemplo, si se perdió el portátil de alguien), haz clic en Revoke all sessions en su lugar. 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 introducir la contraseña actual y recuperan el acceso.

Desactivar la protección

La protección la controla docs.json, así que desactivarla implica editar el archivo y hacer push.

• Sitio completo: elimina auth.password.enabled (o defínelo como false).
• Páginas específicas: elimina todos los marcadores private: true y borra auth.password.private.

En el siguiente build, Jamdesk elimina el hash de contraseña almacenado y devuelve la tarjeta al estado Off. No queda ningún estado "inactivo" persistente. 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 está protegido. private: true en páginas individuales se vuelve redundante.
• Si una página está marcada tanto public: true como private: true, gana public. El valor por defecto más seguro es el que evita filtrar una página por accidente.
• El public: true del frontmatter, el public: true de un grupo de navegación, y los globs de auth.password.public[] se combinan en una sola allow-list. No hay una regla de "gana lo más específico". Si alguna señal indica que una página es pública, es pública.
• Si auth.password.private[] está definido pero auth.password.enabled no lo está, Jamdesk activa automáticamente el modo páginas específicas. No necesitas hacer nada más.

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

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

La cookie de sesión. Tras un desbloqueo exitoso, Jamdesk define una cookie llamada jd_auth_<slug> (por ejemplo, jd_auth_acme). Es HttpOnly, Secure, SameSite=Lax, limitada al host, y firmada con HMAC-SHA256. La carga útil incluye el slug del proyecto, el contador de versión actual, y una marca de tiempo de expiración, de modo que cualquier manipulación falla la validación. La duración por defecto es de 30 días, renovada en cada desbloqueo exitoso.

Limitación de solicitudes. El endpoint de desbloqueo aplica dos contadores por hora: 10 intentos por IP y 100 intentos por proyecto. Ambos se verifican antes de comprobar el hash scrypt, para que un intento de fuerza bruta no pueda consumir CPU ni filtrar información de tiempos. Alcanzar cualquiera de los dos 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 ningún artefacto de build. Si la pierdes, haz una rotación. No existe ninguna vía de recuperación.

Pruebas durante el desarrollo local

jamdesk dev ejecuta tu documentación contra el contenido de R2 en vivo 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 protegidas sin conocer la contraseña. Esto es intencional: tú eres el autor, ya tienes las claves 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 la protección 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?