Offline Login Mod

Provides authentication for NeoForge 1.21.1 offline-mode servers.

This mod has a direct goal:

• Offline players can register a password and log in.
• Premium players can complete Mojang online validation on an offline-mode server.
• Offline players cannot move, interact, chat, or view their real inventory until authentication is complete.

Main Features

1. Offline Player Registration and Password Login

• Unregistered offline players can use register <password> <confirmPassword> on first join.
• Registered offline players can use login <password>.
• Players who are already in-game can use auth changepassword <password> <confirmPassword> to change their offline password.

2. Premium Account Validation

• When a player connects, the mod actively starts premium handshake and Mojang session validation during the login phase.
• If validation succeeds, the player continues login as a premium account, with the experience consistent with a premium server.
• After a successful premium login, the player uses the premium UUID instead of the offline-mode server-generated UUID, ensuring that mods depending on premium UUIDs (e.g., Figura) work correctly.

3. Known Player List Management

• Every successful login (premium or offline) is recorded in the known player list, including UUID, username, and login mode.
• On the next login, the player is routed directly according to their known mode, skipping the Mojang pre-check to avoid hitting API rate limits.
• Administrators can use auth setmode <UUID|username> <online|offline> to manually specify a player's login mode.
• If a player is in the list and marked as ONLINE, but premium validation fails, they are rejected immediately.
• Administrators can use auth remove <UUID|username> to completely remove all stored data for a player (known player list, offline password, login blocks, and passwordless login records). The player will return to a first-login state on next join.

4. Passwordless Login Window

• After a registered offline player logs in successfully, the mod records a trusted login entry for that account UUID and IP.
• Within the configured time window, the same UUID logging in again from the same IP can skip password entry.
• If the same IP is associated with multiple UUIDs during that window, those UUIDs lose passwordless eligibility and fall back to normal password login.

5. Isolation Before Authentication

Before an offline player completes registration or login, the mod places the player into a pending-auth state. In that state, the mod:

• Switches the player to spectator mode.
• Locks the player's position and continuously applies blindness.
• Sends an empty inventory view to hide the real inventory.
• Blocks chat, attacks, block interaction, container access, item dropping, and other gameplay actions.
• Allows only the register and login authentication commands.

6. Configurable Security Policies

• Maximum password retry count.
• Temporary block duration.
• Login timeout.
• Repeated prompt interval.
• Minimum password length.
• Password blacklist (auto-created on first startup, directly editable).
• Mojang network request timeouts.
• Default language and automatic player-language detection.

Configuration

Config File Location

• The server config file is named auth-server.toml.
• NeoForge loads this file as a SERVER config.
• For a world-specific override, use world/serverconfig/auth-server.toml.
• After changing the config, restarting the server is recommended so that the new authentication parameters are fully applied on the next startup.

Default Configuration

[database]
path = "auth/auth"

[offline_login]
max_login_attempts = 3
temporary_block_minutes = 5
trusted_login_window_hours = 24
login_timeout_minutes = 5
prompt_interval_seconds = 5
bcrypt_cost = 12
min_password_length = 1
max_password_length = 72
password_blacklist_path = "auth/password_blacklist.txt"

[online_validation]
connect_timeout_seconds = 10
request_timeout_seconds = 10
pending_handshake_ttl_seconds = 120

[localization]
default_language = "en_us"
auto_detect_player_language = true

Key Configuration Options

Additional notes:

• The player's language cannot be determined reliably before login, so that phase always uses localization.default_language.
• Offline player UUIDs are forced to be generated by the server based on the username (hash of OfflinePlayer:<username>), ensuring the same UUID for the same user on every login.
• Changing an offline password, or resetting one through an administrator action, clears previous trusted-login records.

Commands

Regular Player Commands

Administrator Commands

Environment

• NeoForge
• Minecraft 1.21.1