SuperLogin

Lightweight authentication plugin for offline-mode Minecraft servers with void world isolation, math captcha, and two-factor authentication (2FA) via Telegram bot.

Supports Spigot 1.21.11+ (Java 21).

---

Features

• Void World Isolation — Players are teleported to a separate empty void world during authentication. No interaction with the main world until logged in.
• Registration & Login — /register <password> <confirm> and /login <password>. Passwords are hashed with BCrypt.
• Command Blocking — All commands are blocked during authentication. Players cannot interact with the world, chat, or use any commands except /login and /register.
• Math Captcha — Optional math captcha before registration. Configurable difficulty:
  • Level 1 (easy): Addition and subtraction, numbers up to 20
  • Level 2 (harder): Multiplication and division included, larger numbers
• Two-Factor Authentication (2FA) — Optional per-player 2FA via Telegram bot. Players link their accounts and must confirm each login through the bot.
• Bot Controls — From the Telegram bot, players can:
  • Approve / Deny login attempts (with IP address shown)
  • Kick the player from the server
  • End session (disconnect the player)
  • Block / Unblock access (auto-kick anyone who tries to log in)
• Server Statistics — View online players, TPS, and RAM usage directly in the Telegram bot.
• Server Name — Configurable server name displayed in bot messages.
• Disable 2FA Safely — Disabling 2FA requires confirmation through the bot to prevent unauthorized changes.
• Multi-language — Built-in Russian and English translations. Change the language in config.yml.
• Boss Bar Timer — Visual countdown for authentication and captcha timeouts.
• Tab List Hiding — Unauthenticated players are hidden from the tab list.
• Anti-Fly Compatible — Players won't be kicked by anti-cheat while in the auth world.
• No In-Game Admin Commands — All settings are managed through configuration files only.

---

Installation

1. Download SuperLogin-1.0.0.jar
2. Place it in your server's plugins/ folder
3. Start the server
4. Configuration files will be generated in plugins/SuperLogin/

Requirements

• Spigot 1.21.11 or compatible fork (Paper, Purpur, etc.)
• Java 21+
• Offline mode (online-mode=false in server.properties)

---

Configuration

All settings are managed through configuration files only. There are no admin commands — edit the files and restart the server.

Main Config (config.yml)

# Plugin language (ru / en)
language: ru

# Server name (displayed in Telegram bot messages)
server-name: "Minecraft Server"

# Enable/disable math captcha on first join
captcha-enabled: false

# Captcha difficulty:
#   1 — easy (addition, subtraction, numbers up to 20)
#   2 — harder (multiplication, division, larger numbers)
captcha-difficulty: 1

# Authentication timeout in seconds
auth-time: 30

# Captcha timeout in seconds
captcha-time: 15

# 2FA confirmation timeout in seconds
2fa-time: 40

# Name of the void authentication world
auth-world: superlogin_auth

2FA Config (2fa.yml)

Two-factor authentication is configured in a separate file. The Telegram bot is disabled by default.

---

Setting Up Telegram Bot

1. Open Telegram and find @BotFather
2. Send /newbot and follow the instructions
3. Copy the API token BotFather gives you
4. Edit plugins/SuperLogin/2fa.yml:

telegram:
  enabled: true
  token: "123456789:ABCdefGHIjklMNOpqrsTUVwxyz"
  bot-username: "YourBotUsername"

5. Restart the server

---

How 2FA Works

Linking

1. Enable the Telegram bot in 2fa.yml and restart the server
2. After logging in, a player types /2fa connect
3. The plugin generates a one-time code (valid for 5 minutes)
4. The player sends this code to the bot using the command: /2fa confirm <code>
5. The bot confirms the link — done!

Login with 2FA

1. Player enters /login <password>
2. If password is correct and 2FA is enabled, the Telegram bot receives a confirmation request showing the player's IP address and the server name
3. Player clicks Approve in the bot → login completes
4. When the player leaves the server, the bot shows "Player left the game"

Bot Controls

After confirming login, the bot shows these buttons:

| Button | Action |
|--------|--------|
| 👢 Kick | Kicks the player from the server |
| 🔒 End Session | Disconnects the player and ends their session |
| 🚫 Block Access | Blocks the account — anyone who tries to log in gets kicked immediately. Button changes to Unblock Access |
| ✅ Unblock Access | Removes the block, allows login again |

Bot Features

• Server Statistics — Press "📊 Статистика сервера" to see online players, TPS, and RAM usage. Press "🔄 Обновить" to refresh.
• Welcome Message — Send /start to the bot for setup instructions.

Disabling 2FA

When a player types /2fa disable, a confirmation request is sent to the bot. The player must confirm the action through the bot to prevent unauthorized disabling.

---

Commands

| Command | Description |
|---------|-------------|
| /register <password> <confirm> | Register a new account |
| /login <password> | Log into your account |
| /2fa connect | Link your Telegram account for 2FA |
| /2fa status | View your 2FA status |
| /2fa disable | Disable 2FA (requires bot confirmation) |

---

File Structure

plugins/SuperLogin/
├── config.yml          # Main settings (language, server name, captcha, timeouts)
├── 2fa.yml             # Telegram bot configuration
├── 2fa-data.yml        # Player 2FA data (auto-generated)
├── players.yml         # Player passwords (auto-generated)
├── lang_ru.yml         # Russian translations
└── lang_en.yml         # English translations

---

Authentication Flow

Player joins
    ↓
[Account blocked?] → Kicked immediately
    ↓
Teleported to void auth world
    ↓
[If captcha enabled] → Solve math problem
    ↓
New player? → /register <pass> <confirm>
Returning?  → /login <pass>
    ↓
[If 2FA enabled] → Confirm via Telegram bot
    ↓                  IP address + server name shown
Teleported back to main world

---

FAQ

Q: Can players use commands while authenticating?
A: No. All commands except /login and /register are blocked.

Q: What happens if 2FA confirmation times out?
A: The player is kicked after the configured timeout (default: 40 seconds). They can reconnect and try again.

Q: Is 2FA required for all players?
A: No. 2FA is opt-in. Players enable it themselves with /2fa connect after logging in.

Q: What does "Block Access" do?
A: It blocks the Minecraft account. Anyone who joins with that username will be kicked immediately. The button toggles to "Unblock Access" so you can remove the block.

Q: Can admins change settings from chat?
A: No. All settings are in config files only. Edit config.yml or 2fa.yml and restart the server.

Q: How do I change the language?
A: Edit language: ru to language: en in config.yml and restart the server.

Q: How do I change the server name in bot messages?
A: Edit server-name in config.yml and restart the server.

---

Compatibility

• Spigot 1.21.11+
• Paper 1.21.11+ (may be incompatible)
• Purpur 1.21.11+
• Java 21+

---

How it works

You can see the plugin's operation on the official server for which it was created.