Skip to content

User Manual v6.3.0

Jump to bottom
SzymeX edited this page Sep 24, 2026 · 1 revision

PureAuth 6.3.0 — Wiki

This is the complete operator and user manual for PureAuth 6.3.0. It covers the Paper/Purpur authentication module, the BungeeCord and Velocity network modules, every command and permission, every configuration field, all authentication and recovery procedures, Redis network mode, Fair Play Guard, messages, security, maintenance and troubleshooting.

1. What PureAuth does

PureAuth protects offline-mode Minecraft servers with password registration and login. Optional layers include a PIN GUI, TOTP two-factor authentication (2FA), one-time 2FA recovery codes, account recovery questions, CAPTCHA, short sessions, Premium Auto-Login, progressive login locks, administrator 2FA enforcement, backups, Discord webhooks and PlaceholderAPI support.

Version 6.3.0 adds:

  • Redis-backed multi-proxy duplicate-name protection, shared authentication state and shared sessions;
  • Fair Play Guard for administrator-led cheat/modification inspections;
  • persistent Fair Play Guard disconnect restrictions;
  • separate editable English and Polish message files;
  • a database migration that preserves all existing 6.2.0 accounts.

2. Requirements and module placement

Component Requirement
Backend Paper 26.2 or compatible Purpur build
Compiled Paper API 26.2.build.117-stable
plugin.yml API 26.2
Plugin bytecode Java 21
Practical Paper 26.2 runtime Java 25 or newer
BungeeCord API 1.21-R0.4
Velocity API 3.5.1
Backend server.properties online-mode=false

Spigot, Bukkit-only, Folia and Fabric/Forge are not supported targets. Never expose an offline-mode backend directly to the Internet. On a proxy network, firewall every backend so only the proxy can connect.

Files:

  • pureauth-paper-6.3.0-R.jar — install on every protected Paper/Purpur backend;
  • pureauth-bungee-6.3.0-R.jar — install only on BungeeCord;
  • pureauth-velocity-6.3.0-R.jar — install only on Velocity.

Do not install both proxy modules on one proxy. A proxy JAR does not replace the Paper JAR.

3. Installation

3.1 One Paper/Purpur server

  1. Stop the server.
  2. Put the Paper JAR in plugins/.
  3. Set online-mode=false in server.properties.
  4. Start once to generate plugins/PureAuth/config.yml and plugins/PureAuth/Messages/.
  5. Stop the server, review the generated settings, then start it again.
  6. Confirm that the console reports PureAuth 6.3.0 enabled without an exception.

The default network.mode: LOCAL and database.type: SQLITE are appropriate for one server.

3.2 Proxy network

  1. Install the Paper JAR on every authentication backend.
  2. Install the matching BungeeCord or Velocity JAR on every public proxy.
  3. Configure one shared MySQL/MariaDB database and the same table prefix in every module.
  4. Set all protected backends to offline mode and configure secure proxy forwarding.
  5. Firewall backend ports.
  6. For one proxy use network.mode: LOCAL. For two or more public proxies use network.mode: REDIS everywhere.
  7. In Redis mode, use the same Redis host, database and key_prefix on all PureAuth modules.

SQLite is not a network database. Do not share an SQLite file between servers or proxies.

4. Upgrade from 6.2.0

  1. Stop every proxy and backend.
  2. Back up the database and plugins/PureAuth/ directories.
  3. Replace all 6.2.0 modules together; do not run a mixed 6.2/6.3 network.
  4. Keep the existing database. PureAuth automatically adds fair_play_locked and fair_play_lock_reason.
  5. Merge your settings into the generated 6.3.0 config.
  6. Move customized user-facing text to Messages/EN_en.txt and/or Messages/PL_pl.txt.
  7. Configure Redis if the network has multiple public proxies.
  8. Configure the Fair Play Guard location before its first use.

Password hashes, PIN hashes, PIN lengths, 2FA secrets, backup codes, recovery data, locations, Premium flags and lock history are retained.

5. Authentication lifecycle

5.1 New password account

The player joins, receives a CAPTCHA when enabled, and runs /register <password> <password> [captcha]. PureAuth validates the password length, matching copies, CAPTCHA and per-IP account limit, stores a BCrypt hash, then authenticates the player.

5.2 Existing password account

The player runs /login <password>. A correct password proceeds to 2FA when enabled, otherwise login completes. Repeated bad credentials feed the progressive lock system.

5.3 PIN account

A PIN-enabled account uses the inventory GUI instead of /login. Digits submit automatically at the configured length. The password hash remains stored, so disabling PIN globally restores password login. PIN never bypasses 2FA.

5.4 Authenticated state

After authentication, movement and interaction restrictions are removed, the last location may be restored, the proxy is notified, and Redis authentication/session state is published when configured.

