Gatehouse

Password login for offline-mode NeoForge 1.21.1 servers, with a login screen instead of chat commands.

With online-mode=false, anyone can join with any name, including yours or an operator's. Gatehouse ties each name to a password. The first player to join with a name claims it by choosing one; from then on, that name only gets in with that password.

Installation

Install the mod on the server. Players do not need it: without it, they log in with /register and /login, and the server reminds them what to type in chat and as an on-screen title. Players who also install it on their client get the login screen.

By default the server only asks for a password when online-mode=false, since Mojang already verifies players otherwise. Set requireLogin = "ALWAYS" to ask on every server.

The login screen

• It covers the whole screen, so nobody sees where their character stands before logging in.
• Registering asks for the password twice, with a button to show it while typing.
• It shows the time left to log in and, after a wrong password, how many attempts remain.
• Esc does not close it. A Disconnect button leaves the server.

Until a player logs in

They can look around but cannot move or change dimension. They cannot chat or run commands other than /register and /login, break or place blocks, use items, open containers, attack, or drop or pick up items. They take no damage and mobs ignore them. If they do not log in within the time limit (90 seconds by default), they are kicked.

Wrong passwords

Wrong passwords are counted per IP address, so leaving and joining again does not reset the count. After 5 (configurable), the address is kicked and cannot join again for 10 minutes (configurable, or 0 to only kick). Online operators get a chat message when it happens. A correct password clears the count.

Security

• Passwords are stored as PBKDF2-HMAC-SHA256 hashes, 600,000 iterations by default, with a random salt per account, in <world>/gatehouse/accounts.json. The file never contains a password.
• Offline-mode connections are not encrypted. With the mod installed, the client hashes the password itself and logs in by answering a one-time challenge, so the password is never sent as typed and a captured login cannot be replayed.
• Someone joining with the name of a logged-in player is refused. Vanilla would kick the player who was already playing.
• Names are case-insensitive: if Steve is registered, nobody can join as steve.
• Hashing runs on its own thread, so logins do not stall the server.

Commands

Configuration

serverconfig/gatehouse-server.toml in the world folder:

Known limitations

• Registering, and /login typed in chat by players without the mod, still cross the unencrypted connection. Someone who can read the traffic between player and server can capture them.
• Players behind the same IP (a house, a school, a VPN) share the wrong-password count and the lockout, and can take over each other's session if sessionMinutes is on.
• Lockouts are kept in memory and end when the server restarts.
• Server messages and kick reasons are in English. The login screen is in English and Spanish.