Protection par mot de passe

Il arrive que vous vouliez une documentation qui reste dans Git et en ligne, mais qui ne soit pas visible de tous. Voici des exemples courants : les runbooks, les guides pré-lancement, la documentation réservée aux partenaires et les fonctionnalités en accès anticipé. La protection par mot de passe vous donne une phrase secrète partagée unique qui verrouille soit l'ensemble de votre site, soit un ensemble spécifique de pages, sans rien déplacer hors 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 un selon ce qui est public et ce qui ne l'est pas.

Les deux modes partagent la même carte dans le dashboard, le même écran de déverrouillage, et les mêmes contrôles de rotation et de révocation. Vous pouvez passer de l'un à l'autre à tout moment en modifiant docs.json et en poussant vos changements.

Protégez tout 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 échappatoire : vous pouvez garder certaines pages publiques même si le reste du site est protégé. C'est ainsi que vous pouvez publier une landing page marketing ou un formulaire d'inscription à côté de documentation privée.

Vous disposez de trois façons de marquer une page comme publique, et elles fusionnent toutes dans la même allow-list à chaque build.

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

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

Les groupes de navigation couvrent une section entière en une fois. Définissez public: true sur un group ou un tab dans la navigation de votre docs.json, et toutes les pages en dessous deviennent publiques. Pratique pour un tab « Marketing » qui se trouve à côté de documentation d'ingénierie privée :

{
  "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 couvrir : pages d'accueil de premier niveau, routes générées dynamiquement, ou une sous-arborescence entière 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 prennent en charge * (un segment de chemin) et ** (n'importe quelle profondeur). Un simple / est rejeté lors de la validation : si Jamdesk l'acceptait, une seule faute de frappe pourrait déverrouiller silencieusement tout votre site. Après chaque build, la carte du dashboard affiche l'allow-list résolue, afin que vous puissiez vérifier ce que le build a réellement pris en compte.

Protégez seulement quelques pages

Le mode pages spécifiques suit le workflow inverse : tout est public par défaut, et vous choisissez individuellement les pages à protéger.

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

Lorsqu'une personne accède à une page protégée, elle obtient une carte de déverrouillage centrée. Celle-ci n'affiche que le nom du site et un indice optionnel, sans barre latérale ni navigation.

La carte est personnalisée avec le logo de votre site et la couleur principale définie dans docs.json. Le champ de mot de passe dispose d'un bouton pour afficher le mot de passe et de l'autofocus.

Un mot de passe incorrect affiche la même carte avec un message d'erreur, un champ vide et un léger délai entre les tentatives. Un mot de passe incorrect et une requête sans mot de passe aboutissent tous deux au même écran, si bien que rien sur la page ne distingue « mot de passe incorrect » de « aucun mot de passe saisi pour l'instant ».

Une fois que le 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évoquiez.

Outils d'IA et clés API

Les outils qui ne peuvent pas saisir le mot de passe, comme un client MCP ou un script qui récupère llms.txt, peuvent utiliser une clé API du projet à la place. La clé fonctionne pour le serveur MCP, les URL de pages .md et les fichiers llms. Elle n'ouvre jamais les pages HTML ni le chat IA.

Rotation et révocation des sessions

Un mot de passe partagé doit finir par changer, par exemple après avoir circulé ou quand quelqu'un quitte l'équipe.

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

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 plutôt sur Revoke all sessions. Cela incrémente un compteur de version côté serveur, ce qui invalide tous les cookies émis avant cet incrément. Les visiteurs ressaisissent le mot de passe actuel et peuvent revenir.

Désactiver la protection

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

• Site entier : supprimez auth.password.enabled (ou définissez-le sur false).
• Pages spécifiques : supprimez tous les marqueurs private: true et videz auth.password.private.

Au prochain build, Jamdesk supprime le hash du mot de passe stocké et fait repasser la carte à 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 même page peut être concernée par plusieurs signaux à la fois. L'ordre de résolution, du plus spécifique au moins spécifique :

• Si auth.password.enabled vaut true, tout le 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, c'est public qui l'emporte. Le comportement par défaut le plus sûr est celui qui évite de divulguer accidentellement une page.
• Le public: true du frontmatter, le public: true d'un groupe de navigation, et les globs auth.password.public[] fusionnent tous dans une seule allow-list. Il n'y a pas de règle « le plus spécifique l'emporte ». Si un seul signal indique qu'une page est publique, elle est publique.
• Si auth.password.private[] est défini mais que auth.password.enabled ne l'est pas, Jamdesk active automatiquement le mode pages spécifiques. Vous n'avez rien d'autre à faire.

Fonctionnement des sessions et de la limitation de débit

Cette section couvre le cookie de session, les limites de débit et le stockage du mot de passe.

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 fuiter d'informations de timing. Atteindre l'une ou l'autre limite renvoie 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, ou un artefact de build. Si vous le perdez, faites une rotation. Aucun moyen de récupération n'existe.

Tester en développement local

jamdesk dev exécute votre documentation avec 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, ce qui vous permet de prévisualiser les pages protégées sans connaître le mot de passe. C'est volontaire : vous êtes l'auteur, vous avez déjà les clés du dépôt, et bloquer l'aperçu local derrière un mur de 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é à l'adresse <slug>.jamdesk.app (ou votre domaine personnalisé) depuis une fenêtre de navigateur qui n'a pas encore le cookie.

Dépannage

Et ensuite ?