5.5 Protection before login

Before successful authentication PureAuth restricts movement, world and inventory interaction, drops, damage and normal chat. Login/Register/2FA/recovery flows remain available as required by their state.

6. Player commands

Command Who/when Exact purpose
/register <pass> <pass> Unregistered player Creates an account when CAPTCHA is disabled.
/register <pass> <pass> <captcha> Unregistered player Creates an account when CAPTCHA is enabled.
/login <pass> Registered password account Verifies the password. PIN accounts must use the GUI.
/changepass <old> <new> <new> Logged-in password account Verifies the old password and saves the new BCrypt hash.
/changepass Logged-in PIN account Opens the PIN change sequence: current PIN, new PIN, confirmation.
/setpin Logged-in player Opens the new-PIN and confirmation sequence.
/rempin Logged-in player with PIN Removes PIN login and returns the account to password login.
/premium Logged-in player Verifies the name against Mojang and enables same-IP Premium Auto-Login.
/cracked Logged-in Premium-mode player Disables Premium Auto-Login.
/2fa setup Logged-in player Generates a TOTP secret, asks for a current code, then creates one-use backup codes.
/2fa remove Logged-in 2FA player Requires a current authenticator code and disables 2FA. Admin Guard may require it again.
/2fa recovery <code> Login 2FA stage Consumes one backup code, disables 2FA and invalidates the remaining old codes.
/recovery setup Logged-in player Selects a recovery question and stores a hash of the answer.
/recovery remove Logged-in player Deletes recovery question and answer data.
/recovery start Logged-out registered player Starts question verification. Chat input is private to the recovery flow.
/recovery pass <new> <new> Verified recovery session Replaces the password, removes a forgotten PIN, ends recovery and logs in.

Player commands do not require Bukkit permissions in 6.3.0; their account/login state is the authorization boundary.

7. PIN authentication

/setpin requires authentication and an enabled PIN feature. The player clicks number heads; closing the window cancels setup/change. Closing the required login PIN window halts that login for safety, and the player reconnects or uses configured recovery.

PIN length accepts 1–9 digits. PINs are hashed, not stored as plaintext. Administrators can set, change or remove a player's PIN with the admin commands described below. GUI names, lore, digit labels and status text are in the selected message file; materials, textures and sounds are in config.yml.

8. Two-factor authentication (2FA)

2FA is a second proof after the password or PIN. PureAuth uses time-based one-time passwords (TOTP), compatible with authenticator applications such as Google Authenticator, Aegis, 2FAS and similar apps.

Setup

  1. Log in normally.
  2. Run /2fa setup.
  3. Add the displayed secret key to the authenticator app.
  4. Type the current six-digit code in chat.
  5. Save the displayed backup codes outside Minecraft.

The secret is not active until the confirmation code succeeds. Each backup code is one-use. Successful backup recovery disables 2FA and invalidates every old backup code.

Login

After a correct password/PIN, type the current authenticator code in chat. This private input is intercepted by PureAuth. A wrong code counts toward the login-attempt policy.

Removal and lost device

Use /2fa remove and confirm with a current TOTP code. If the device is lost during login, use /2fa recovery <backup-code>. If no backup code remains, an administrator must use account recovery/admin procedures according to server policy; PureAuth intentionally has no silent 2FA bypass command.

9. Account recovery

Recovery is optional and controlled by settings.recovery.enabled.

Enabling recovery for an account

  1. Log in.
  2. Run /recovery setup.
  3. Type a displayed question number.
  4. Type the answer. The normalized answer is hashed before storage.

Recovering an account

  1. Join but do not log in.
  2. Run /recovery start.
  3. Answer the configured question in chat.
  4. After successful verification run /recovery pass <new-password> <new-password>.

Recovery sessions expire and are removed on disconnect. Type cancel during the question flow to cancel it. A successful password recovery removes the PIN so the forgotten PIN cannot keep the user locked out. Recovery questions are the recovery_questions list in both message files; keep the list order stable, because the database stores the selected zero-based index.

10. Progressive login locks and administrator unlock

settings.max_attempts controls wrong attempts per connection. Reaching it creates one persistent kick stage. Defaults:

Stage Result
1 30-minute temporary login lock
2 24-hour temporary login lock
3 Permanent account lock

Temporary locks survive restart. Titles, chat and actionbar countdowns are independently configurable. With reset_history_after_successful_login: false, a later successful login does not erase escalation history. /pureauth unlock <player> clears the permanent lock, temporary lock, kick history and Fair Play Guard persistent restriction.

11. Premium Auto-Login, sessions and CAPTCHA

Premium Auto-Login verifies that the name exists through Mojang's profile API. With require_same_ip: true, automatic login only occurs when the current IP equals the last trusted IP. It is convenience based on name/IP, not a replacement for secure proxy forwarding.

