alomcAuth

A Spigot/Paper authentication plugin for Minecraft 1.21 servers running in offline mode. Players cannot move, chat, or run commands until they prove they own an e-mail address in a whitelisted domain - built for a university server where only students of a given faculty were allowed in.

How it works

1. On join, the player is frozen in spectator mode and told to /register <email> or /login <password>.
2. /register accepts only addresses in the configured domain (e.g. @example.com), rejects addresses already bound to another account, and mails a one-time code over SMTP.
3. /confirm <code> <password> verifies the code and creates the account.
4. On successful /login the player is released into survival gameplay.

Until a player is authenticated the plugin cancels movement, chat, commands (except the auth ones), spectator teleports, and hides configured chat prefixes (e.g. staff chat) at the packet level via ProtocolLib - so a joining client cannot spy on the server while sitting at the login prompt.

Features

• E-mail domain gate - registration restricted to one mail domain, one account per address.
• One-time codes - random, configurable range, with expiry and a re-request cooldown.
• Salted SHA-256 password hashing with a per-user random salt (SecureRandom).
• Pluggable storage - JSON or SQLite, selected in config via a small factory (Storage interface).
• Packet-level pre-auth isolation - ProtocolLib listeners on SYSTEM_CHAT and CAMERA.
• CSV audit log - joins, disconnects, registrations, and failures written to a timestamped file per server start.
• Self-updating config - missing keys from the bundled default config.yml are merged into the existing one on startup.
• Admin commands - manual registration, unregistering, and clearing a stuck one-time code.

Commands

Command	Description
/register <email>	Request a one-time code by e-mail
/confirm <code> <new_password>	Confirm the code and set a password
/login <password> (/l)	Log in
/changepassword <old> <new>	Change password
/authhelp	List player commands
/manualregister <player> <password> <email>	Register a player by hand (admin)
/unregister <player>	Remove a player from the database (admin)
/deleteotc <player>	Delete a player's pending one-time code (admin)
/authhelpadmin	List admin commands (admin)

Admin commands require the alomcauth.admin.manualregister permission.

Configuration

config.yml (created on first start):

email:
  address: ""        # SMTP account used to send codes
  password: ""
  smtpHost: ""
  smtpPort: 587
validator:
  maildomain: "@example.com"
verification:
  code:
    min: 100000
    max: 999999
    expiration: 15   # minutes
    confirmcooldown: 30
  password:
    passwordSaltLength: 16
database:
  type: json         # json or sqlite
  file: registered-players.json
preauth:
  hidden_prefixes:
    - staffchat      # chat messages hidden from unauthenticated players

Build & install

Requires JDK 8+ and Maven.

mvn clean package

Drop the shaded jar from target/ into your server's plugins/ directory alongside ProtocolLib, start the server once, fill in the SMTP details in plugins/alomcAuth/config.yml, and restart.

Tech

Java 8 · Spigot API 1.21 · ProtocolLib 5 · JavaMail · Gson · JDBC/SQLite · Maven Shade

Notes

Built for the alo-mc server. The /spawn command that used to live here has moved to mc-utilsplugin.