ВЕРСИИ (16)

## [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] - 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: ```java 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: ```java 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) | ---

## [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()` called `PasswordHasher.verify()` synchronously during `onCommand()`, 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 via `runTask()` for all Bukkit API side-effects. Zero blocking on the main thread. - **New status field:** `/opshield status` now 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 `/op` or `/deop` required 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` (default `30`; set `0` to 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 globalAuthCount` caps server-wide concurrent PBKDF2 operations at `MAX_CONCURRENT_AUTH = 4`. Requests over the cap receive `auth_server_busy` and are dropped without queuing. - **Per-sender dedup:** `Map<String, AtomicInteger> authPending` prevents the same player from queuing more than one verification at a time. Excess requests receive `auth_pending`. #### FIX [High] — `cleanupRuntimeState()` ran on the main thread - **Root cause:** `Bukkit.getScheduler().runTaskTimer()` was used instead of `runTaskTimerAsynchronously()`. The cleanup method holds synchronized blocks on `LockoutRecord` objects; under load this briefly stalled the tick. - **Fix:** Scheduler call changed to `runTaskTimerAsynchronously()`. All collections involved are `ConcurrentHashMap`/`ConcurrentLinkedQueue` — safe for async access. #### FIX [Medium] — Shutdown race condition between async periodic flush and `onDisable` sync flush - **Root cause:** `onDisable()` called `flushPersistentDataSync()` while the 200-tick async flush task could be mid-execution. Although `compareAndSet` prevented double saves, the two threads could both have a reference to `dataFile` and compete on the same `YamlConfiguration` serialisation. - **Fix:** `onDisable()` now cancels both async task IDs (`periodicFlushTaskId`, `cleanupTaskId`) **before** calling `flushPersistentDataSync()`, ensuring only one flush can run at shutdown. #### FIX [Medium] — `ShadowBanManager` used `HashMap` for command→message mapping - **Root cause:** `HashMap` has undefined iteration order. Commands like `deop op`, `ban-ip`, or `give op` could match the wrong message key depending on JVM run, leading to non-deterministic fake responses. - **Fix:** Replaced with `LinkedHashMap` preserving 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: 2` was introduced in v1.8.0 but `reloadConfiguration()` never checked it. There was no warning when admins ran an old config against a new build. - **Fix:** `reloadConfiguration()` now compares `config-version` against `EXPECTED_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:** `authenticatedSessions` was 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 from `authenticatedSessions` on disconnect. --- ### ✨ New Features #### Authenticated Session Tokens - First successful `/op` or `/deop` authentication grants a timed session. - Subsequent privilege commands within the window skip password entry. - Session duration: `security.session_timeout_minutes` (default `30`; `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 1. **No breaking changes** — existing `config.yml` and `data.yml` are fully compatible. 2. **New config key** — add `security.session_timeout_minutes: 30` (or let the default apply on first reload). 3. **config-version** is auto-bumped from `2` → `3` on first reload; a one-time warning will appear in console. 4. **Permission setup** is unchanged from v1.8.0. ### 🔮 Planned for v1.10.0 - Extract `AutoPunishmentManager` — move all ban/kick/firewall logic out of `OPShield.java` - Extract `IpLimitManager` — move IP tracking and flagging - Extract `CommandRestrictionManager` - Unit tests for `LockoutManager` and `ShadowBanManager` - Consider Argon2id as an optional stronger hashing algorithm ---

## [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 `ConcurrentHashMap`s (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 ---

## [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: 1. No database migration needed 2. All configuration stays the same 3. No command changes 4. Direct drop-in JAR replacement ### 🔮 Future Work (v1.8.0+) Recommended further refactoring: - Extract `AutoPunishmentManager` for ban/kick logic - Extract `IpLimitManager` for IP tracking - Extract `CommandRestrictionManager` for command validation - Create interface-based services for better testability - Add unit tests for new manager classes ---