Sessions allow a recently authenticated UUID to reconnect for the configured time. In Redis mode the session expiry is shared between modules. PIN-required accounts still require the PIN GUI.

CAPTCHA adds a generated code to registration. length controls code length; characters is the allowed alphabet. An empty or overly small alphabet should not be used.

12. Redis network mode

What it protects

In a multi-proxy network, every proxy atomically tries to acquire a case-insensitive username lease before allowing login. Redis SET NX PX guarantees only one proxy owns that name at a time. The owning proxy refreshes the lease and releases it on disconnect. The TTL releases stale ownership after a crashed proxy. Owner-checked Lua scripts prevent one connection from refreshing or releasing another connection's lease.

Redis also shares authenticated UUID state and short session expiry. The proxy owns the network connection lease; backend Paper modules consume/publish auth and session state and do not acquire a second conflicting lease.

Setup

Set network.mode: REDIS on all modules, then configure identical host, port, credentials, database and key_prefix. Use a dedicated Redis ACL user, bind Redis to a private interface, require authentication, firewall it from players and never expose port 6379 publicly.

Failure policy

  • DENY (recommended) is fail-closed: new connections are rejected when Redis cannot prove the name is free.
  • ALLOW falls back to local-only operation during startup failure. It favors availability but cannot guarantee cross-proxy duplicate prevention.

connection_timeout_ms limits establishing a Redis connection. socket_timeout_ms limits an operation waiting for a reply. player_lock_ttl_seconds must be long enough to survive short pauses; proxies refresh around one-third of the TTL. authenticated_ttl_seconds controls shared authenticated-state lifetime.

Keys

All keys begin with key_prefix. Player names are normalized to lowercase. Do not let unrelated PureAuth networks share the same prefix unless they intentionally share online-name ownership and sessions.

13. Fair Play Guard

“Fair Play Guard” is natural English and describes an administrative fair-play inspection without claiming that the plugin itself detects cheats.

Configure the location

  1. Grant pureauth.admin.check.setup.
  2. Run /pureauth check setup.
  3. Stand at the exact center/location used for inspections.
  4. Run /pureauth check setup confirm.

The world, coordinates, yaw and pitch are serialized to settings.locations.fair_play_check. Do not hand-edit the serialized value unless you fully understand the format.

Start an inspection

Run /pureauth check <player>. By default the target must be online and authenticated. PureAuth records the original location, game mode and flight state, teleports the player to the inspection location, sets Adventure mode, disables flight, sends the title/instructions and starts reminders.

Default restrictions block item drops, inventory changes, block breaking/placing/interacting, commands and damage. Chat from the checked player is cancelled globally and delivered only to the inspecting administrator; console receives it when console started the check. If the player exceeds 50 blocks from the configured center, PureAuth teleports them back.

Clear a player

Run /pureauth check clear <player>. For an active online inspection, PureAuth removes restrictions, restores the configured game mode/location/flight state, sends the cleared title and notifies both parties. For an offline player it clears a persistent Fair Play Guard disconnect restriction. /pureauth unlock <player> is the broader alternative that clears all account locks too.

Disconnect during inspection

With lock_on_disconnect: true, disconnecting stores a persistent database restriction. A later pre-login is denied with the editable PureAuth appeal message. With disconnect_command.enabled: true, the configured console command also runs, with %player% and %uuid% replaced. Command execution and PureAuth's persistent lock are independent switches.

Administrator ban during inspection

When Paper reports a banned kick, the Bukkit name ban list contains the player, or a configured ban command is detected, PureAuth restores/removes its temporary inspection state and does not add its own disconnect restriction. Third-party ban commands must have their root added to ban_detection.command_prefixes. The list matches the command root and first target argument; it cannot infer an arbitrary plugin's custom syntax.

Reload and shutdown

/pureauth reload reschedules radius and reminder tasks using current intervals. On normal plugin shutdown, active players are restored and are not punished as inspection leavers.

14. Administrator commands

/pa is an alias for /pureauth.

