StaffAuth
Visão geral
O StaffAuth protege as contas da staff. Quando um jogador entra e tem a permissão de staff (security.admin por padrão), ele fica congelado até se autenticar: não pode se mover, interagir, quebrar ou colocar blocos, abrir inventários, conversar, lutar nem usar comandos além de /staffauth. Um membro da staff sem senha registra uma na primeira entrada; depois disso, faz login com ela.
As senhas nunca são enviadas como argumentos de comando nem digitadas no chat. Elas são inseridas em um campo de diálogo do Paper, ou em um menu opcional de teclado numérico, e são armazenadas apenas como hashes BCrypt em um artifact do TypeWriter. As tentativas malsucedidas têm taxa limitada, com um cooldown crescente, e podem expulsar o jogador.
Todos ficam retidos por cerca de um tick na entrada, silenciosamente, enquanto suas permissões carregam, para que um backend de permissões lento nunca deixe a staff entrar sem verificação. Os jogadores que não são staff são então liberados; se as permissões não forem estabelecidas em 10 segundos, o jogador é expulso com uma explicação.
Recursos
- Congelamento na entrada — a staff não autenticada não pode se mover, interagir, construir, soltar, pegar, consumir, pescar, receber ou causar dano, conversar nem executar comandos.
- Registro e login — a staff de primeira vez se registra digitando uma senha duas vezes; os demais fazem login.
- Armazenamento com hash — apenas hashes BCrypt são salvos, com um fator de custo configurável.
- Limites de tentativas — um cooldown que dobra após cada falha (até 60 segundos) e uma expulsão após
maxAttemptsfalhas. - Timeout de sessão — opcionalmente, envie a staff autenticada de volta ao login após um número de minutos.
- Diálogo ou teclado — um campo de diálogo do Paper por padrão, além de um menu opcional de teclado de dígitos construído a partir de um layout do GUI.
- Ferramentas de admin — redefina uma senha armazenada ou force um logout.
- Extensão Permissions opcional — aguarda o carregamento das permissões antes de decidir quem é staff.
Instalação
- Instale a extensão GUI: o diálogo de login e o menu de teclado são abertos por meio dela. Sem ela,
/staffauthresponde que a interface está indisponível. - Opcionalmente, instale a extensão BTC Permissions se seus servidores carregam permissões de um banco de dados; o StaffAuth a detecta automaticamente.
- Coloque o JAR do StaffAuth em
plugins/Typewriter/extensions/e reinicie o servidor. - Conceda a permissão de staff (
security.admin) às contas que devem se autenticar.
Primeiros passos
- No painel web do TypeWriter, abra uma página static e adicione um artifact Staff Auth Passwords. Nunca altere seu
artifactIddepois, ou as senhas armazenadas serão perdidas. - Na mesma página, adicione uma entry Staff Auth Config. Verifique
staffPermission,adminPermission,maxAttempts,minPasswordLength,bcryptCoste as mensagens. - Publique. O StaffAuth precisa das duas entries: sem a config ele não faz nada e, sem o artifact, a staff entra sem verificação (um erro é registrado no log).
- Entre com uma conta de teste que tenha a permissão de staff. Você fica congelado e é solicitado a se registrar: digite uma senha no diálogo e depois confirme-a.
- Reconecte-se: o diálogo agora pede a senha.
- Opcional: adicione uma action Staff Auth Menu para usar o teclado. Veja abaixo.
O StaffAuth usa a primeira Staff Auth Config e o primeiro artifact Staff Auth Passwords que encontrar. Não crie vários.
Como funciona
A autenticação dura até o jogador sair do servidor (o estado é mantido apenas na memória) ou até o timeout de sessão opcional expirar. Enquanto restrito, o único comando permitido é /staffauth (e /sa, que é apenas isento do bloqueio; ele não está registrado como alias).
Menus
Entrar, /staffauth, login e register abrem um diálogo do Paper com um campo de texto. Ao registrar, o diálogo é exibido uma segunda vez para confirmar a senha. O texto do prompt vem de guiLoginPrompt e o título de guiTitle.
A action Staff Auth Menu abre, em vez disso, um teclado de inventário (somente dígitos). Dispare-a a partir de uma cadeia de actions se preferir esse visual. Em seu layoutPool, dê aos itens um tipo de botão para transformá-los em teclas:
| Tipo de botão | Função |
|---|---|
DIGIT_0 a DIGIT_9 | Adiciona um dígito à senha. |
PASSWORD_DISPLAY | Mostra um ponto por dígito digitado. |
LOGIN / REGISTER | Envia a senha; o rótulo é Register quando o jogador ainda não tem senha. |
BACKSPACE | Remove o último dígito. |
CANCEL | Limpa a entrada e fecha o menu. |
O teclado só consegue digitar dígitos, e a senha ainda deve respeitar minPasswordLength. useGuiWhenAvailable controla se um diálogo é aberto automaticamente na entrada.
Configuração
Tudo é definido nas entries. Nos campos de mensagem, use {attempts}, {max} e {length} como placeholders (chaves, não tags MiniMessage): {attempts} e {max} em wrongPasswordMessage, {attempts} em maxAttemptsKickMessage, {length} (o mínimo) e {max} em passwordTooShortMessage.
As senhas ficam no arquivo do artifact escolhido por artifactId, como um mapa JSON de UUID do jogador para hash BCrypt. O artifact fica em cache por 5 segundos.
Comandos
O nome do comando vem do campo commandName da config (padrão staffauth). Não há permissão registrada no comando base: qualquer um pode executá-lo, mas ele só tem efeito para a staff. Os subcomandos de admin exigem a permissão definida em adminPermission.
| Comando | Descrição |
|---|---|
/staffauth | Abre o diálogo de login ou de registro. |
/staffauth open, login, register | O mesmo que acima. |
/staffauth logout | Encerra sua autenticação e mostra o diálogo novamente. |
/staffauth status | Mostra seu estado, se você tem a permissão de staff e se o GUI está disponível. |
/staffauth reset <player> | Exclui a senha armazenada de um jogador (nome ou UUID), que deve se registrar novamente. Exige adminPermission. |
/staffauth force-logout <player> | Desconecta um jogador online da autenticação e mostra a ele o diálogo. Exige adminPermission. |
Permissões
As permissões são campos configuráveis, não nodes fixos.
| Permissão | Concede |
|---|---|
security.admin (staffPermission) | Marca um jogador como staff: ele deve se autenticar. |
security.staffauth.admin (adminPermission) | /staffauth reset e /staffauth force-logout. |
Entries
3 entradas, geradas a partir do código-fonte da extensão.
Ações1
- Staff Auth MenuStaff Auth Menu
Comandos1
- Staff Auth ConfigStaff Auth Config
Artefatos1
- Staff Auth DataStaff Auth Passwords
Solução de problemas
A staff entra sem que a senha seja pedida. Verifique se tanto a config quanto o artifact estão publicados. Sem o artifact, o StaffAuth deixa a staff entrar e registra StaffAuth has no artifact entry. Verifique também se o jogador realmente tem staffPermission (/staffauth status o mostra).
O jogador é expulso com uma mensagem sobre permissões. A extensão Permissions não sinalizou que as permissões do jogador foram carregadas em 10 segundos. Reconecte-se; se persistir, verifique o backend do Permissions nos logs.
The StaffAuth interface is unavailable. A extensão GUI não está carregada. Instale-a e reinicie.
As senhas desapareceram. O artifactId do artifact foi alterado ou a entry foi recriada. Restaure o id anterior. Um valor armazenado que não seja um UUID ou uma string BCrypt válida faz o carregamento falhar e é registrado como StaffAuth artifact could not be loaded; o jogador permanece congelado e é informado de que seu estado está ilegível.
O registro é recusado. A senha deve ter entre minPasswordLength (6) e maxPasswordLength (128) caracteres e não conter espaços nem caracteres de controle. As duas digitações devem coincidir.
Um jogador é expulso após logins malsucedidos. Após maxAttempts (5 por padrão) falhas, o jogador é expulso com maxAttemptsKickMessage. Defina maxAttempts como 0 para desativar as expulsões; o cooldown continua valendo. /staffauth reset <player> limpa uma senha esquecida.
Extensões relacionadas
- GUI — abre o diálogo de login e o menu de teclado.