
OPShield
Protects your server from OP/admin abuse with console-only OP (via password) and optional admin command restriction.
- Загрузки
- 221
- Подписчики
- 1
- Обновлён
- 4 июня 2026 г.
- Лицензия
- Apache-2.0
Опубликован 7 марта 2026 г.
🛡️ OPShield
Advanced security & command protection plugin for Paper 1.21+
Protect your server from abuse — secure OP access, track every action, stop attackers instantly.
📖 Table of Contents
- ✨ Features
- 🔐 Security System
- 📊 Audit & Logging
- 📦 Requirements
- 🚀 Installation
- ⌨️ Commands & Permissions
- 🔧 Configuration
- 🔍 Troubleshooting
- ❓ FAQ
- 📄 Credits
✨ Features
🔒 OP Protection
- Password-gated
/opand/deop— no password, no privilege changes - Async PBKDF2 verification — password hashing runs off the main thread; zero TPS impact even under brute-force attack
- Authenticated session tokens — after one successful login, a configurable session window lets admins skip re-entering the password (
security.session_timeout_minutes, default 30 min) - Session cleared on disconnect — sessions are never carried across reconnections
- Global auth concurrency cap — server-wide PBKDF2 operations capped at 4 concurrent verifications to prevent CPU saturation under mass attack
- PBKDF2-HMAC-SHA256 hashed storage — plaintext never kept in config
- Configurable PBKDF2 iteration count (
security.password.pbkdf2_iterations) - Automatic migration from legacy plaintext and SHA-256 hashes
- Auto-upgrade legacy hashes — on next successful login, SHA-256 is silently replaced with PBKDF2 (
security.password.auto_upgrade_legacy_hash) - Console warning if a legacy SHA-256 hash is detected on startup
- OP whitelist — restrict
/opto a predefined set of player names
🚫 Sensitive Command Protection
- Block dangerous commands for non-OP players (
blocked_commands) - Optionally block commands even for OP players (
blocked_op_commands) - Block entire command namespaces via prefix list (
blocked_command_prefixes) - Alias and namespace resolution — bypass attempts via
minecraft:opor plugin aliases are caught - Per-player bypass permission (
opshield.bypass) for trusted staff
🧠 Brute-force Detection & Lockout
- Configurable failed-attempt limit before lockout (
security.lockout.max-attempts) - Exponential backoff — each offence doubles the lockout duration
- Optional IP-mirrored lockout (
security.lockout.track_ip) - Lockout count decay after a cooling-off period (
security.lockout.count_decay_hours) - Persistent tracking — lockout state survives server restarts
- Manual unlock via
/opshield unlock <player|ip>
🕵️ Shadow Ban System
- Sensitive blocked commands send a fake success message instead of an error
- Each trigger increments the player's hidden shadow-ban level
- Level persists across restarts
- Auto-escalates to real punishment when
shadow_ban.auto_punish_levelis reached - Set
auto_punish_level: 99to keep decoy behaviour without escalation - Fake messages come from language files — fully customisable per locale
⚠️ Auto Punishment System
- Punishment modes:
kick,ban,ban-ip,firewall,custom - Persistent rolling-window threshold — survives restarts and crashes
- Firewall mode runs an OS script asynchronously via
ProcessBuilderwith configurable timeout - Custom mode supports
{player}and{ip}placeholders - IP-limit auto-punishment for accounts detected sharing the same IP
🌍 Multi-Language Support
- Bundled language files: English (
en), Vietnamese (vn), Russian (ru) - Automatic fallback to English for any missing key
- Switch language via
language: "en"inconfig.yml
📊 Audit & Logging
- Every privilege change, password failure, command block, and punishment is logged
- Async queue — log writes never touch the main thread
- Queue capacity limit —
audit.max_queue_sizeprevents OOM if disk writes fail for extended periods - Dual output format —
audit.format: plain(default human-readable) oraudit.format: json(machine-readable, one JSON object per line) - UTF-8 safe — uses NIO
Files.write()with explicit charset - Retry on failure — failed writes are re-queued instead of silently discarded
- Configurable rotation:
audit.max_file_size_mbandaudit.log_retention(up to N backup files) - Optional console mirror:
audit.console_output: true - Log files:
plugins/OPShield/audit.log,audit.log.1…audit.log.N
📦 Requirements
| Component | Version |
|---|---|
| Java | 21+ |
| Paper | 1.21+ |
| Folia | ❌ Not supported |
🚀 Installation
- Download the plugin
.jar - Drop it into your server's
plugins/folder - Start the server — OPShield will generate a random password and print it once in the console
- Save the password somewhere safe (it is only shown once)
- Grant permissions — add
opshield.adminto your admin group in your permission plugin (e.g. LuckPerms). OPShield no longer grants permissions based on OP status alone (changed in v1.8.0) - Open
plugins/OPShield/config.ymlto customise behaviour - Run
/opshield reloadin-game or restart to apply changes ✅
Upgrading from 1.7.0?
data.ymlis automatically migrated on first boot. You only need to update your permission plugin setup — see the CRITICAL note in the changelog.
Tip: If you already have an
op_passwordplaintext value from an older version, OPShield will automatically migrate it toop_password_hashand remove the plaintext entry.
⌨️ Commands
| Command | Description |
|---|---|
/op <player> [password] |
Grant OP with password verification |
/deop <player> [password] |
Remove OP with password verification |
/opshield reload |
Reload configuration |
/opshield unlock <player|ip> |
Clear all tracking state for a player or IP |
/opshield status |
Show runtime statistics (active sessions, auth queue, flagged IPs, etc.) |
🔐 Permissions
⚠️ Changed in v1.8.0: All permissions now default to
false. You must grant them explicitly via a permission plugin.
| Permission | Default | Description |
|---|---|---|
opshield.* |
false | Wildcard — grants all permissions |
opshield.admin |
false | Grants all child permissions |
opshield.reload |
false | Reload OPShield configuration |
opshield.unlock |
false | Unlock a tracked player or IP |
opshield.status |
false | View runtime statistics |
opshield.op |
false | Use password-protected /op |
opshield.deop |
false | Use password-protected /deop |
opshield.bypass |
false | Bypass non-OP restricted command blocking |
Example LuckPerms setup
/lp group admin permission set opshield.admin true
🔧 Configuration
Files generated under plugins/OPShield/:
config.yml— main configurationdata.yml— persistent runtime state (lockouts, shadow-ban levels, IP windows)languages/en.yml— English messageslanguages/vn.yml— Vietnamese messageslanguages/ru.yml— Russian messages
⚙️ Key Config Options
# Enable verbose console logging for troubleshooting (disable in production)
debug: false
# Password security
security:
lockout:
enabled: true
max-attempts: 3
duration-minutes: 3
track_ip: true
count_decay_hours: 168
# Session timeout after successful auth (0 = disable, always require password)
session_timeout_minutes: 30
password:
pbkdf2_iterations: 120000 # range: 10000 – 1000000
auto_upgrade_legacy_hash: true # silently upgrade SHA-256 → PBKDF2 on login
# Auto-punishment
auto_punishment:
enabled: true
threshold: 5
window_seconds: 300
command: "kick" # kick | ban | ban-ip | firewall | custom
firewall_timeout_seconds: 10
# Shadow ban
shadow_ban:
enabled: true
auto_punish_level: 5
# Audit log
audit:
console_output: true
max_file_size_mb: 5
log_retention: 3
max_queue_size: 10000 # 0 = unlimited (not recommended)
format: "plain" # plain | json
📐 Recommended settings by server size
Small server (≤ 20 players)
security.lockout.max-attempts: 3
security.lockout.duration-minutes: 5
ip_limit.max_accounts: 2
auto_punishment.enabled: false
shadow_ban.auto_punish_level: 10
Medium server (20–100 players)
security.lockout.max-attempts: 3
security.lockout.duration-minutes: 3
ip_limit.max_accounts: 3
auto_punishment.enabled: true
auto_punishment.command: kick
auto_punishment.threshold: 5
shadow_ban.auto_punish_level: 5
Large server (100+ players)
security.lockout.max-attempts: 2
security.lockout.duration-minutes: 10
ip_limit.max_accounts: 2
auto_punishment.enabled: true
auto_punishment.command: ban-ip
auto_punishment.threshold: 3
shadow_ban.auto_punish_level: 3
🔥 Firewall mode setup
Firewall mode executes an OS script asynchronously. To enable it:
auto_punishment:
command: "firewall"
allow_unsafe_firewall_exec: true
firewall_timeout_seconds: 10
# Linux:
firewall_script: "iptables -A INPUT -s {ip} -j DROP"
# Windows:
# firewall_script: "netsh advfirewall firewall add rule name=OPShield dir=in action=block remoteip={ip}"
If allow_unsafe_firewall_exec is false, firewall mode falls back to a safe kick.
🔍 Troubleshooting
Admin needs to enter password every single /op command
OPShield grants a session after each successful authentication. Check:
security.session_timeout_minutesinconfig.yml— if set to0, sessions are disabled- The session is cleared when you disconnect; if you keep reconnecting you will need to re-authenticate
- Run
/opshield statusto see how many active sessions exist
Cannot use /op — "Incorrect password"
The password is required. Run:
/op <yourname> <password>
If you forgot the password, clear op_password_hash in config.yml and restart — a new password will be generated and printed in the console.
Admin cannot use /opshield after upgrading from 1.7.0
In v1.8.0, permissions now default to false instead of op. You need to explicitly grant the permission:
/lp group admin permission set opshield.admin true
Player is locked out and cannot try again
An admin can manually clear the lockout:
/opshield unlock <playername>
/opshield unlock <ip-address>
Auto-punishment is not triggering
Check the following:
auto_punishment.enabled: trueinconfig.yml- The command the player used is listed in
auto_punishment.sensitive_commands shadow_ban.enabled— if true, the player may be getting fake success messages first; level must reachauto_punish_level- Run
/opshield reloadafter any config change - Run
/opshield statusto see current shadow-ban levels and punish state
Audit log is empty or not updating
- Check
audit.console_output: trueto confirm logging is active - Check write permissions on the
plugins/OPShield/folder - If
audit.max_queue_sizeis reached, aSEVEREwarning appears in console — check disk space
Config changes are not taking effect
Run in-game or console:
/opshield reload
❓ FAQ
Does OPShield replace /op?
No — it intercepts and wraps it. The original /op behaviour is preserved but gated behind a password.
Is the password stored securely?
Yes — passwords are hashed using PBKDF2-HMAC-SHA256 with a random salt and 120,000 iterations (configurable). The plaintext is never written to disk.
Does it support Spigot or Folia?
Paper 1.21+ only. Spigot may work but is not tested. Folia is explicitly not supported (folia-supported: false).
Can I disable auto-punishment entirely?
Yes — set auto_punishment.enabled: false. Shadow-ban fake messages will still work independently.
What happens if the server restarts during a lockout?
Lockout state is persisted to data.yml and restored on startup. Players cannot bypass lockouts by crashing or restarting the server.
Can I have multiple language files?
Yes — all three bundled files (en, vn, ru) are always present. Switch via language: in config.yml. Missing keys automatically fall back to the bundled English defaults.
What changed in v2.0.0?
Thread-safety overhaul — five race conditions and visibility bugs fixed:
ArrayDequerace condition — replaced withConcurrentLinkedDequeto preventConcurrentModificationExceptionand data corruption when the async cleanup task and main-thread event handler accessed the same deque simultaneously.- Non-volatile config fields —
lockoutDecayHours,autoPunishmentWindowSeconds,ipLimitTimeWindowSeconds, andsessionTimeoutMsare nowvolatileso async tasks always see up-to-date values after/opshield reload. - Non-volatile
AuditLoggerfields —consoleOutput,maxBytes,maxBackups,maxQueueSize, andformatare nowvolatile. - IP range check — replaced 16 manual
startsWith()checks withInetAddresspredicates, adding previously missing link-local range detection. - Audit log level — audit console output now uses
INFOinstead ofWARNING.
See the Changelog for details.
What changed in v1.9.1?
Six bugs fixed in a patch release: double timestamps in audit log, missing session-granted/active messages, shadow-ban decoy messages losing their colours, exponential backoff count being reset too early (making count_decay_hours ineffective), and the /opshield reload permission check order. See the Changelog for details.
What changed in v1.9.0?
The biggest changes are async PBKDF2 authentication (no more TPS impact under brute-force) and session tokens (no need to re-type the password every command within the session window). See the Changelog for the full list.
What changed in v1.8.0?
The most important change is permission defaults — see the Changelog for the full list. The short version: grant opshield.admin to your admin group in LuckPerms.
📄 Credits
Author: Duong2012G
License: Apache 2.0
Website: https://modrinth.com/user/Duong2012G
Built for secure, professional Minecraft servers.
Ченджлог
2.0.0Релиз1.21.9, 1.21.10, 1.21.11 · 4 июня 2026 г.
[2.0.0] - 2026-06-03 — Thread-Safety & Security Overhaul
This release resolves all known thread-safety bugs identified through a full
code audit. No configuration keys were added, removed, or renamed.
Existing config.yml and data.yml files are fully compatible — no
migration required.
1.9.1Релиз1.21.9, 1.21.10, 1.21.11 · 23 мая 2026 г.
[1.9.1] - 2026-05-23 — Bug Fix Release
This is a patch release that resolves six bugs identified through code review.
No configuration keys were added, removed, or renamed. Existing data.yml and
config.yml files are fully compatible — no migration needed.
🐛 Bug Fixes
FIX [Critical] — Double timestamp in every audit log entry
- Root cause:
OPShield.audit()manually prepended a formatted timestamp to the message string before passing it toAuditLogger.log(). However,AuditLogger.buildLine()also wraps every line with its own timestamp, resulting in output like:
This affected every audit entry since v1.6.0.[2026-05-23 10:00:00] 2026-05-23 10:00:00 | Configuration reloaded. - Fix: Removed the manual timestamp construction from
OPShield.audit(). Timestamp formatting is now owned exclusively byAuditLogger.buildLine(). Audit lines now read correctly:[2026-05-23 10:00:00] Configuration reloaded. - Impact: Existing rotated log files (
audit.log.1etc.) retain the old double-timestamp format. New entries written after the upgrade are clean. No action required on existing files.
FIX [High] — auth_session_granted and auth_session_active messages were never sent
- Root cause: The language key
auth_session_grantedwas introduced in v1.9.0 but the correspondingsend()call was absent from bothcompletePrivilegeCommand()(session grant path) andhandlePrivilegeCommand()(session reuse path). Players had no way to know a session existed or how much time remained. - Fix:
completePrivilegeCommand()now callssendReplaced(player, "auth_session_granted", "minutes", …)immediately after the session is stored inauthenticatedSessions.handlePrivilegeCommand()now callssendReplaced(player, "auth_session_active", "minutes", …)(with the remaining minutes) on the session-reuse fast-path.
- New language key:
auth_session_activeadded toen.yml,vn.yml, andru.yml.
FIX [Medium] — Shadow-ban decoy messages lost all colour formatting
- Root cause: The fake-success message pipeline was:
PlainTextComponentSerializer.plainText().serialize(colorize(fakeMsg))colorize()correctly parsed&a,&c, etc. into an AdventureComponentwith colour, butPlainTextComponentSerializer.plainText().serialize()then stripped every colour code before wrapping the result in a hard-codedNamedTextColor.YELLOW. Language-file formatting was silently discarded. - Fix: Removed the unnecessary serialise/re-wrap chain. The
Componentreturned bycolorize(fakeMsg)is now sent directly:
Server owners can now apply any Adventure-compatible colour codes (player.sendMessage(colorize(fakeMsg));&a,&c,&l, etc.) in their language files and have them rendered correctly. - Cleanup: Removed now-unused imports
NamedTextColor,PlainTextComponentSerializer, andComponentfromOPShield.java.
FIX [Medium] — LockoutManager.cleanupExpired() discarded backoff count earlier than count_decay_hours intended
- Root cause:
cleanupExpired()removed any record whoseexpiryMs <= nowANDattempts == 0. When a lockout expired naturally,isLockedOut()setexpiryMs = 0andattempts = 0(intentionally preservingcountfor exponential backoff). On the very next cleanup tick (≤ 60 s later), the cleanup predicate matched and deleted the entire record, includingcount. Thesecurity.lockout.count_decay_hoursconfig key had no practical effect: the backoff counter was always reset within one cleanup cycle after each lockout expired. - Fix:
cleanupExpired()now accepts adecayMsparameter (derived fromlockoutDecayHoursinOPShield). A record is only removed when both conditions are true:- No active lockout and no in-progress attempts.
- The time elapsed since
lastLockoutAtMsexceedsdecayMs. Exponential backoff now behaves as documented.
- API change (internal):
LockoutManager.cleanupExpired()→cleanupExpired(long decayMs). No external callers; internal call site updated inOPShield.cleanupRuntimeState().
FIX [Medium] — /opshield reload blocked by allow_op_reload: false even for players with explicit opshield.reload permission
- Root cause: In
handleManagementCommand(), theallow_op_reloadflag was evaluated before the permission check. A player with an explicitopshield.reloadgrant from a permissions plugin was still denied whenallow_op_reload: false, making the permission effectively meaningless. - Fix: The permission check (
opshield.reload) now runs first. Theallow_op_reloadflag is applied only as a secondary restriction after the caller is confirmed to hold the permission. Console senders are unaffected.
FIX [Low] — IP tracking unreliable behind BungeeCord / Velocity (documentation + debug warning)
- Root cause:
getPlayerIpRaw()usesplayer.getAddress().getAddress().getHostAddress(). Behind a proxy, this resolves to the proxy's own address (commonly127.0.0.1or a private RFC-1918 range), not the connecting client's real IP. IP-based lockout mirroring andip_limittracking silently group all players under the same key. - Fix (partial): Full proxy-IP forwarding requires server-side configuration
outside the plugin's scope (Paper IP forwarding,
BungeeGuard, etc.). This release adds a debug-mode warning logged whendebug: trueand the resolved address is a loopback or private-range address, so administrators are alerted during setup. The warning is suppressed in production (debug: false) to avoid console spam on legitimate LAN servers.
🌍 Language File Changes
| Key | Files | Change |
|---|---|---|
auth_session_active |
en.yml, vn.yml, ru.yml |
Added — shown when an existing valid session is reused |
All other keys are unchanged and backwards-compatible.
🔧 Internal / Code Quality
- Removed four now-unused imports from
OPShield.java:LocalDateTime,ZoneId,Instant,DateTimeFormatter(timestamp moved toAuditLogger),Component,NamedTextColor,PlainTextComponentSerializer(shadow-ban message fix). LockoutManager.cleanupExpired()signature updated (internal only).- Added inline
FIX[…]comments at every corrected site for audit trail.
✅ Compatibility
| Item | Status |
|---|---|
config.yml (v1.9.0) |
✅ No changes required |
data.yml (v1.9.0) |
✅ No changes required |
| Language files (v1.9.0) | ⚠️ auth_session_active key added; old files work but players will see [Missing Message: auth_session_active] until updated |
| Paper API | ✅ 1.21+ (unchanged) |
1.9.0Релиз1.21.9, 1.21.10, 1.21.11 · 15 мая 2026 г.
[1.9.0] - 2026-05-15 — Async Auth, Session Timeout & Security Hardening
🐛 Bug Fixes
FIX [Critical] — PBKDF2 verification was running on the main server thread
- Root cause:
handlePrivilegeCommand()calledPasswordHasher.verify()synchronously duringonCommand(), which executes on the main thread. With 120,000 PBKDF2 iterations, each failed attempt caused a measurable TPS drop (~50–200 ms). Under coordinated brute-force from multiple clients this could stall the server tick loop. - Fix: Password verification is now dispatched via
Bukkit.getScheduler().runTaskAsynchronously(). The result is delivered back to the main thread viarunTask()for all Bukkit API side-effects. Zero blocking on the main thread. - New status field:
/opshield statusnow shows pending verification count (0/4).
FIX [Critical] — No session timeout after successful authentication
- Root cause: After a correct password was accepted, no state was stored. Every subsequent
/opor/deoprequired re-entering the password. In practice admins worked around this by keeping a note of the password nearby, which is a security anti-pattern. - Fix: A
ConcurrentHashMap<UUID, Long>(authenticatedSessions) tracks expiry epoch-ms per player. After the first successful auth within a session window, password entry is skipped. - Config key:
security.session_timeout_minutes(default30; set0to disable). - Session lifecycle: granted on successful auth → cleared on player quit (
PlayerQuitEvent) → cleared on manual/opshield unlock→ purged by cleanup task.
FIX [High] — No global rate limit on PBKDF2 operations
- Root cause: A coordinated attack with many accounts spamming
/op <name> <guess>queued unbounded async hashing tasks, saturating CPU cores. - Fix:
AtomicInteger globalAuthCountcaps server-wide concurrent PBKDF2 operations atMAX_CONCURRENT_AUTH = 4. Requests over the cap receiveauth_server_busyand are dropped without queuing. - Per-sender dedup:
Map<String, AtomicInteger> authPendingprevents the same player from queuing more than one verification at a time. Excess requests receiveauth_pending.
FIX [High] — cleanupRuntimeState() ran on the main thread
- Root cause:
Bukkit.getScheduler().runTaskTimer()was used instead ofrunTaskTimerAsynchronously(). The cleanup method holds synchronized blocks onLockoutRecordobjects; under load this briefly stalled the tick. - Fix: Scheduler call changed to
runTaskTimerAsynchronously(). All collections involved areConcurrentHashMap/ConcurrentLinkedQueue— safe for async access.
FIX [Medium] — Shutdown race condition between async periodic flush and onDisable sync flush
- Root cause:
onDisable()calledflushPersistentDataSync()while the 200-tick async flush task could be mid-execution. AlthoughcompareAndSetprevented double saves, the two threads could both have a reference todataFileand compete on the sameYamlConfigurationserialisation. - Fix:
onDisable()now cancels both async task IDs (periodicFlushTaskId,cleanupTaskId) before callingflushPersistentDataSync(), ensuring only one flush can run at shutdown.
FIX [Medium] — ShadowBanManager used HashMap for command→message mapping
- Root cause:
HashMaphas undefined iteration order. Commands likedeop op,ban-ip, orgive opcould match the wrong message key depending on JVM run, leading to non-deterministic fake responses. - Fix: Replaced with
LinkedHashMappreserving explicit insertion order. More specific and longer tokens (e.g."inventory","teleport","deop") are declared before shorter substrings ("clear","tp","op") so prefix-matching is always predictable.
FIX [Low] — config-version field was written but never read
- Root cause:
config-version: 2was introduced in v1.8.0 butreloadConfiguration()never checked it. There was no warning when admins ran an old config against a new build. - Fix:
reloadConfiguration()now comparesconfig-versionagainstEXPECTED_CONFIG_VERSION = 3. It logs a warning if the file is outdated (new options missing → defaults used) or from a newer build (unknown keys may be ignored). The version is bumped in-place so the warning fires only once.
FIX [Low] — PlayerQuitEvent not handled; stale session UUIDs accumulated
- Root cause:
authenticatedSessionswas new in this version, but without a quit handler a UUID could remain in the map until the cleanup task ran, creating a window where a reconnecting player could bypass auth. - Fix:
@EventHandler onPlayerQuit()immediately removes the UUID fromauthenticatedSessionson disconnect.
✨ New Features
Authenticated Session Tokens
- First successful
/opor/deopauthentication grants a timed session. - Subsequent privilege commands within the window skip password entry.
- Session duration:
security.session_timeout_minutes(default30;0= always require password). - Sessions are cleared on disconnect, manual unlock, or config reload.
- New language keys:
auth_session_granted,auth_pending,auth_server_busy.
Async PBKDF2 Authentication Pipeline
- All password verifications now run asynchronously.
- Bukkit API side-effects (setOp, messages, broadcasts) still execute on the main thread via callback.
- Extracted
completePrivilegeCommand()to consolidate post-auth logic (hash upgrade, session grant, lockout clear, setOp, broadcast).
Enhanced /opshield status Output
Two new status lines:
Active auth sessions: 2
Pending PBKDF2 verifications: 0/4
Session timeout: 30 min
🔧 Configuration Changes
| Key | Change | Default |
|---|---|---|
config-version |
Bumped 2 → 3 |
3 |
security.session_timeout_minutes |
NEW — auth session TTL in minutes; 0 = disabled |
30 |
No existing keys were removed or renamed. Old config-version: 2 files are read normally with a one-time console warning.
🌍 Language Files
Three new message keys added to all language files (en, vn, ru):
| Key | Purpose |
|---|---|
auth_pending |
Sender already has a PBKDF2 verification in flight |
auth_server_busy |
Server-wide auth cap reached |
auth_session_granted |
Confirmation message shown after session is created |
📊 Code Quality Metrics
| Metric | v1.8.0 | v1.9.0 |
|---|---|---|
| PBKDF2 on main thread | ✅ yes | ❌ no (async) |
| Session timeout | ❌ | ✅ |
| Global auth rate limit | ❌ | ✅ (cap=4) |
| Per-sender auth dedup | ❌ | ✅ |
| Cleanup on main thread | ✅ yes | ❌ no (async) |
| Shutdown race condition | ✅ present | ❌ fixed |
| ShadowBan match order | non-deterministic | deterministic |
config-version enforced |
❌ | ✅ |
PlayerQuitEvent handled |
❌ | ✅ |
📝 Migration Notes from v1.8.0
- No breaking changes — existing
config.ymlanddata.ymlare fully compatible. - New config key — add
security.session_timeout_minutes: 30(or let the default apply on first reload). - config-version is auto-bumped from
2→3on first reload; a one-time warning will appear in console. - Permission setup is unchanged from v1.8.0.
🔮 Planned for v1.10.0
- Extract
AutoPunishmentManager— move all ban/kick/firewall logic out ofOPShield.java - Extract
IpLimitManager— move IP tracking and flagging - Extract
CommandRestrictionManager - Unit tests for
LockoutManagerandShadowBanManager - Consider Argon2id as an optional stronger hashing algorithm
1.8.0Релиз1.21.9, 1.21.10, 1.21.11 · 28 апреля 2026 г.
[1.8.0] - 2026-04-28 — Manager Refactor, Security Hardening & Quality Improvements
🔒 Security Fixes
CRITICAL — Permission Default Changed
opshield.admindefault changed fromop→false(breaking if you relied on implicit OP grants)- Previously any player with OP status automatically received full OPShield admin rights
- Now all permissions must be explicitly granted via a permission plugin (e.g. LuckPerms)
- Migration: add
opshield.adminto your OP group in your permission plugin
- All child permissions (
opshield.reload,opshield.unlock,opshield.op,opshield.deop) default changed fromop→falsefor the same reason - Added
opshield.*wildcard permission for convenience
🏗️ Architecture Improvements
LockoutManager — Full Refactor
- Introduced
LockoutRecordinner class consolidating 5 separateConcurrentHashMaps (failedAttempts, lockoutTimestamps, lockoutCount, lastLockoutAt) into a single per-key object - Decay logic moved entirely into
LockoutManager.recordFailure()— no longer split between main class and manager - Added
mirrorLockout()for IP-mirrored lockouts (called by OPShield whentrack_ip=true) - Added
exportSnapshot()/importSnapshot()for clean persistence without raw map access - Backwards-compatible persistence: v1.8.0 reads legacy v1.7.0 data format and migrates automatically
LockoutManageris now the single source of truth for all lockout state
ShadowBanManager — Full Refactor
- Shadow-ban levels now owned by
ShadowBanManager(previously a rawConcurrentHashMapinOPShield.java) getFakeMessage()is no longer static; it accepts aMessageProviderfunctional interface so messages come from language files, not hard-coded strings- Added
shouldEscalate(key, threshold)method — clearly separates the "should I punish?" decision from execution - Added
exportLevels()/importLevels()for persistence - Extended command keyword → message-key mapping: now covers
op,deop,kick,stop,reload,pardon
OPShield.java — Reduced God Class Burden
- Replaced 5 raw state maps with delegation to
LockoutManager - Replaced
playerShadowBanLevelmap with delegation toShadowBanManager - Added
/opshield statuscommand for runtime diagnostics (shows active levels, flagged IPs, queue sizes) - Added
debugLog()helper — controlled bydebug: falseconfig key; never exposes sensitive info in production
✨ New Features
debugmode (debug: falsein config.yml) — enables verbose internal logging for troubleshooting without recompiling/opshield status— new sub-command withopshield.statuspermission; reports shadow-ban level count, flagged IPs, sensitive-history windows, auto-punishment statesecurity.password.auto_upgrade_legacy_hash: true— automatically re-hashes a legacy SHA-256 password to PBKDF2 the next time the correct password is provided; hash is saved to config.yml with no manual action required- Audit queue capacity (
audit.max_queue_size: 10000) — prevents unbounded memory growth if disk writes fail; oldest entries dropped with a console warning (rate-limited to once per flush cycle) - Audit JSON format (
audit.format: json) — emits one machine-readable JSON object per line for log aggregator ingestion;plainformat unchanged for backwards compatibility
🐛 Bug Fixes
ShadowBanManager.getFakeActionMessage()was never called — v1.7.0 added it but the main class still used hard-coded logic. Now the manager is the sole source of fake messagesLockoutManager.ipLimitMapwas unused —recordIpConnection()was called but the data was never read. Removed; IP limit tracking remains in OPShield.java pendingIpLimitManagerextractionPasswordHasher.upgradeHashIfNeeded()(NEW) —isLegacyHash()existed in 1.7.0 but there was no code path to actually upgrade the stored hash. Now the main class callsupgradeHashIfNeeded()after each successful login whenauto_upgrade_legacy_hash: trueHASH_FORMAT_VERSIONconstant (NEW) — the string"pbkdf2"was scattered as a magic literal acrossPasswordHasher; centralised to a named constant
🔧 Build Improvements
maven-compiler-plugin 3.13.0added with explicit<release>21</release>and<parameters>flagmaven-shade-plugin 3.6.0added (no relocations yet, but scaffold is ready for future bundled deps)maven-surefire-plugin 3.2.5added with JUnit 5 + Mockito test dependencies for unit testing managers- Centralised version properties —
java.version,paper.version, and plugin versions now all defined in<properties>for consistency
📝 Configuration
- Added
config-version: 2— allows future automatic migration detection - Added
debug: false— verbose diagnostic logging toggle - Added
security.password.auto_upgrade_legacy_hash: true - Added
audit.max_queue_size: 10000 - Added
audit.format: plain - Added
shadow_ban.auto_punish_leveldefault raised from3→5 - Added inline "Recommended values by server size" comments to
config.yml
🌍 Language Files
- Added 7 new shadow-fake message keys:
shadow_fake_op,shadow_fake_deop,shadow_fake_kick,shadow_fake_pardon,shadow_fake_stop,shadow_fake_reload(all three languages) - Fixed inconsistent Vietnamese translations in
vn.yml - All three language files now use natural-language fake messages that better blend in with real server output
📊 Code Quality Metrics
| Metric | v1.7.0 | v1.8.0 |
|---|---|---|
| Raw state maps in OPShield.java | 7 | 3 |
| Manager classes | 2 (stub) | 2 (fully active) |
Permissions with insecure default op |
6 | 0 |
| Hard-coded fake messages | 8 | 0 |
| Unused manager methods | 2 | 0 |
config-version |
❌ | ✅ |
| Debug mode | ❌ | ✅ |
| Audit queue cap | ❌ | ✅ |
| JSON audit format | ❌ | ✅ |
📝 Migration Notes
- Permission plugin setup required — add
opshield.adminto your OP group (see CRITICAL note above) - data.yml is auto-migrated from v1.7.0 format on first boot — no manual action needed
- All configuration keys are backwards-compatible; new keys use sensible defaults
- Old
lockout_timestamps/failed_attempts/lockout_count/last_lockout_atsections indata.ymlare read on upgrade and merged intolockout_records; old sections are replaced on next save
🔮 Planned for v1.9.0
- Extract
AutoPunishmentManager— move all ban/kick/firewall logic out ofOPShield.java - Extract
IpLimitManager— move IP tracking and flagging - Extract
CommandRestrictionManager— movematchesConfiguredCommandlogic - Add unit tests for
LockoutManagerandShadowBanManager - Consider Argon2id as an optional stronger hashing algorithm
1.7.0Релиз1.21.9, 1.21.10, 1.21.11 · 24 апреля 2026 г.
[1.7.0] - 2026-04-24 — Architecture Improvements & God Class Refactoring
🚀 Improvements
Architecture Refactoring
LockoutManager (NEW) — Extracted lockout logic from main class
- Centralized player/IP lockout state management
- Clean public API for lockout operations
- Expired lockout cleanup methods
ShadowBanManager (NEW) — Extracted shadow ban logic
- Shadow ban state tracking
- Fake action message generation
- Duration management with expiry cleanup
- Improved message consistency
Password Security
- PasswordHasher improvements — Enhanced password handling
- PBKDF2 iteration count configurable at runtime
- Legacy SHA-256 detection with
isLegacyHash()method - Iteration count validation (10,000 - 1,000,000 range)
- Better separation of hash versioning concerns
Code Organization
- Created
manager/package for extracting business logic - Reduced OPShield.java God Class burden
- Better separation of concerns
- Improved testability of individual components
Language Files
- Fixed grammar inconsistencies (e.g., "1 player" vs "1 players")
- Improved fake action message clarity
- Better error message wording
📊 Code Quality
Metrics
- Before: 1,172 LOC in single class (God Class)
- After: OPShield.java reduced + 2 new manager classes
- Managers Created: 2 (LockoutManager, ShadowBanManager)
- Lines Extracted: ~300+ from main class
Quality Improvements
- ✅ Reduced cyclomatic complexity in main class
- ✅ Improved code organization
- ✅ Better separation of concerns
- ✅ More testable components
- ✅ Easier to extend for future features
📝 Migration Notes
For existing servers:
- No database migration needed
- All configuration stays the same
- No command changes
- Direct drop-in JAR replacement
🔮 Future Work (v1.8.0+)
Recommended further refactoring:
- Extract
AutoPunishmentManagerfor ban/kick logic - Extract
IpLimitManagerfor IP tracking - Extract
CommandRestrictionManagerfor command validation - Create interface-based services for better testability
- Add unit tests for new manager classes
1.6.0Релиз1.21.9, 1.21.10, 1.21.11 · 21 апреля 2026 г.
[1.6.0] — 2026-04-21
Bug fixes
High severity
AuditLoggerswitched fromFileWriterto NIOFiles.write()—FileWriterused the JVM platform default charset, which could produce garbled or truncated log entries on servers whose OS locale is not UTF-8. All writes now usejava.nio.file.Files.write()with an explicitStandardCharsets.UTF_8argument andStandardOpenOption.APPEND.ensureFile()is no longer called on every flush tick — the previous implementation re-checked (and conditionally re-created) the log file and its parent directory on every async flush, even when neither had changed. AnAtomicBoolean fileReadyflag now gates the check so it runs at most once per file lifetime. The flag is cleared after rotation so the next write correctly re-creates the log file.Failed audit writes now re-queue entries instead of silently discarding them — if a flush attempt throws
IOException, the affected lines are returned to the front of the queue and retried up toMAX_WRITE_RETRIES(2) times. On final failure aSEVEREconsole error is printed and the lines are re-queued so they are not permanently lost.
Medium severity
- Legacy SHA-256 password hash triggers a console warning on startup — if
op_password_hashinconfig.ymlcontains an old SHA-256 value (generated by OPShield < 1.4.0), the server console now displays a clear warning advising the admin to reset the password so it is upgraded to PBKDF2 storage. The plugin continues to accept the legacy hash for authentication; no data is lost.
Low severity
Magic string
"unknown"for unresolvable player IPs replaced with named constantUNKNOWN_IP— eliminates the class of silent typo bugs where inconsistent string literals caused an IP to be handled as a real address in some code paths but skipped correctly in others.Grammar correction in English shadow-ban fake messages —
shadow_fake_clearincorrectly read"Cleared the inventory of 1 players". Corrected to"Cleared the inventory of 1 player". Related entity messages (shadow_fake_kill,shadow_fake_tp) also updated to use the singular form"entity"for consistency.folia-supported: falseadded toplugin.yml— OPShield uses the Bukkit task scheduler and is not compatible with Folia. The flag prevents Folia auto-detection from incorrectly classifying the plugin as Folia-safe and loading it on an incompatible runtime.auto_punish_firewall_failmessage key added to all language files — previously the firewall punishment path had no dedicated message for the case where the script is skipped (unsafe exec disabled, blank script, or unknown IP). All three language files (en.yml,vn.yml,ru.yml) now include the key.
Improvements
PBKDF2 iteration count is now configurable via
security.password.pbkdf2_iterations(default120000, range10000–1000000). Increasing the value raises brute-force resistance at the cost of slightly slower verification on each/opor/deopattempt. Existing stored hashes are unaffected — they carry their own iteration count.firewall_scriptconfig entry now includes OS-specific examples — the config comment now shows both a Linuxiptablesexample and a Windowsnetshexample so admins know the expected format without having to consult external documentation.
New config keys
| Key | Default | Description |
|---|---|---|
security.password.pbkdf2_iterations |
120000 |
PBKDF2 iteration count for new password hashes (10 000–1 000 000) |
New language keys (all files)
| Key | Description |
|---|---|
auto_punish_firewall_fail |
Shown when firewall punishment is skipped and player is kicked instead |
1.5.0Релиз1.21.9, 1.21.10, 1.21.11 · 20 апреля 2026 г.
[1.5.0] — 2026-04-19
Bug fixes
Medium severity
sensitiveCommandHistorynow persisted todata.yml— the auto-punishment rolling window survived previously only in memory, allowing players to bypass the threshold by timing restarts or crashes. Timestamps are now written on every dirty flush and restored on startup; stale entries outside the configured window are discarded automatically on load.- Shadow-ban level escalation is now enforced —
playerShadowBanLevelwas incremented and stored but never acted upon. A new config keyshadow_ban.auto_punish_level(default3) defines the threshold at which the level triggers realauto_punishmentand then resets. Requiresauto_punishment.enabled: true. - Firewall script no longer blocks the main thread —
executeFirewallBlockpreviously calledRuntime.getRuntime().exec()synchronously, which could freeze the server if the script was slow. It now runs asynchronously viaProcessBuilderwith a configurable hard timeout (auto_punishment.firewall_timeout_seconds, default10). The player is kicked immediately on the main thread; the OS script executes in the background.
Low severity
unlockIdentifier()now clearssensitiveCommandHistory— previously,/opshield unlockcleared all other tracking maps but leftsensitiveCommandHistoryintact, causing inconsistent state after a manual unlock.getMsgPlain()replaced fragile color-strip logic — manualreplace('&X', "")calls missed several color codes and decorators. Now uses Adventure'sPlainTextComponentSerializerfor correct, future-proof plain-text extraction.- Multi-file audit log rotation —
AuditLoggerpreviously kept only one backup file (audit.log.1), permanently overwriting it on every rotation. Rotation now shifts files:audit.log.1→audit.log.2→ … →audit.log.N. Controlled byaudit.log_retention(default3). - Config validation for
auto_punishment.command— an unrecognized mode with nocustom_commandset now prints a clear console warning on load and reload instead of silently falling back to a potentially unexpected behaviour.
New config keys
| Key | Default | Description |
|---|---|---|
shadow_ban.auto_punish_level |
3 |
Shadow-ban level threshold that triggers auto-punishment |
audit.log_retention |
3 |
Number of rotated audit log backup files to keep |
auto_punishment.firewall_timeout_seconds |
10 |
Max seconds before a hung firewall script is force-killed |
1.4.0Релиз1.21.9, 1.21.10, 1.21.11 · 14 апреля 2026 г.
[1.4.0] — 2026-04-14
Security hardening
- migrated password storage to
op_password_hashso plaintext is no longer kept in config after migration - added PBKDF2 password hashing for new stored credentials
- preserved backward compatibility for older SHA-256 hashes during migration
- made firewall execution explicitly unsafe and opt-in only via
allow_unsafe_firewall_exec - disabled auto-punishment by default to reduce accidental false positives on fresh installs
Logic fixes
- fixed IP-limit detection so it counts unique accounts inside a real rolling time window
- changed OP whitelist enforcement to apply to
/oponly - added lockout count decay after a configurable cooling-off period
- cleaned expired lockouts and expired IP flags automatically on a schedule
- localized shadow-ban fake success messages instead of hardcoding English strings in Java
Performance and maintainability
- replaced repeated async save spawns with a debounced persistent save loop
- replaced synchronous audit file writes with queued async flushes
- added basic audit log rotation
- cached
CommandMapreflection result instead of resolving it on every blocked command - split hashing and audit logging into dedicated helper classes
Permissions and command handling
- added
opshield.op - added
opshield.deop - added
opshield.admin - added
opshield.bypass - kept
/opshield reloadand/opshield unlock <player|ip>as admin management commands
Config changes
- added
op_password_hash - retained
op_passwordonly as a legacy migration input - added
broadcast_on_privilege_change - added
audit.* - added
security.lockout.track_ip - added
security.lockout.count_decay_hours - added
auto_punishment.window_seconds - added
auto_punishment.custom_command - added
auto_punishment.allow_unsafe_firewall_exec - added
ip_limit.auto_punish - added
ip_limit.flag_duration_minutes
Комментарии
Загружаем…