Command Permission Behaviour
/pureauth none Displays version and author.
/pureauth reload pureauth.admin.reload Reloads config/messages and restarts backup, PIN and Fair Play task settings.
/pureauth stats pureauth.admin.stats Console-only account count and feature status.
/pureauth unlock <player> pureauth.admin.unlock Clears progressive, permanent and Fair Play locks; reconnects an online target safely.
/pureauth unregister <player> pureauth.admin.unregister Deletes the account and asks an online target to rejoin/register.
/pureauth register <player> <password> pureauth.admin.register Creates an offline/online player's account. Secret is redacted from audit logs.
/pureauth forcelogin <player> pureauth.admin.forcelogin Marks an online player authenticated. Use only after manual identity verification.
/pureauth info <player> pureauth.admin.info Displays stored UUID, IP, dates and security flags.
/pureauth setpassword <player> <password> pureauth.admin.setpassword Replaces the player's password hash. Secret is redacted from logs.
/pureauth accounts <ip> pureauth.admin.accounts Lists usernames recorded for the IP.
/pureauth location login pureauth.admin.location Stores the command sender's current login waiting location.
/pureauth location register pureauth.admin.location Stores the current registration waiting location.
/pureauth setpin <player> <pin> pureauth.admin.pin Enables the supplied valid numeric PIN. Secret is redacted from logs.
/pureauth changepin <player> <pin> pureauth.admin.pin Replaces an existing PIN. Secret is redacted.
/pureauth rempin <player> pureauth.admin.pin Removes the target PIN.
/pureauth check <player> pureauth.admin.check.start Starts Fair Play Guard.
/pureauth check setup pureauth.admin.check.setup Starts location setup. Player-only.
/pureauth check setup confirm pureauth.admin.check.setup Saves the administrator's current position. Player-only.
/pureauth check clear <player> pureauth.admin.check.clear Clears an active inspection or persistent Fair Play restriction.

With settings.safe_mode: true, sensitive administrative mutations are console-only. Tab completion filters entries by permission.

15. Permissions

Permission Default Meaning
pureauth.admin op Parent granting every admin permission below except Admin Guard.
pureauth.admin.reload op Reload configuration/messages.
pureauth.admin.stats op View console statistics.
pureauth.admin.unlock op Unlock accounts.
pureauth.admin.unregister op Delete accounts.
pureauth.admin.register op Create accounts.
pureauth.admin.forcelogin op Force online authentication.
pureauth.admin.info op Read account information.
pureauth.admin.setpassword op Replace passwords.
pureauth.admin.accounts op Query accounts by IP.
pureauth.admin.location op Set login/register locations.
pureauth.admin.pin op Administer PINs.
pureauth.admin.guard false Marks the holder as an administrator who must enable 2FA. It is a policy marker, not command access.
pureauth.admin.check op Parent for all three Fair Play permissions.
pureauth.admin.check.start op Start inspections.
pureauth.admin.check.setup op Set inspection location.
pureauth.admin.check.clear op Clear active/persistent inspection restrictions.

For least privilege, grant individual permissions instead of pureauth.admin.

16. Complete Paper configuration reference

Database and connection pool

Path Default Purpose
database.type SQLITE SQLITE for one backend or MYSQL for network/shared storage.
database.pool.maximum_pool_size -1 Auto size; explicitly use 1 for SQLite or a measured 16–32 range for MySQL.
database.pool.minimum_idle -1 Auto idle connection count.
database.pool.connection_timeout_ms 10000 Maximum pool wait for a DB connection.
database.pool.idle_timeout_ms 600000 Time before excess idle DB connections may close.
database.pool.max_lifetime_ms 1800000 Maximum pooled connection age. Keep below DB/server limits.
database.mysql.host localhost MySQL/MariaDB hostname.
database.mysql.port 3306 Database TCP port.
database.mysql.database minecraft Schema name.
database.mysql.username root DB user; create a restricted production user instead.
database.mysql.password password DB password. Protect file permissions.
database.mysql.table_prefix pureauth_ Letters, numbers and underscore only; identical on a shared network.

Async performance

Path Default Purpose
performance.async.database_threads 8 Bounded database worker count.
performance.async.crypto_threads 4 BCrypt/TOTP-related worker count.
performance.async.network_threads 4 Mojang/Redis/network worker count.
performance.async.queue_size 512 Maximum queued work per bounded executor before safe rejection/backpressure.

Network/Redis

Path Default Purpose
network.mode LOCAL LOCAL for a single entry proxy/server; REDIS for multi-proxy coordination.
network.redis.host localhost Redis hostname/private IP.
network.redis.port 6379 Redis port.
network.redis.username empty ACL username; empty uses default user.
network.redis.password empty Redis/ACL password.
network.redis.database 0 Logical Redis database index.
network.redis.key_prefix pureauth: Namespace; a trailing colon is normalized automatically.
network.redis.connection_timeout_ms 2000 Connect timeout.
network.redis.socket_timeout_ms 2000 Read/write response timeout.
network.redis.player_lock_ttl_seconds 45 Username lease TTL; values below 10 are normalized to 10.
network.redis.authenticated_ttl_seconds 600 Shared authenticated UUID TTL.
network.redis.failure_policy DENY DENY fail-closed or ALLOW local fallback.

General, PIN and GUI

