# MaanAuth 🔒 The modern, secure authentication plugin for Paper & Spigot 1.21.x Built from scratch with a focus on security, performance, and a polished player experience. --- ## 🔐 Security - 🛡️ Argon2id password hashing — the current gold standard. BCrypt supported as a legacy fallback for migrated accounts. SHA1/MD5/SHA256 are intentionally not supported anywhere. - 🔑 Two-Factor Authentication (TOTP) — fully RFC 6238 compliant, works with Google Authenticator, Authy, and any standard TOTP app. No external dependency, implemented from scratch. - ⚔️ Brute-force protection — progressive login delays (1s > 2s > 5s > 10s > 30s > 60s) with configurable temporary account lockout after too many failed attempts. - 🤖 Anti-bot rejoin throttle — IPs that reconnect faster than a configurable threshold are immediately forced into a CAPTCHA challenge. - 🧩 CAPTCHA system — triggered automatically after repeated failed logins or suspicious rapid reconnects. Displayed via ActionBar or Title. - 💾 Remember-me sessions — successful logins save a trusted IP-bound session. Reconnecting from the same IP within the configured window (default 7 days) skips /login entirely. /logout clears it immediately. --- ## ✨ Player Experience - 📺 Persistent login title — a repeating title/subtitle reminds unauthenticated players every few seconds so the prompt never gets lost in chat. Pauses automatically during CAPTCHA. - 🎆 Firework login effect — a small burst firework pops on successful authentication alongside a configurable sound and title. Fully toggleable. - 📍 Last location restore — players are teleported back to exactly where they were when they last left. Falls back to a configurable auth spawn if no location is saved. - 🧊 Player isolation — unauthenticated players are completely frozen and hidden from the rest of the server. They cannot move, break or place blocks, open inventories, chat, use commands outside the whitelist, deal or receive damage, pick up items, or interact with anything until authenticated. - ⭐ Premium auto-login — names that belong to Mojang accounts are detected via the Mojang API (cached, async) and can skip /register and /login entirely. Fully toggleable. - 🎨 Colored formatted messages — every message uses bold accents, color-coded status symbols, and framed chat banners. Fully customisable via messages.yml. --- ## 💬 Commands - `/register ` — Create your account - `/login ` — Log into your account - `/logout` — Log out and clear your trusted session - `/changepassword ` — Change your password - `/unregister ` — Permanently delete your account - `/captcha

` — Submit a CAPTCHA code
- `/premium` — Check if your username has a Mojang account
- `/2fa enable` — Enable 2FA and get your secret key
- `/2fa verify ` — Confirm 2FA setup or complete a login challenge
- `/2fa disable` — Disable 2FA on your account
- `/maanauth reload` — Reload config and messages live
- `/maanauth status` — See online count, authenticated count, DB type
- `/maanauth info ` — View account details for any player
- `/maanauth history ` — View last 10 login events with IPs and timestamps
- `/maanauth unlock ` — Clear a locked account
- `/maanauth setauthlocation` — Set the auth spawn to your current position
- `/maanauth clearauthlocation` — Reset the auth spawn to defaults

---

## 🗄️ Database

- 🟢 SQLite out of the box — zero setup, works immediately.
- 🔵 MySQL and MariaDB supported — just fill in the connection details in config.yml.
- ⚡ HikariCP connection pooling — all database I/O runs on a dedicated async thread pool. Nothing ever blocks the server main thread.
- 🔄 Automatic schema creation and migration — tables are created on first run. Upgrading from an older install safely adds new columns without touching existing data.
- 📋 Audit log — every register, login, failed attempt, password change, 2FA event, and logout is recorded with IP and timestamp.

---

## ⚙️ Configuration

Everything is configurable without touching code.

- 📝 Password strength rules (min/max length, uppercase, numbers, special chars)
- ⏱️ Login timeout and freeze behaviour
- 🔒 Brute-force delays and lockout duration
- 🧩 CAPTCHA trigger threshold, code length, and display mode
- ⭐ Premium detection and auto-login toggle
- 💾 Session (remember-me) duration
- 📍 Auth spawn location (or set it in-game with /maanauth setauthlocation)
- 🎵 Login sound, title text, and firework toggle
- 📜 Per-command allowed list for unauthenticated players
- 💬 All player-facing messages in messages.yml

---

## 🔑 Permissions

- `maanauth.use` — Basic auth commands (default: everyone)
- `maanauth.admin` — All /maanauth admin subcommands (default: op)
- `maanauth.bypass` — Skip authentication entirely
- `maanauth.captcha.bypass` — Skip CAPTCHA challenges

---

## 📦 Requirements

- ✅ Paper or Spigot 1.21.x
- ✅ Java 21
- ✅ No external plugin dependencies — all libraries are shaded into the jar

---

Built by maan.exe 🚀

PBXMaan