LibreLogin Documentation

LibreLogin (formerly LibrePremium) is an open-source, multiplatform authentication plugin designed for high customizability. Key features include:

• AutoLogin: Automatically logs in premium players.
• TOTP 2FA: Supports Time-based One-Time Passwords via apps like Authy or Google Authenticator.
• Session System: Manages player sessions.
• Name Validation: Includes case sensitivity checks.
• Data Migration: Provides automatic migration for premium players and a single-command migration for player data.
• Geyser/Bedrock Support: Compatible with Bedrock players via Floodgate.

Requirements

• Java: Requires Java 17 or newer.

Security Considerations

• Proxy Usage: If you are running LibreLogin on a proxy (such as Velocity or BungeeCord), you must ensure your limbo server is properly secured.

LibreLogin implements rate limiting on commands to prevent abuse.

• Throttling: Commands are subject to a rate limiter (defaulting to 1 attempt per second). If a user exceeds this, they will receive an error-throttle message.
• Error Handling: The plugin uses a custom exception handler. If a command results in an InvalidCommandArgument exception, the plugin catches it and sends the specific error message (e.g., syntax errors or invalid arguments) directly to the user's audience. Unexpected exceptions are logged to the server console with a stack trace.

The /librelogin dump command creates a detailed JSON diagnostic file in the plugin's dumps/ folder. This file is useful for debugging and includes:

• Plugin version and timestamp
• Proxy data (plugin list, server list, limbo/lobby information)
• A full thread dump including thread IDs, names, states, priorities, and stack traces.

Files are named using the pattern dump-dd-MM-yyyy_HH-mm-ss.json.

LibreLogin is compatible with the following platforms:

• Velocity
• BungeeCord
• Paper

The confirmpasswordreset command allows a user to finalize a password reset process using a provided token and a new password. This command validates the token against the current password reset cache and ensures the new password matches the repetition input.

Usage Syntax: confirmpasswordreset <token> <password> <passwordRepeat>

Requirements for success:

1. The <token> must match the token currently stored in the password reset cache for the user.
2. The <password> and <passwordRepeat> arguments must be identical.

Upon successful execution, the user's password is updated in the database, the reset cache is invalidated for that user, and a password change event is fired.

Commands for managing the plugin's internal state and configuration.

# Reload the main configuration file
/librelogin reload configuration

# Reload the messages/localization files
/librelogin reload messages

# Test the email handler by sending a test mail to an address
/librelogin email test <email>

# Get plugin version information
/librelogin about

# Generate a system diagnostic dump
/librelogin dump

The librelogin command is the primary entrypoint for staff administration. It provides subcommands for managing user accounts, system configuration, and diagnostic data. Most administrative subcommands require specific permissions (e.g., librelogin.dump, librepremium.user.info).

/librelogin <subcommand>

Use the password change command to update a user's password. This command requires the current password and a new password. It validates the old password against the stored hash before updating the database and firing a password change event.

Aliases:

• changepassword
• changepass
• passwd
• passch

Syntax: {@@syntax.change-password} (Refer to your specific localization files for the exact string format, typically <old_password> <new_password>)

Errors:

• If the user is not registered, it returns the error: error-no-password.
• If the old password does not match, it returns the error: error-password-wrong and fires an AuthenticWrongPasswordEvent with AuthenticationSource.CHANGE_PASSWORD.

Use the /2faconfirm <code >confirm command to complete the two-factor authentication (2FA) process. This command expects a numeric code (such as a TOTP code) as an argument. The command handles spaces within the code automatically by stripping them before parsing.

Requirements:

• The player must be currently in a state of awaiting 2FA verification.
• The provided code must be a valid integer.

If the confirmation is successful, the player will be kicked from the server with a message indicating that 2FA is enabled (typically used to force a re-login or to finalize the authentication state).