Path Default Purpose
settings.safe_mode false Makes sensitive admin changes console-only.
settings.language EN Selects EN_en.txt; PL selects PL_pl.txt. Reload after changing.
settings.blindness_effect true Applies the pre-authentication visual effect.
settings.premium_login.enabled true Enables /premium and automatic Premium login.
settings.premium_login.require_same_ip true Requires the last trusted IP.
settings.pin.enabled true Enables PIN setup and PIN login.
settings.pin.length 6 Required PIN digits, supported 1–9; invalid values fail safely to 6.
settings.pin.gui.digit_material PLAYER_HEAD Fallback digit item material.
settings.pin.gui.filler.material GRAY_STAINED_GLASS_PANE Empty GUI filler.
settings.pin.gui.input.filled.material LIME_STAINED_GLASS_PANE Filled PIN position.
settings.pin.gui.input.empty.material BLACK_STAINED_GLASS_PANE Empty PIN position.
settings.pin.gui.status_material NETHER_STAR Status/help item.
settings.pin.gui.controls.backspace.material ARROW Backspace item.
settings.pin.gui.controls.backspace.texture empty Optional trusted Base64 Minecraft texture; empty uses material.
settings.pin.gui.controls.clear.material BARRIER Clear item.
settings.pin.gui.controls.clear.texture empty Optional Base64 texture.
settings.pin.gui.digits.0.texture, settings.pin.gui.digits.1.texture, settings.pin.gui.digits.2.texture, settings.pin.gui.digits.3.texture, settings.pin.gui.digits.4.texture, settings.pin.gui.digits.5.texture, settings.pin.gui.digits.6.texture, settings.pin.gui.digits.7.texture, settings.pin.gui.digits.8.texture, settings.pin.gui.digits.9.texture bundled values Base64 textures.minecraft.net player-head texture for each digit. Invalid/untrusted URLs fail closed to material.
settings.pin.gui.sounds.enabled true Master GUI sound switch.
settings.pin.gui.sounds.open minecraft:block.ender_chest.open GUI opening sound key.
settings.pin.gui.sounds.click minecraft:ui.button.click Digit/control click sound.
settings.pin.gui.sounds.step minecraft:block.note_block.pling PIN-stage transition sound.
settings.pin.gui.sounds.success minecraft:entity.player.levelup Successful PIN sound.
settings.pin.gui.sounds.error minecraft:entity.villager.no Invalid PIN/error sound.

Backup, recovery and Discord

Path Default Purpose
settings.backup.enabled true Starts scheduled backup/export.
settings.backup.interval_hours 24 Time between backups.
settings.backup.max_backups 10 Retained rotating backups.
settings.recovery.enabled true Enables account recovery commands/flow.
settings.discord.enabled false Master Discord webhook switch.
settings.discord.webhook_url placeholder Discord webhook URL; keep it secret.
settings.discord.events.server_lifecycle true Start/stop reports.
settings.discord.events.user_login false Successful login reports.
settings.discord.events.user_register true Registrations.
settings.discord.events.user_changepass true Password changes.
settings.discord.events.user_premium_toggle true Premium/cracked toggles.
settings.discord.events.failed_attempts true Failed credential reports.
settings.discord.events.account_locked true Account-lock reports.
settings.discord.events.admin_usage true Ordinary admin action reports.
settings.discord.events.admin_sensitive true Sensitive account mutation reports.

Security, limits, sessions and Admin Guard

Path Default Purpose
settings.security.account_lock_enabled true Master persistent lock policy.
settings.security.kicks_before_lock 3 Kick stage at which permanent lock occurs.
settings.security.progressive_lock.enabled true Enables temporary stages before permanent lock.
settings.security.progressive_lock.first_lock_seconds 1800 First stage (30 minutes).
settings.security.progressive_lock.second_lock_seconds 86400 Second stage (24 hours).
settings.security.progressive_lock.reset_history_after_successful_login false When true, successful auth clears escalation history.
settings.security.progressive_lock.reminder_interval_seconds 10 Lock status refresh/reminder interval.
settings.security.progressive_lock.display.title true Show lock title.
settings.security.progressive_lock.display.chat true Show lock chat messages.
settings.security.progressive_lock.display.actionbar true Show actionbar countdown.
settings.captcha.enabled true Adds CAPTCHA to registration.
settings.captcha.length 5 Generated code length.
settings.captcha.characters A-Z0-9 Source alphabet exactly as configured.
settings.login_timeout 60 Seconds to complete login before kick.
settings.max_attempts 3 Bad credentials allowed per connection.
settings.min_password_length 4 Minimum password characters; production should use a stronger value.
settings.max_accounts_per_ip 3 Registration limit per recorded IP.
settings.sessions.enabled true Enables reconnect sessions.
settings.sessions.time_minutes 1 Session lifetime.
settings.admin_guard.enabled true Requires 2FA for holders of pureauth.admin.guard.

Fair Play Guard

