StaffAuth

Staff accounts are frozen at join until they log in with a BCrypt-hashed password.

Privatev0.0.2Utilities

RequiresTypeWriter0.9.0-beta-177 (BTC build)GUIPermissionsoptional

Built for the BornToCraft network. This extension is documented for reference and is not distributed.

Support

Overview

StaffAuth protects staff accounts. When a player joins and has the staff permission (security.admin by default), they are frozen until they authenticate: they cannot move, interact, break or place blocks, open inventories, chat, fight or use commands other than /staffauth. A staff member without a password registers one on first join; afterwards they log in with it.

Passwords are never sent as command arguments or typed in chat. They are entered in a Paper dialog input, or on an optional number keypad menu, and are stored only as BCrypt hashes in a TypeWriter artifact. Failed attempts are rate-limited with a growing cooldown and can kick the player.

Everyone is held for about a tick at join while their permissions load, silently, so that a slow permission backend never lets staff in unchecked. Players who are not staff are then released; if the permissions are not established within 10 seconds the player is kicked with an explanation.

Features

• Join freeze — unauthenticated staff cannot move, interact, build, drop, pick up, consume, fish, take or deal damage, chat or run commands.
• Register and login — first-time staff register by entering a password twice; others log in.
• Hashed storage — only BCrypt hashes are saved, with a configurable cost factor.
• Attempt limits — a cooldown that doubles after each failure (up to 60 seconds) and a kick after maxAttempts failures.
• Session timeout — optionally send authenticated staff back to the login after a number of minutes.
• Dialog or keypad — a Paper dialog input by default, plus an optional digit keypad menu built from a GUI layout.
• Admin tools — reset a stored password or force a logout.
• Optional Permissions extension — waits for the permissions to load before deciding who is staff.

Installation

1. Install the GUI extension: the login dialog and the keypad menu are opened through it. Without it, /staffauth answers that the interface is unavailable.
2. Optionally install the BTC Permissions extension if your servers load permissions from a database; StaffAuth detects it automatically.
3. Put the StaffAuth JAR in plugins/Typewriter/extensions/ and restart the server.
4. Give the staff permission (security.admin) to the accounts that must authenticate.

Getting started

1. In the TypeWriter web panel, open a static page and add a Staff Auth Passwords artifact. Never change its artifactId afterwards, or the stored passwords are lost.
2. On the same page add one Staff Auth Config entry. Check staffPermission, adminPermission, maxAttempts, minPasswordLength, bcryptCost and the messages.
3. Publish. StaffAuth needs both entries: without the config it does nothing, and without the artifact staff are let in (an error is logged).
4. Join with a test account that has the staff permission. You are frozen and asked to register: type a password in the dialog, then confirm it.
5. Reconnect: the dialog now asks for the password.
6. Optional: add a Staff Auth Menu action to use the keypad. See below.

One artifact, one config

StaffAuth uses the first Staff Auth Config and the first Staff Auth Passwords artifact it finds. Do not create several.

How it works

Authentication lasts until the player leaves the server (state is kept in memory only) or the optional session timeout expires. While restricted, the only command allowed is /staffauth (and /sa, which is only exempted from the block; it is not registered as an alias).

Menus

Joining, /staffauth, login and register open a Paper dialog with a text input. When registering, the dialog is shown a second time to confirm the password. The prompt text comes from guiLoginPrompt, the title from guiTitle.

The Staff Auth Menu action opens an inventory keypad instead (digits only). Trigger it from an action chain if you prefer that look. In its layoutPool, give items a button type to turn them into keys:

Button type	Function
DIGIT_0 to DIGIT_9	Adds a digit to the password.
PASSWORD_DISPLAY	Shows one dot per digit entered.
LOGIN / REGISTER	Submits the password; the label is Register when the player has no password yet.
BACKSPACE	Removes the last digit.
CANCEL	Clears the entry and closes the menu.

The keypad can only type digits, and the password must still respect minPasswordLength. useGuiWhenAvailable controls whether a dialog is opened automatically at join.

Configuration

Everything is set in the entries. In message fields, use {attempts}, {max} and {length} as placeholders (curly braces, not MiniMessage tags): {attempts} and {max} in wrongPasswordMessage, {attempts} in maxAttemptsKickMessage, {length} (the minimum) and {max} in passwordTooShortMessage.

Passwords live in the artifact file chosen by artifactId, as a JSON map from player UUID to BCrypt hash. The artifact is cached for 5 seconds.

Commands

The command name comes from the commandName field of the config (default staffauth). There is no registered permission on the base command: anyone can run it, but it only has an effect for staff. Admin subcommands need the permission set in adminPermission.

Command	Description
/staffauth	Opens the login or registration dialog.
/staffauth open, login, register	Same as above.
/staffauth logout	Ends your authentication and shows the dialog again.
/staffauth status	Shows your state, whether you have the staff permission, and whether the GUI is available.
/staffauth reset <player>	Deletes the stored password of a player (name or UUID), who must register again. Requires adminPermission.
/staffauth force-logout <player>	Logs out an online player and shows them the dialog. Requires adminPermission.

Permissions

The permissions are configurable fields, not fixed nodes.

Permission	Grants
security.admin (staffPermission)	Marks a player as staff: they must authenticate.
security.staffauth.admin (adminPermission)	/staffauth reset and /staffauth force-logout.

Entries

3 entries, generated from the extension source.

Actions1

• Staff Auth MenuStaff Auth Menu

Commands1

• Staff Auth ConfigStaff Auth Config

Artifacts1

• Staff Auth DataStaff Auth Passwords

Troubleshooting

Staff walk in without being asked for a password. Check that both the config and the artifact are published. With no artifact, StaffAuth lets staff in and logs StaffAuth has no artifact entry. Also check that the player really has staffPermission (/staffauth status prints it).

The player is kicked with a message about permissions. The Permissions extension did not signal that the player's permissions were loaded within 10 seconds. Reconnect; if it persists, check the Permissions backend in the logs.

The StaffAuth interface is unavailable. The GUI extension is not loaded. Install it and restart.

Passwords disappeared. The artifact's artifactId was changed or the entry was recreated. Restore the previous id. A stored value that is not a valid UUID or BCrypt string makes the load fail and is logged as StaffAuth artifact could not be loaded; the player is kept frozen and told their state is unreadable.

Registration refused. The password must be between minPasswordLength (6) and maxPasswordLength (128) characters and contain no spaces or control characters. The two entries must match.

A player is kicked after failed logins. After maxAttempts (5 by default) failures the player is kicked with maxAttemptsKickMessage. Set maxAttempts to 0 to disable kicks; the cooldown still applies. /staffauth reset <player> clears a forgotten password.

Related extensions

• GUI — opens the login dialog and the keypad menu.