## [1.6.0] — 2026-04-21 ### Bug fixes #### High severity - **`AuditLogger` switched from `FileWriter` to NIO `Files.write()`** — `FileWriter` used 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 use `java.nio.file.Files.write()` with an explicit `StandardCharsets.UTF_8` argument and `StandardOpenOption.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. An `AtomicBoolean fileReady` flag 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 to `MAX_WRITE_RETRIES` (2) times. On final failure a `SEVERE` console 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_hash` in `config.yml` contains 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 constant `UNKNOWN_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_clear` incorrectly 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: false` added to `plugin.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_fail` message 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` (default `120000`, range `10000`–`1000000`). Increasing the value raises brute-force resistance at the cost of slightly slower verification on each `/op` or `/deop` attempt. Existing stored hashes are unaffected — they carry their own iteration count. - **`firewall_script` config entry now includes OS-specific examples** — the config comment now shows both a Linux `iptables` example and a Windows `netsh` example 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] — 2026-04-19 ### Bug fixes #### Medium severity - **`sensitiveCommandHistory` now persisted to `data.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** — `playerShadowBanLevel` was incremented and stored but never acted upon. A new config key `shadow_ban.auto_punish_level` (default `3`) defines the threshold at which the level triggers real `auto_punishment` and then resets. Requires `auto_punishment.enabled: true`. - **Firewall script no longer blocks the main thread** — `executeFirewallBlock` previously called `Runtime.getRuntime().exec()` synchronously, which could freeze the server if the script was slow. It now runs asynchronously via `ProcessBuilder` with a configurable hard timeout (`auto_punishment.firewall_timeout_seconds`, default `10`). The player is kicked immediately on the main thread; the OS script executes in the background. #### Low severity - **`unlockIdentifier()` now clears `sensitiveCommandHistory`** — previously, `/opshield unlock` cleared all other tracking maps but left `sensitiveCommandHistory` intact, causing inconsistent state after a manual unlock. - **`getMsgPlain()` replaced fragile color-strip logic** — manual `replace('&X', "")` calls missed several color codes and decorators. Now uses Adventure's `PlainTextComponentSerializer` for correct, future-proof plain-text extraction. - **Multi-file audit log rotation** — `AuditLogger` previously 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 by `audit.log_retention` (default `3`). - **Config validation for `auto_punishment.command`** — an unrecognized mode with no `custom_command` set 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] — 2026-04-14 ### Security hardening - migrated password storage to `op_password_hash` so 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 `/op` only - 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 `CommandMap` reflection 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 reload` and `/opshield unlock <player|ip>` as admin management commands ### Config changes - added `op_password_hash` - retained `op_password` only 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`

## [1.3.0] — 2026-03-28 ### 🔥 New Security Features #### Auto-Punishment (Automatic Punishment) - Automatically ban-ip or execute punishment command when players attempt sensitive commands too many times - Config: `auto_punishment.threshold` - maximum allowed attempts - Supports multiple modes: `ban-ip`, `ban`, `kick`, `firewall`, or custom command - Firewall script: Execute system commands (iptables/ufw) to block IP at network level - Configurable sensitive commands list: `sensitive_commands` #### IP-Limit (Multi-account Detection) - Track number of accounts connecting from the same IP - Auto-flag and punish if exceeding `max_accounts` within time window - Default: 3 accounts / 5 minutes - Integrates with Auto-Punishment to automatically block suspicious IPs #### Shadow Ban / Fake Success (Deceptive) - Instead of showing "no permission", display fake success messages - Attackers think they succeeded but nothing actually happens - Buys time for admin to investigate and handle attackers - Fake messages for commands: clear, kill, ban, gamemode, tp, effect, give #### Anti-Spam Console Log - Blocked commands no longer appear in console log - Only logged to audit.log to prevent server console spam ### 🛡️ Security Improvements - Auto-punishment exempt for OP and whitelist-admin - IP tracking with automatic time window cleanup - Full audit logging for all auto-punishment actions ---

## [1.2.1] — 2026-03-16 ### ✨ New Features - **OP Command Restriction** — Added ability to restrict specific commands even for OPs. This helps prevent admin abuse and limits potential damage from backdoors. - New config options: `restrict_op_commands` (boolean) and `blocked_op_commands` (list). - Console remains exempt from these restrictions for emergency recovery.