Path Default Purpose
settings.fair_play_guard.enabled true Master switch.
settings.fair_play_guard.require_authenticated true Target must finish PureAuth login first.
settings.fair_play_guard.teleport_to_check_location true Teleport to configured inspection point.
settings.fair_play_guard.force_adventure_mode true Change target to Adventure during inspection.
settings.fair_play_guard.block_item_drops true Cancel item drops.
settings.fair_play_guard.block_inventory_changes true Cancel inventory clicks.
settings.fair_play_guard.block_world_interaction true Cancel break/place/interact.
settings.fair_play_guard.block_commands true Cancel player commands.
settings.fair_play_guard.prevent_damage true Cancel damage to the checked player.
settings.fair_play_guard.private_chat true Send checked-player chat only to inspector/console.
settings.fair_play_guard.lock_on_disconnect true Store persistent restriction after logout/kick not recognized as a ban.
settings.fair_play_guard.restore_previous_location true Return to pre-check location on clear/ban/shutdown.
settings.fair_play_guard.restore_survival_mode true Restore Survival specifically; false restores original game mode.
settings.fair_play_guard.discord_invite discord.gg/yourserver %discord% used in reminders.
settings.fair_play_guard.radius.enabled true Enforce inspection radius.
settings.fair_play_guard.radius.max_distance 50.0 Maximum 3D distance in blocks. Other worlds count as outside.
settings.fair_play_guard.radius.check_interval_ticks 20 Radius check period; minimum runtime value is 1 tick.
settings.fair_play_guard.reminders.enabled true Repeated Discord/waiting-area instruction.
settings.fair_play_guard.reminders.interval_seconds 10 Reminder period; minimum runtime value is 1 second.
settings.fair_play_guard.disconnect_command.enabled false Run optional console command on inspection disconnect.
settings.fair_play_guard.disconnect_command.command example ban Command without leading slash; supports %player%, %uuid%. Blank/invalid commands are ignored.
settings.fair_play_guard.ban_detection.command_prefixes common ban roots Command roots that identify an admin ban and suppress PureAuth disconnect punishment.

Remaining settings and generated locations

Path Default Purpose
settings.update_checker true Checks the configured release source and notifies about newer semantic versions.
settings.message_interval 10 Seconds between login/register reminders.
settings.locations.spawn_login empty Serialized login waiting location; set with admin command.
settings.locations.spawn_register empty Serialized registration waiting location.
settings.locations.fair_play_check empty Serialized Fair Play Guard location.

17. BungeeCord and Velocity configuration

Both proxy configs contain the same database pool, language and Redis meanings documented above. Bungee uses database.type plus nested database.mysql.*; Velocity uses database.driver and flat host, port, database, username, password, prefix. Production proxy networks must use MYSQL and identical credentials/table prefix. settings.language selects the proxy duplicate/unavailable kick file. All network.redis.* fields have the same meaning and defaults as Paper.

18. Messages and notifications

PureAuth creates:

plugins/PureAuth/Messages/EN_en.txt
plugins/PureAuth/Messages/PL_pl.txt

Despite the .txt extension these files use YAML. Keep quotes around values containing :, #, brackets or leading spaces. Use \n for a new line. Legacy & colors and &#RRGGBB hex colors are supported. Change prefix to rebrand every response that uses it. Run /pureauth reload after editing.

The config contains operational values only; all player/admin chat, title, subtitle, actionbar, GUI label/lore and kick text is in these message files. Lists such as recovery_questions and GUI lore must remain YAML lists.

Placeholders

Placeholder Used for
%player% Target/player name
%admin% Inspector/administrator name
%message% Private Fair Play chat text
%discord% Fair Play Discord invite
%reason% Stored Fair Play reason where applicable
%time% Seconds or formatted remaining lock time, depending on key
%code% CAPTCHA or generated recovery content depending on key
%key% TOTP secret
%codes% 2FA backup-code block
%question%, %number% Recovery question/list entry
%length% Required password/PIN length
%attempts%, %max% Failed attempts and limit
%current%, %new% Update versions
%version%, %count%, %value% Admin/version/stat output
%accounts% Account list
%uuid%, %ip%, %last_login%, %registered%, %premium%, %pin_enabled%, %locked%, %temporary_lock_until%, %failed_login_kicks%, %recovery_set%, %2fa_enabled% /pureauth info template

Do not remove a placeholder unless you intentionally do not want that value displayed. Unknown placeholders are printed literally.

Complete message-key index

Authentication/join/locks: prefix, join_title, join_subtitle_register, join_subtitle_login, actionbar_timer, captcha_message, reminder_register, reminder_login, title_locked, subtitle_locked, error_locked_chat, temporary_lock_title, temporary_lock_subtitle, temporary_lock_chat, temporary_lock_actionbar, temporary_lock_kick, temporary_lock_expired, permanent_lock_kick, lock_database_error_kick, success_register, success_login, success_premium_login, success_session, password_changed, title_success_register, subtitle_success_register, title_success_login, subtitle_success_login, title_success_premium_login, subtitle_success_premium_login, title_success_session, subtitle_success_session.

