Protection par mot de passe

Parfois vous souhaitez que votre documentation soit en ligne, accessible, versionnée dans Git, mais pas visible par tout le monde. Runbooks, guides pré-lancement, docs réservées aux partenaires, fonctionnalités en accès anticipé. La protection par mot de passe vous donne une phrase secrète partagée unique qui protège soit l'ensemble de votre site, soit un ensemble spécifique de pages, sans rien déplacer de votre dépôt existant.

Les captures d'écran montrent l'interface en anglais.

Quel mode choisir ?

Jamdesk propose deux modes de protection par mot de passe. Choisissez en fonction de ce qui est public et de ce qui ne l'est pas.

Les deux modes partagent la même carte dashboard, le même écran de déverrouillage, et les mêmes contrôles de rotation et révocation. Vous pouvez basculer entre eux à tout moment en modifiant docs.json et en poussant.

Protéger l'ensemble de votre site

{
  "$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=/"

Exceptions publiques

Le mode site entier dispose d'une porte de sortie : vous pouvez garder des pages spécifiques publiques même si le reste du site est protégé. C'est ainsi que vous publiez une page d'accueil marketing ou un formulaire d'inscription à côté de docs privées.

Vous disposez de trois façons de marquer une page comme publique, et elles fusionnent toutes dans la même liste d'autorisation à chaque build.

Le frontmatter est l'option la plus granulaire. Ajoutez public: true à n'importe quel fichier .mdx et uniquement cette page échappe à la protection :

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

Les groupes de navigation couvrent une section entière d'un coup. Définissez public: true sur un group ou un tab dans votre navigation docs.json, et chaque page sous celui-ci est publique. Pratique pour un onglet "Marketing" qui se trouve à côté de docs d'ingénierie privées :

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

Les globs explicites sous auth.password.public[] gèrent tout ce que le frontmatter et la navigation ne peuvent pas : les pages d'accueil de premier niveau, les routes générées dynamiquement, ou un sous-arbre entier que vous préférez ne pas réécrire.

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

Les globs supportent * (un segment de chemin) et ** (n'importe quelle profondeur). Un simple / est rejeté à la validation : si Jamdesk l'honorait, une seule faute de frappe pourrait silencieusement déverrouiller l'ensemble de votre site. Après chaque build, la carte dashboard affiche la liste d'autorisation résolue, afin que vous puissiez vérifier ce que le build a réellement capturé.

Protéger seulement quelques pages

Le mode pages spécifiques est le flux de travail inverse : tout est public par défaut, et vous optez individuellement les pages dans la protection.

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

Ce que voient les visiteurs

Quand quelqu'un arrive sur une page protégée, il voit une carte de déverrouillage centrée sans barre latérale, sans chrome, et sans indication de ce qui se trouve derrière la porte en dehors du nom du site et d'un indice optionnel.

La carte est personnalisée avec le logo et la couleur principale de votre site depuis docs.json. Le champ de mot de passe dispose d'un bouton de révélation et est mis en focus automatiquement.

Les mauvais mots de passe affichent la même carte avec un message d'erreur, un nouveau champ de saisie, et un petit délai entre les tentatives. Un mot de passe incorrect et une requête sans mot de passe atterrissent tous deux sur le même écran, donc rien sur la page ne distingue "mot de passe erroné" de "aucun mot de passe saisi encore".

Une fois qu'un visiteur saisit le bon mot de passe, il reçoit un cookie signé et peut naviguer normalement jusqu'à l'expiration de la session ou jusqu'à ce que vous la révoquez.

Rotation et révocation des sessions

Les mots de passe se partagent. Les gens partent. Vous voudrez le changer à un moment donné.

Ouvrez la carte Password Protection, saisissez une nouvelle phrase secrète dans le champ Rotate password, et cliquez sur Save new password. Toute personne avec l'ancien mot de passe est bloquée à sa prochaine requête ; toute personne avec le nouveau mot de passe peut entrer. La rotation prend effet immédiatement et ne nécessite pas de rebuild.

Si vous voulez simplement forcer la déconnexion de toutes les sessions actives sans changer la phrase secrète (par exemple si l'ordinateur portable de quelqu'un a disparu), cliquez sur Revoke all sessions à la place. Cela incrémente un compteur de version côté serveur, ce qui invalide tous les cookies émis avant l'incrémentation. Les visiteurs saisissent à nouveau le mot de passe actuel et peuvent se reconnecter.

Désactiver la protection

La protection est pilotée par docs.json, donc la désactiver signifie modifier le fichier et pousser.

• Site entier : supprimez auth.password.enabled (ou définissez-le à false).
• Pages spécifiques : supprimez chaque marqueur private: true et videz auth.password.private.

Au prochain build, Jamdesk supprime le hash du mot de passe stocké et remet la carte sur Off. Aucun état "dormant" ne persiste. Si vous réactivez la protection plus tard, vous devrez choisir un nouveau mot de passe.

Règles de priorité

Une seule page peut être touchée par plusieurs signaux à la fois. L'ordre de résolution, du plus spécifique au moins spécifique :

• Si auth.password.enabled est true, l'ensemble du site est protégé. private: true sur des pages individuelles devient redondant.
• Si une page est marquée à la fois public: true et private: true, public l'emporte. La valeur par défaut la plus sûre est celle qui n'expose pas accidentellement une page.
• Le frontmatter public: true, le nav-group public: true, et les globs auth.password.public[] fusionnent tous dans une seule liste d'autorisation. Pas de règle "le plus spécifique l'emporte". Si un signal dit qu'une page est publique, elle est publique.
• Si auth.password.private[] est défini mais pas auth.password.enabled, Jamdesk active le mode pages spécifiques automatiquement. Vous n'avez rien d'autre à faire.

Fonctionnement des sessions et de la limitation de débit

Trois questions reviennent avec tout nouveau système d'authentification.

Le cookie de session. Lors d'un déverrouillage réussi, Jamdesk définit un cookie nommé jd_auth_<slug> (par exemple, jd_auth_acme). Il est HttpOnly, Secure, SameSite=Lax, limité à l'hôte, et signé avec HMAC-SHA256. La charge utile inclut le slug du projet, le compteur de version actuel, et un horodatage d'expiration, de sorte que toute altération échoue à la validation. La durée de vie par défaut est de 30 jours, renouvelée à chaque déverrouillage réussi.

Limitation de débit. L'endpoint de déverrouillage applique deux compteurs par heure : 10 tentatives par IP et 100 tentatives par projet. Les deux sont vérifiés avant le calcul du hash scrypt afin qu'une tentative de force brute ne puisse pas consommer du CPU ni laisser fuir des informations de timing. Atteindre l'une ou l'autre limite retourne 429 Too Many Requests avec un en-tête Retry-After.

Stockage. Votre mot de passe est haché avec scrypt et stocké dans le Firestore du dashboard. Il n'atterrit jamais dans votre dépôt, votre docs.json, ni dans un artefact de build. Si vous le perdez, effectuez une rotation. Aucun chemin de récupération n'existe.

Test pendant le développement local

jamdesk dev exécute votre documentation contre le contenu R2 en direct et la configuration en direct. La protection par mot de passe n'est pas appliquée dans le serveur de développement local, vous pouvez donc prévisualiser les pages protégées sans connaître le mot de passe. C'est délibéré : vous êtes l'auteur, vous avez déjà les clés du dépôt, et bloquer le preview local sur un mot de passe serait une friction sans bénéfice de sécurité.

Si vous voulez vérifier la protection réelle, accédez au site déployé sur <slug>.jamdesk.app (ou votre domaine personnalisé) depuis une fenêtre de navigateur qui n'a pas encore le cookie.

Dépannage

Étape suivante