## [1.2.0] — 2026-03-15 ### 🐛 Bug Fixes (7 fixes) #### BUG-1 — Deprecated `ChatColor` API replaced with Adventure `LegacyComponentSerializer` - **Root cause:** `getMsg()` used `ChatColor.translateAlternateColorCodes('&', msg)`, which is deprecated in Paper 1.21 and produces build warnings. - **Fix:** Replaced with `LegacyComponentSerializer.legacyAmpersand().deserialize(raw)`. All `sendMessage()` calls now pass `Component` objects. Added helper methods `send(sender, key)` and `sendReplaced(sender, key, ...)` to centralise message dispatch. `Bukkit.broadcastMessage()` replaced with `Bukkit.broadcast()`. #### BUG-2 — `allow_op_reload: false` had no effect on console - **Root cause:** The reload handler checked `!allowOpReload && sender instanceof Player` first, so console senders (who are not `instanceof Player`) skipped the check entirely and were always permitted. - **Fix:** The behaviour is now explicit and documented: `allow_op_reload` intentionally controls **in-game players only**. Console is always allowed to reload. Added a clear comment in code and updated the README to document this intent. The help message was also updated to reflect the correct usage. #### BUG-3 — `savePersistentData()` blocked the main thread with I/O - **Root cause:** Every wrong password attempt triggered `savePersistentData()` synchronously on the main server thread, writing to `data.yml` via file I/O which can stall the tick cycle on loaded servers. - **Fix:** `savePersistentData()` now snapshots the maps on the main thread (thread-safe, fast), then dispatches the actual file write via `Bukkit.getScheduler().runTaskAsynchronously()`. `onDisable()` still saves synchronously because async tasks may not execute during shutdown. #### BUG-4 — No way to manually unlock a locked-out player - **Root cause:** When a player was locked out there was no command to lift the lockout. Admins had to either wait for the timer or delete `data.yml` entirely. - **Fix:** Added `/opshield unlock <player|ip>` command. Accepts either a player name (matched case-insensitively) or an IP address (dots automatically converted to underscores to match the storage key). Clears `failedAttempts`, `lockoutTimestamps`, and `lockoutCount` for the matching key. Requires `opshield.unlock` permission (default: op). New `unlock_success` and `unlock_not_found` message keys added to all language files. #### BUG-5 — Lockout reset allowed infinite brute-force with fixed delay - **Root cause:** When a lockout expired, `isLockedOut()` cleared both `lockoutTimestamps` **and** `failedAttempts`, resetting the counter to zero. An attacker could attempt `max-attempts - 1` wrong passwords, wait out the lockout, and repeat indefinitely without ever receiving a longer penalty. - **Fix:** Introduced `lockoutCount` (persisted in `data.yml` as `lockout_count`). Each time a lockout is triggered, the count increments and the duration doubles: `lockoutDurationMinutes * 2^(count-1)`, capped at 24 hours. On successful authentication the `failedAttempts` and `lockoutTimestamps` are cleared, but `lockoutCount` is preserved so repeated abuse continues to receive longer lockouts. The unlock command (`BUG-4`) clears all three maps. #### BUG-6 — Command block / server-console bypass is documented (not a code bug) - **Root cause:** Lockout and whitelist checks are gated on `sender instanceof Player` — command blocks and other plugins dispatching `/op` bypass these checks by design because they have no IP address. - **Fix:** Added explicit documentation in README explaining this is intentional. Server administrators are advised to restrict physical/panel access to prevent console-level abuse. #### BUG-7 — `CommandMap` reflection failure was fully silent - **Root cause:** If `getCommandMap()` reflection failed (e.g., custom server forks, future API changes), the exception was caught by a bare `catch (Exception ignored)` block with no log output, making diagnosis impossible. - **Fix:** Replaced `ignored` with a `getLogger().fine(...)` call that logs the failure at FINE level with the command name and exception message. This appears in debug logs without spamming the console under normal operation. ### ✨ New Features - `/opshield unlock <player|ip>` — manually clear lockout for a player or IP (`opshield.unlock` permission) - `/opshield` (no args) — now shows a brief help line instead of an error - `/ops` alias added for `/opshield` - Exponential backoff: lockout duration doubles per repeat offender (capped at 24 h) - Language file defaults auto-merged from jar — new keys appear automatically in existing language files without requiring users to recreate them ### 🔧 Other Changes - `pom.xml`: version → 1.2.0; switched dependency from `spigot-api` to `paper-api` (Paper bundles Adventure — no extra shade required); compiler source/target bumped from Java 17 → Java 21 (`maven.compiler.release`) - `plugin.yml`: version → 1.2.0; added `opshield.unlock` permission; updated descriptions; added `/ops` alias - All 3 language files (`en`, `vn`, `ru`): added `unlock_success` and `unlock_not_found` keys; updated `lockout_message` to mention increasing duration ---