PIN and GUI: pin_login_open, pin_login_reminder, pin_setup_open, pin_change_open, pin_confirm_prompt, pin_mismatch, pin_current_success, pin_current_wrong, pin_login_success, pin_saved, pin_removed, pin_not_set, pin_already_set, pin_disabled, pin_invalid, pin_database_error, database_error, pin_gui_cancelled, pin_command_no_args, pin_login_command_blocked, pin_changepass_gui_only, pin_admin_changed_notice, pin_admin_rejoin, pin_halted_title, pin_halted_subtitle, pin_halted_subtitle_recovery, pin_halted_chat, pin_halted_chat_recovery, pin_gui_title, pin_gui_filler_name, pin_gui_input_filled_name, pin_gui_input_empty_name, pin_gui_status_login, pin_gui_status_setup_new, pin_gui_status_setup_confirm, pin_gui_status_change_current, pin_gui_status_change_new, pin_gui_status_change_confirm, pin_gui_status_complete, pin_gui_status_lore, pin_gui_control_backspace_name, pin_gui_control_backspace_lore, pin_gui_control_clear_name, pin_gui_control_clear_lore, pin_gui_digit_0_name, pin_gui_digit_0_lore, pin_gui_digit_1_name, pin_gui_digit_1_lore, pin_gui_digit_2_name, pin_gui_digit_2_lore, pin_gui_digit_3_name, pin_gui_digit_3_lore, pin_gui_digit_4_name, pin_gui_digit_4_lore, pin_gui_digit_5_name, pin_gui_digit_5_lore, pin_gui_digit_6_name, pin_gui_digit_6_lore, pin_gui_digit_7_name, pin_gui_digit_7_lore, pin_gui_digit_8_name, pin_gui_digit_8_lore, pin_gui_digit_9_name, pin_gui_digit_9_lore.

2FA: 2fa_usage, 2fa_title, 2fa_subtitle_setup, 2fa_subtitle_login, 2fa_setup_start, 2fa_key_msg, 2fa_enter_code, 2fa_setup_success, 2fa_setup_fail, 2fa_login_req, 2fa_removed, 2fa_verify_remove, 2fa_not_enabled, 2fa_already, title_success_2fa, subtitle_success_2fa, success_2fa_verify, 2fa_backup_codes_msg, 2fa_recovery_usage, 2fa_recovery_success, 2fa_recovery_fail.

Recovery: recovery_questions, recovery_setup_usage, recovery_remove_success, recovery_question_list, recovery_question_format, recovery_answer_prompt, recovery_setup_success, recovery_start_usage, recovery_verify_success, recovery_pass_usage, recovery_pass_changed, recovery_pin_removed, recovery_database_error, recovery_not_set, recovery_already_setup, recovery_fail, recovery_session_expired, recovery_cancelled, recovery_disabled, recovery_invalid_number, recovery_number_required, recovery_question_config_error, recovery_verification_required.

Premium, network and errors: sync_success, update_available, update_download, premium_enabled, premium_disabled, premium_fail_api, premium_already, premium_not_enabled, premium_ip_changed, premium_disabled_admin, premium_api_error, error_already_online, error_wrong_pass, error_usage_login, error_usage_changepass, error_vpn_kick, error_wrong_captcha, error_usage_captcha, error_usage_reg, error_kick_attempts, error_kick_timeout, error_already_logged, error_not_logged, error_match_pass, error_length_pass, error_already_reg, error_not_reg, error_wrong_old, error_max_ip, error_launcher_mismatch, online_mode_fail_safe_kick, network_duplicate_kick, network_unavailable_kick.

Admin/Admin Guard: admin_guard_title, admin_guard_subtitle, admin_guard_chat, admin_guard_forced_setup, admin_guard_remove_warning, admin_reload, admin_unregister, admin_loc_set, admin_pass_set, admin_force_login, admin_unlock, admin_register_success, admin_register_fail, admin_console_only, admin_safe_mode, admin_player_not_found, admin_unknown_command, admin_help, admin_pin_set, admin_pin_changed, admin_pin_removed, admin_pin_already_set, admin_pin_not_set, admin_no_perm, admin_players_only, admin_invalid_type, admin_offline, admin_header_border, admin_info_header, admin_info_body, admin_accounts, admin_version, admin_created_by, admin_stats_title, admin_stats_users, admin_stats_safe_mode, admin_stats_discord, admin_stats_backup, admin_unlock_kick, admin_unregister_kick, location_login_name, location_register_name, admin_usage_unlock, admin_usage_unregister, admin_usage_register, admin_usage_forcelogin, admin_usage_info, admin_usage_setpassword, admin_usage_accounts, admin_usage_location, admin_usage_setpin, admin_usage_changepin, admin_usage_rempin.

