OPShield

[1.8.0] - 2026-04-28 — Manager Refactor, Security Hardening & Quality Improvements

🔒 Security Fixes

CRITICAL — Permission Default Changed

• opshield.admin default changed from op → 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.admin to your OP group in your permission plugin
• All child permissions (opshield.reload, opshield.unlock, opshield.op, opshield.deop) default changed from op → false for the same reason
• Added opshield.* wildcard permission for convenience

🏗️ Architecture Improvements

LockoutManager — Full Refactor

• Introduced LockoutRecord inner class consolidating 5 separate ConcurrentHashMaps (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 when track_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
• LockoutManager is now the single source of truth for all lockout state

ShadowBanManager — Full Refactor

• Shadow-ban levels now owned by ShadowBanManager (previously a raw ConcurrentHashMap in OPShield.java)
• getFakeMessage() is no longer static; it accepts a MessageProvider functional 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 playerShadowBanLevel map with delegation to ShadowBanManager
• Added /opshield status command for runtime diagnostics (shows active levels, flagged IPs, queue sizes)
• Added debugLog() helper — controlled by debug: false config key; never exposes sensitive info in production

✨ New Features

• debug mode (debug: false in config.yml) — enables verbose internal logging for troubleshooting without recompiling
• /opshield status — new sub-command with opshield.status permission; reports shadow-ban level count, flagged IPs, sensitive-history windows, auto-punishment state
• security.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; plain format 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 messages
• LockoutManager.ipLimitMap was unused — recordIpConnection() was called but the data was never read. Removed; IP limit tracking remains in OPShield.java pending IpLimitManager extraction
• PasswordHasher.upgradeHashIfNeeded() (NEW) — isLegacyHash() existed in 1.7.0 but there was no code path to actually upgrade the stored hash. Now the main class calls upgradeHashIfNeeded() after each successful login when auto_upgrade_legacy_hash: true
• HASH_FORMAT_VERSION constant (NEW) — the string "pbkdf2" was scattered as a magic literal across PasswordHasher; centralised to a named constant

🔧 Build Improvements

• maven-compiler-plugin 3.13.0 added with explicit <release>21</release> and <parameters> flag
• maven-shade-plugin 3.6.0 added (no relocations yet, but scaffold is ready for future bundled deps)
• maven-surefire-plugin 3.2.5 added 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_level default raised from 3 → 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

1. Permission plugin setup required — add opshield.admin to your OP group (see CRITICAL note above)
2. data.yml is auto-migrated from v1.7.0 format on first boot — no manual action needed
3. All configuration keys are backwards-compatible; new keys use sensible defaults
4. Old lockout_timestamps / failed_attempts / lockout_count / last_lockout_at sections in data.yml are read on upgrade and merged into lockout_records; old sections are replaced on next save

🔮 Planned for v1.9.0

• Extract AutoPunishmentManager — move all ban/kick/firewall logic out of OPShield.java
• Extract IpLimitManager — move IP tracking and flagging
• Extract CommandRestrictionManager — move matchesConfiguredCommand logic
• Add unit tests for LockoutManager and ShadowBanManager
• Consider Argon2id as an optional stronger hashing algorithm

---