OPShield

[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 to AuditLogger.log(). However, AuditLogger.buildLine() also wraps every line with its own timestamp, resulting in output like:

  [2026-05-23 10:00:00] 2026-05-23 10:00:00 | Configuration reloaded.
  

  This affected every audit entry since v1.6.0.
• Fix: Removed the manual timestamp construction from OPShield.audit(). Timestamp formatting is now owned exclusively by AuditLogger.buildLine(). Audit lines now read correctly:

  [2026-05-23 10:00:00] Configuration reloaded.
  

• Impact: Existing rotated log files (audit.log.1 etc.) 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_granted was introduced in v1.9.0 but the corresponding send() call was absent from both completePrivilegeCommand() (session grant path) and handlePrivilegeCommand() (session reuse path). Players had no way to know a session existed or how much time remained.
• Fix:
  • completePrivilegeCommand() now calls sendReplaced(player, "auth_session_granted", "minutes", …) immediately after the session is stored in authenticatedSessions.
  • handlePrivilegeCommand() now calls sendReplaced(player, "auth_session_active", "minutes", …) (with the remaining minutes) on the session-reuse fast-path.
• New language key: auth_session_active added to en.yml, vn.yml, and ru.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 Adventure Component with colour, but PlainTextComponentSerializer.plainText().serialize() then stripped every colour code before wrapping the result in a hard-coded NamedTextColor.YELLOW. Language-file formatting was silently discarded.
• Fix: Removed the unnecessary serialise/re-wrap chain. The Component returned by colorize(fakeMsg) is now sent directly:

  player.sendMessage(colorize(fakeMsg));
  

  Server owners can now apply any Adventure-compatible colour codes (&a, &c, &l, etc.) in their language files and have them rendered correctly.
• Cleanup: Removed now-unused imports NamedTextColor, PlainTextComponentSerializer, and Component from OPShield.java.

FIX [Medium] — LockoutManager.cleanupExpired() discarded backoff count earlier than count_decay_hours intended

• Root cause: cleanupExpired() removed any record whose expiryMs <= now AND attempts == 0. When a lockout expired naturally, isLockedOut() set expiryMs = 0 and attempts = 0 (intentionally preserving count for exponential backoff). On the very next cleanup tick (≤ 60 s later), the cleanup predicate matched and deleted the entire record, including count. The security.lockout.count_decay_hours config key had no practical effect: the backoff counter was always reset within one cleanup cycle after each lockout expired.
• Fix: cleanupExpired() now accepts a decayMs parameter (derived from lockoutDecayHours in OPShield). A record is only removed when both conditions are true:
  1. No active lockout and no in-progress attempts.
  2. The time elapsed since lastLockoutAtMs exceeds decayMs. Exponential backoff now behaves as documented.
• API change (internal): LockoutManager.cleanupExpired() → cleanupExpired(long decayMs). No external callers; internal call site updated in OPShield.cleanupRuntimeState().

FIX [Medium] — /opshield reload blocked by allow_op_reload: false even for players with explicit opshield.reload permission

• Root cause: In handleManagementCommand(), the allow_op_reload flag was evaluated before the permission check. A player with an explicit opshield.reload grant from a permissions plugin was still denied when allow_op_reload: false, making the permission effectively meaningless.
• Fix: The permission check (opshield.reload) now runs first. The allow_op_reload flag 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() uses player.getAddress().getAddress().getHostAddress(). Behind a proxy, this resolves to the proxy's own address (commonly 127.0.0.1 or a private RFC-1918 range), not the connecting client's real IP. IP-based lockout mirroring and ip_limit tracking 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 when debug: true and 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 to AuditLogger), 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)

---