Proteção por senha

Às vezes, você quer uma documentação que permaneça no Git e online, mas não fique visível para todos. Exemplos comuns incluem runbooks, guias de pré-lançamento, documentação exclusiva para parceiros e recursos de acesso antecipado. A proteção por senha fornece uma única senha compartilhada que controla o acesso a todo o site ou a um conjunto específico de páginas, sem mover nada do seu repositório existente.

As capturas de tela mostram a interface em inglês.

Qual modo devo escolher?

O Jamdesk tem dois modos de proteção por senha. Escolha um com base no que é público e no que não é.

Ambos os modos compartilham o mesmo cartão no dashboard, a mesma tela de desbloqueio e os mesmos controles de rotação e revogação. Você pode alternar entre eles a qualquer momento editando docs.json e fazendo push.

Proteja todo o seu 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=/"

Exceções públicas

O modo para todo o site tem uma alternativa: você pode manter páginas específicas públicas mesmo enquanto o restante do site está protegido. É assim que você publica uma landing page de marketing ou um formulário de cadastro junto com a documentação privada.

Você tem três maneiras de marcar uma página como pública, e todas são combinadas na mesma lista de permissões em cada build.

Frontmatter é a opção mais granular. Adicione public: true a qualquer arquivo .mdx e somente essa página ficará fora da proteção:

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

Grupos de navegação abrangem uma seção inteira de uma só vez. Defina public: true em um group ou tab na navegação do docs.json, e todas as páginas abaixo dele serão públicas. Útil para uma aba "Marketing" ao lado da documentação privada de engenharia:

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

Globs explícitos em auth.password.public[] lidam com tudo que o frontmatter e a navegação não conseguem: landing pages no nível superior, rotas geradas dinamicamente ou uma árvore inteira que você prefere não reescrever.

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

Os globs aceitam * (um segmento de caminho) e ** (qualquer profundidade). Uma / isolada é rejeitada na validação: se o Jamdesk a aceitasse, um simples erro de digitação poderia desbloquear silenciosamente todo o seu site. Após cada build, o cartão do dashboard mostra a lista de permissões resolvida, para que você possa verificar o que o build realmente identificou.

Proteja apenas algumas páginas

O modo para páginas específicas usa o fluxo oposto: tudo é público por padrão, e você opta por incluir páginas individuais na proteção.

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

O que os visitantes veem

Quando alguém acessa uma página protegida, vê um cartão de desbloqueio centralizado. Ele mostra apenas o nome do site e uma dica opcional, sem barra lateral ou navegação.

O cartão usa o logotipo e a cor primária do seu site definidos em docs.json. O campo de senha tem um controle para revelar o conteúdo e recebe foco automaticamente.

Senhas incorretas exibem o mesmo cartão com uma mensagem de erro, um campo vazio e um pequeno atraso entre as tentativas. Uma senha incorreta e uma requisição sem senha levam à mesma tela, portanto nada na página diferencia "senha incorreta" de "nenhuma senha inserida ainda".

Depois que o visitante insere a senha correta, recebe um cookie assinado e pode navegar normalmente até a sessão expirar ou você revogá-la.

Rotação e revogação de sessões

Uma senha compartilhada eventualmente precisa ser alterada, por exemplo, depois de ser compartilhada com muitas pessoas ou quando alguém deixa a equipe.

Abra o cartão Password Protection, digite uma nova senha no campo Rotate password e clique em Save new password. Todas as pessoas com a senha antiga perderão o acesso na próxima requisição; quem tiver a nova senha poderá entrar. A rotação entra em vigor imediatamente e não exige um novo build.

Se quiser apenas forçar o logout de todas as sessões ativas sem alterar a senha (por exemplo, se o laptop de alguém desapareceu), clique em Revoke all sessions. Isso incrementa um contador de versão no servidor, invalidando todos os cookies emitidos antes do incremento. Os visitantes inserem novamente a senha atual e recuperam o acesso.

Desativação da proteção

A proteção é controlada pelo docs.json, portanto desativá-la significa editar o arquivo e fazer push.

• Todo o site: remova auth.password.enabled (ou defina-o como false).
• Páginas específicas: remova todos os marcadores private: true e limpe auth.password.private.

No próximo build, o Jamdesk exclui o hash de senha armazenado e retorna o cartão ao estado Off. Nenhum estado "inativo" permanece. Se você reativar a proteção posteriormente, precisará escolher uma nova senha.

Regras de precedência

Uma única página pode ser afetada por vários sinais ao mesmo tempo. A ordem de resolução, da mais específica para a menos específica, é:

• Se auth.password.enabled for true, todo o site será protegido. private: true em páginas individuais se torna redundante.
• Se uma página for marcada como public: true e private: true, public vence. O padrão mais seguro é aquele que não expõe uma página por acidente.
• public: true no frontmatter, public: true em grupos de navegação e os globs de auth.password.public[] são combinados em uma única lista de permissões. Não existe uma regra de "vence o mais específico". Se qualquer sinal indicar que uma página é pública, ela será pública.
• Se auth.password.private[] estiver definido, mas auth.password.enabled não estiver, o Jamdesk ativará automaticamente o modo para páginas específicas. Você não precisa fazer mais nada.

Como funcionam as sessões e a limitação de taxa

Esta seção aborda o cookie de sessão, os limites de taxa e o armazenamento da senha.

O cookie de sessão. Após um desbloqueio bem-sucedido, o Jamdesk define um cookie chamado jd_auth_<slug> (por exemplo, jd_auth_acme). Ele é HttpOnly, Secure, SameSite=Lax, limitado ao host e assinado com HMAC-SHA256. O payload inclui o slug do projeto, o contador de versão atual e um registro de data e hora de expiração, portanto qualquer adulteração falha na validação. A duração padrão é de 30 dias, renovada a cada desbloqueio bem-sucedido.

Limitação de taxa. O endpoint de desbloqueio aplica dois contadores por hora: 10 tentativas por IP e 100 tentativas por projeto. Ambos são aplicados antes da verificação do hash scrypt, para que uma tentativa de força bruta não consuma CPU nem revele informações de tempo. Atingir qualquer um dos limites retorna 429 Too Many Requests com um cabeçalho Retry-After.

Armazenamento. Sua senha recebe hash com scrypt e é armazenada no Firestore do dashboard. Ela nunca chega ao seu repositório, ao seu docs.json ou a um artefato de build. Se você perdê-la, faça a rotação. Não existe caminho de recuperação.

Testes durante o desenvolvimento local

jamdesk dev executa sua documentação usando o conteúdo R2 ativo e a configuração ativa. A proteção por senha não é aplicada no servidor de desenvolvimento local, para que você possa visualizar páginas protegidas sem saber a senha. Isso é intencional: você é o autor, já tem as chaves do repositório, e bloquear a visualização local com uma barreira de senha criaria atrito sem benefício de segurança.

Se quiser verificar a proteção real, acesse o site publicado em <slug>.jamdesk.app (ou seu domínio personalizado) usando uma janela do navegador que ainda não tenha o cookie.

Solução de problemas

O que vem a seguir?