AdminPassword - Wiki & Documentation

Welcome to the AdminPassword wiki! This plugin provides a robust, lightweight, and foolproof security layer for your server's Administrators. It forces OP players to verify themselves with a password before executing any commands or using OP-specific game features.

🌟 Overview

AdminPassword is built to prevent unauthorized access if an Admin's account gets compromised.

• Command Blocking: Unverified OPs cannot use any commands.
• Shortcut Blocking: Blocks native Minecraft client OP shortcuts (e.g., F3+F4 gamemode switcher) which bypass standard command listeners.
• Stealth Polling: Automatically detects if a player receives OP status while already playing on the server, locking them down immediately.
• Log Masking: Passwords are never leaked. Command logs in the console are masked (/ap [***]).

---

🏗️ Architecture & How It Works

AdminPassword uses a Bidirectional Sync Architecture, making it flawless for both standalone servers and massive proxy networks (Velocity).

1. Standalone Bukkit/Paper Mode

If you run a single server without a proxy, simply drop the adminpassword-bukkit-X.X.X.jar into your plugins folder.
When an OP player joins, the plugin locks their commands. Once they type /ap <password>, they are verified for the duration of their session. If they disconnect, the session is wiped.

2. Network Mode (Velocity + Bukkit) -> "The Synchronized Shield"

If you own a proxy network, you can install the plugin on Velocity AND all backend Bukkit servers. This creates an industry-standard "Synchronized Shield":

1. Verification: A player joins the Lobby server and types /ap <password>.
2. Syncing Up: The Bukkit plugin in the Lobby verifies the password and silently sends a Plugin Message (adminpw:sync) to the Velocity proxy saying: "This player is verified, remember them."
3. Switching Servers: The player enters the portal to the Survival server.
4. Syncing Down: While the player connects, Velocity whispers to the Survival server: "Hey, I know this player, they already entered the password. Unlock them!"
5. Result: The player only types their password once per proxy session, but enjoys maximum security (like F3+F4 blocking) physically enforced on every backend server.

---

📥 Installation

For Standalone Servers (Paper/Spigot/Bukkit)

1. Download adminpassword-bukkit.jar.
2. Place it in your /plugins folder.
3. Restart the server.
4. Edit the plugins/adminpassword/config.yml to change the default password.
5. Restart again or reload the server.

For Proxy Networks (Velocity)

1. Place adminpassword-bukkit.jar in all of your backend servers' /plugins folders.
2. Place adminpassword-velocity.jar in your Velocity proxy's /plugins folder.
3. Restart the proxy and all backend servers.
4. Set the same password in the config.yml files across all servers (Proxy and Bukkit servers).
5. Optional: Give proxy-level admins the adminpassword.protected permission via LuckPerms on Velocity if you want Velocity to also block proxy-specific commands before verification.

---

⌨️ Commands & Permissions

| Command | Aliases | Description | Permission |
|---------|---------|-------------|------------|
| /ap <password> | /admin, /adminpassword | Verifies the administrator. | None (Only works for OPs) |

(Note: Normal players who type /ap will simply receive a "No permission" message without counting as a failed password attempt).

---

⚙️ Configuration (config.yml)

# The master password required for OPs to unlock their accounts.
admin-password: "changeme123"

# What should the plugin do if the player exceeds the max attempts?
# Options: WARN_ONLY, KICK_AFTER_X, BAN_AFTER_X
wrong-password-action: KICK_AFTER_X

# How many failed attempts before the action above is triggered?
max-attempts: 5

# Which commands should be blocked? 
# ALL: Blocks everything.
# LIST: Blocks only the commands defined in the blocked-commands list.
block-mode: ALL

# Used only if block-mode is set to LIST.
blocked-commands:
  - "op"
  - "deop"
  - "stop"
  - "ban"

messages:
  not-verified: "&cYou must enter the admin password to use commands: /ap <password>"
  wrong-password: "&cIncorrect password! Attempts left: {left}"
  correct-password: "&aPassword verified! Welcome back, Admin."
  kicked-message: "&cYou have been kicked for too many failed admin password attempts."
  no-permission: "&cUnknown command. Type \"/help\" for help."

---

❓ FAQ

Q: Do I need to give permissions for OPs to be checked?
A: On Bukkit/Paper, no. The plugin automatically detects if a player has isOp() == true. On Velocity, it checks for the adminpassword.protected permission, as proxies cannot natively see backend OP lists.

Q: Does it protect against F3+F4 gamemode switching?
A: Yes. Unlike most plugins that only listen to text commands, AdminPassword directly blocks the game mode change packet if the OP is unverified.

Q: What if someone uses the console to give a player OP while they are online?
A: AdminPassword features a stealth Polling Task. It scans the server every 2 seconds. If a normal player suddenly becomes OP, the plugin will immediately lock their commands and ask for the password.