Fair Play Guard: fair_play_disabled, fair_play_setup_start, fair_play_setup_title, fair_play_setup_subtitle, fair_play_setup_not_started, fair_play_setup_saved, fair_play_location_missing, fair_play_usage, fair_play_target_offline, fair_play_target_not_authenticated, fair_play_already_checked, fair_play_started_admin, fair_play_started_player, fair_play_title, fair_play_subtitle, fair_play_reminder, fair_play_private_chat_format, fair_play_command_blocked, fair_play_returned_to_area, fair_play_clear_not_found, fair_play_cleared_admin, fair_play_cleared_player, fair_play_clear_title, fair_play_clear_subtitle, fair_play_disconnect_reason, fair_play_disconnect_locked, fair_play_lock_kick, fair_play_database_error, fair_play_ban_cleanup.

19. Backups, logs, webhooks and placeholders

SQLite backups copy the local database; MySQL mode exports plugin-owned data according to the implementation. Rotation retains max_backups. Always also maintain infrastructure-level encrypted backups and test restores.

Administrative commands are written to PureAuth logs; password/PIN arguments for register, setpassword, setpin and changepin are replaced with [REDACTED]. Discord event switches only apply when the master switch is true and the webhook URL is valid. Treat webhook URLs as secrets.

PlaceholderAPI is optional (softdepend). PureAuth loads without it. Proxy plugin messages use pureauth:sync; do not block that channel between the proxy and backends.

20. Troubleshooting

“Username already connected” but nobody appears online

Wait at least player_lock_ttl_seconds. If it persists, confirm all proxies use synchronized system time, the same prefix, and can refresh/release Redis keys. Do not manually delete keys while a proxy may still own them.

Redis unavailable

Check private routing, ACL username/password, database index, TLS/network policy if externally provided, and both timeouts. Under DENY, rejection is expected and protects against duplicates. Under ALLOW, the console states that protection has fallen back locally.

Fair Play player was locked after an admin ban

Add the third-party ban command root to ban_detection.command_prefixes. Prefer commands in ban Player Reason form. Paper-native banned kick causes and the built-in name ban list are also detected.

Fair Play location missing

Run setup and confirm as a player in a loaded world. If the world was renamed/deleted, set the point again.

Messages did not change

Edit the language file selected by settings.language, validate YAML quotes/lists, then /pureauth reload. On a proxy, restart after changing proxy resource/config files if its platform does not expose a reload lifecycle.

Player cannot use recovery

Confirm recovery is enabled, the account has a selected question, the player is not already logged in, and the saved question index still exists in the same position in recovery_questions.

Paper refuses every player

Protected backend online-mode must be false. On a proxy network verify forwarding/firewall configuration instead of changing PureAuth's fail-safe message.

Database startup failure

Verify type/driver spelling, credentials, schema permissions, prefix characters and pool timeouts. Do not treat a proxy SQLite warning as a production network configuration; use MySQL/MariaDB.

21. Production security checklist

  • Firewall offline-mode backends from the public Internet.
  • Use MySQL/MariaDB for a network and a least-privilege database user.
  • Use Redis ACL authentication, a private bind/firewall and failure_policy: DENY.
  • Use a unique Redis key prefix per independent network.
  • Keep require_same_ip, account locks and Admin Guard enabled unless policy requires otherwise.
  • Grant individual admin permissions and reserve pureauth.admin for trusted operators.
  • Set strong password length and protect config, database, logs, backups and webhook URLs.
  • Test /pureauth unlock, recovery, 2FA recovery and Fair Play appeals before production incidents.
  • Keep Paper/Purpur, proxy and Java patched, and replace all PureAuth modules together.
  • Retain off-host encrypted backups and perform restore drills.

22. Operational acceptance checklist

After installation or upgrade verify:

  1. plugin enables and disables cleanly;
  2. register/login/CAPTCHA work;
  3. PIN setup, login, change, remove and GUI-close safety work;
  4. 2FA setup, login, removal and one-use recovery code work;
  5. account recovery works and removes a forgotten PIN;
  6. progressive temporary/permanent locks and /pureauth unlock work;
  7. proxy switching preserves authentication;
  8. two proxies cannot accept the same nickname simultaneously in Redis mode;
  9. Redis outage produces the selected failure policy;
  10. Fair Play setup/start/private chat/radius/restrictions/clear/logout lock/appeal unlock/admin-ban cleanup work;
  11. EN and PL message reloads work;
  12. scheduled backup and webhook policy match expectations.

YooUUU rEAllY reAd thiiisS??

Clone this wiki locally