## [1.1.1] — 2026-03-11 ### Fixed - **Alias bypass (EssentialsX and other plugins):** Non-OPs could use blocked commands via aliases (`/gm`, `/gms`, `/tpa`, `/tphere`, etc.) because the plugin compared only the typed text. Commands are now resolved to their canonical name via Bukkit's `CommandMap` before checking the block list, so aliases are caught automatically without needing to enumerate them in config. - **Non-OP players could not use `/op <player> <password>`:** `"op"` was listed in `blocked_commands`, causing `PlayerCommandPreprocessEvent` to cancel the command before it ever reached `onCommand`. Password-based OP now works correctly for non-OP players. - **Password exposed in `logs/latest.log`:** `/op` and `/deop` events were not cancelled before Bukkit logged them, so the password appeared in plain text in console output and log files. The event is now cancelled immediately and dispatched directly to `onCommand` internally. - **`getRemainingLockoutTime` showed inflated minutes:** Integer division added an extra minute at every boundary (e.g. 5 seconds remaining showed "1 minute"). Fixed to ceiling division. ---

fixed

# 🛡️ Changelog - OPShield v1.0.3 All notable changes to the **OPShield** plugin in this version are documented below. --- ## [1.0.3] — 2026-03-07 ### 🌍 Multi-Language Support * **Full Localization:** The plugin now supports multiple languages. All messages have been moved from `config.yml` to separate language files. * **Included Languages:** * **English** (`en.yml`) - Default. * **Vietnamese** (`vn.yml`). * **Russian** (`ru.yml`). * **Dynamic Language Switching:** Change the language in `config.yml` and use `/opshield reload` to switch instantly without a server restart. * **Auto-Resource Generation:** The plugin automatically creates default language files in the plugin folder if they are missing. ### ⚙️ Configuration Changes * Added `language` option to `config.yml`. * Removed hardcoded messages from `config.yml` to minimize clutter and improve maintainability. ### 🛠️ Internal Improvements * Built a flexible localization manager to handle message loading and caching. * Ensured consistency across color codes and placeholders in all translations. ---

# Changelog - OPShield v1.0.1 - All notable changes to the OPShield plugin in this version are documented below. - [1.0.1] - 2026-03-07 🔴 Critical Security Fixes Inverted Logic Fix: Resolved a critical bug where restrict_admin_commands: true would block OPs instead of protecting them. Existing OPs are now correctly exempted from command restrictions. SHA-256 Password Hashing: Upgraded password storage and comparison from plain-text to SHA-256 hashing. Passwords are now securely hashed in memory to prevent exposure. Secure Default Password: Added an automatic check for the default password (secure123). The plugin now generates a strong 16-character random password if the default is detected. - 🛡️ New Security Features Console Password Requirement: Added require_password_from_console (Default: false). When enabled, the console must provide the secret password to use /op or /deop. /deop Protection: Extended password authentication to the /deop command, preventing unauthorized removal of admin rights. Wildcard/Prefix Blocking: Introduced blocked_command_prefixes. Admins can now block entire namespaces (e.g., essentials:, minecraft:) to prevent bypasses via aliases. Audit Logging: Implemented a dedicated audit log system. All authentication attempts and blocked command actions are now logged with timestamps in plugins/OPShield/audit.log. - ⚙️ Configuration Changes Added require_password_from_console setting. - Added blocked_command_prefixes list. - Updated config.yml comments for better clarity on security features. Added localization keys for de-op operations. - 🛠️ Internal Improvements - Registered /op and /deop as internal overrides in plugin.yml for more reliable interception. Normalized command processing to be more robust against casing and prefix bypasses.