papermc-skill 1.0.0 → 1.1.0

package/docs/10-database-and-storage.md

@@ -1,32 +1,32 @@
-# Penyimpanan Database Asinkron: SQLite & HikariCP di Paper
+# Asynchronous Database Storage: SQLite & HikariCP in Paper
 
-Menyimpan data pemain (uang/ekonomi, statistik level, inventaris kustom, quest) langsung ke file YAML (`config.yml` atau `player.yml`) sering kali menjadi lambat dan berisiko korup jika server memiliki ribuan pemain unik.
+Storing player profiles (economy balances, levels, custom inventories, quests) directly into YAML files (`config.yml` or `player.yml`) degrades performance rapidly and invites file corruption when scaling to thousands of unique users.
 
-Standar industri untuk penyimpanan data di plugin produksi adalah menggunakan database relasional (seperti **SQLite** untuk server mandiri, atau **MySQL/PostgreSQL via HikariCP** untuk jaringan multi-server/BungeeCord).
+The industry standard for production storage is relational databases (**SQLite** for standalone single servers, or **MySQL / PostgreSQL via HikariCP** for multi-server BungeeCord/Velocity networks).
 
 ---
 
-## 1. Aturan Emas Database di Minecraft
+## 1. The Golden Rule of Minecraft Database Access
 
-> **DILARANG KERAS menjalankan koneksi database, query `SELECT`, atau `INSERT/UPDATE` di main/region tick thread.**
-> Query yang memakan waktu 50ms akan langsung menyebabkan TPS server turun dan pemain mengalami lag atau rollback.
+> **NEVER open database connections, execute `SELECT` queries, or run `INSERT/UPDATE` statements on the main or region tick threads.**
+> A single query taking 50ms immediately causes TPS drops, player rubberbanding, and tick watchdog warnings.
 
-Gunakan selalu **Asynchronous Execution (`CompletableFuture`)** yang me-return hasil ke thread region pemain saat selesai.
+Always execute database operations via **Asynchronous Threads (`CompletableFuture`)**, and dispatch results back to the player's entity scheduler when mutating game state.
 
 ---
 
-## 2. Menyiapkan HikariCP (Connection Pooling)
+## 2. Configuring HikariCP (High-Performance Connection Pooling)
 
-HikariCP adalah library connection pool tercepat di ekosistem Java (digunakan secara ekstensif oleh **LuckPerms**).
+HikariCP is the fastest connection pool in the Java ecosystem (utilized extensively by **LuckPerms**).
 
-### Dependensi Gradle:
+### Gradle Dependency:
 ```kotlin
 dependencies {
     implementation("com.zaxxer:HikariCP:5.1.0")
 }
 ```
 
-### Inisialisasi DataSource:
+### Initializing the DataSource:
 ```java
 package com.example.plugin.database;
 
@@ -46,12 +46,12 @@ public final class DatabaseManager {
         config.setUsername(user);
         config.setPassword(password);
 
-        // Pengaturan Pool HikariCP yang Direkomendasikan
+        // Recommended HikariCP Pool Settings
         config.setMaximumPoolSize(10);
         config.setMinimumIdle(2);
-        config.setConnectionTimeout(10000); // 10 detik
-        config.setIdleTimeout(600000);      // 10 menit
-        config.setMaxLifetime(1800000);     // 30 menit
+        config.setConnectionTimeout(10000); // 10 seconds
+        config.setIdleTimeout(600000);      // 10 minutes
+        config.setMaxLifetime(1800000);     // 30 minutes
         config.setPoolName("PluginHikariPool");
 
         this.dataSource = new HikariDataSource(config);
@@ -60,7 +60,7 @@ public final class DatabaseManager {
     public void initSQLite(String filePath) {
         HikariConfig config = new HikariConfig();
         config.setJdbcUrl("jdbc:sqlite:" + filePath);
-        config.setMaximumPoolSize(1); // SQLite hanya boleh 1 writer pool
+        config.setMaximumPoolSize(1); // SQLite only supports a single writer
         config.setPoolName("PluginSQLitePool");
 
         this.dataSource = new HikariDataSource(config);
@@ -80,9 +80,9 @@ public final class DatabaseManager {
 
 ---
 
-## 3. Repositori Asinkron dengan `CompletableFuture`
+## 3. Asynchronous DAO Pattern with `CompletableFuture`
 
-Buat Data Access Object (DAO) yang memisahkan eksekusi SQL dari logika game:
+Construct a Data Access Object (DAO) to cleanly decouple raw SQL execution from in-game mechanics:
 
 ```java
 package com.example.plugin.database;
@@ -120,7 +120,7 @@ public final class PlayerRepository {
         }
     }
 
-    // Membaca data pemain secara asinkron
+    // Read player balance asynchronously
     public CompletableFuture<Integer> getCoinsAsync(UUID uuid) {
         return CompletableFuture.supplyAsync(() -> {
             try (Connection conn = databaseManager.getConnection();
@@ -136,17 +136,17 @@ public final class PlayerRepository {
             } catch (SQLException e) {
                 e.printStackTrace();
             }
-            return 0; // Default jika data belum ada
+            return 0; // Default fallback
         }, dbExecutor);
     }
 
-    // Menyimpan data pemain secara asinkron (Upsert)
+    // Persist player balance asynchronously
     public CompletableFuture<Void> setCoinsAsync(UUID uuid, int coins) {
         return CompletableFuture.runAsync(() -> {
             try (Connection conn = databaseManager.getConnection();
                  PreparedStatement stmt = conn.prepareStatement(
                      "INSERT INTO player_data (uuid, coins) VALUES (?, ?) " +
-                     "ON CONFLICT(uuid) DO UPDATE SET coins = excluded.coins;" // SQLite & Postgres (gunakan ON DUPLICATE KEY UPDATE untuk MySQL)
+                     "ON CONFLICT(uuid) DO UPDATE SET coins = excluded.coins;" // SQLite / PostgreSQL
                  )) {
                 stmt.setString(1, uuid.toString());
                 stmt.setInt(2, coins);
@@ -165,21 +165,21 @@ public final class PlayerRepository {
 
 ---
 
-## 4. Menggunakan Hasil Database di Event Listener
+## 4. Applying Query Results in Event Listeners
 
-Saat data selesai di-fetch dari database, gunakan scheduler Folia/Paper pemain untuk menerapkan perubahannya ke objek Bukkit:
+When asynchronous database queries resolve, schedule execution back to the player's entity scheduler to mutate Bukkit state:
 
 ```java
 @EventHandler
 public void onPlayerJoin(PlayerJoinEvent event) {
     Player player = event.getPlayer();
 
-    // Fetch data koin di thread asinkron
+    // Fetch coins asynchronously off the tick thread
     playerRepository.getCoinsAsync(player.getUniqueId()).thenAccept(coins -> {
-        // Terapkan hasil ke entity pemain di thread region pemain
+        // Dispatch result safely onto the player's entity region thread
         player.getScheduler().run(plugin, task -> {
             player.sendActionBar(MiniMessage.miniMessage().deserialize(
-                "<gold>Saldo Koin: <yellow>" + coins + "</yellow></gold>"
+                "<gold>Balance: <yellow>" + coins + " Coins</yellow></gold>"
             ));
         }, null);
     });

package/docs/11-security-and-exploit-prevention.md

@@ -0,0 +1,233 @@
+# Masterclass Guide: Security & Exploit Prevention in Paper & Folia Plugins
+
+Public Minecraft servers face hostile environments: modified clients (*hacked clients*), automated packet bots, and malicious players probing for item duplication glitches (*dupe exploits*) or server-crashing packet freezes. This masterclass guide provides authoritative architectural patterns to ensure your Paper and Folia plugins remain completely exploit-proof.
+
+---
+
+## 1. Item Duplication Prevention (Dupe Glitch Elimination)
+
+Item duplication exploits almost universally originate from *race conditions* between inventory interface events, fast clicking, or off-thread asynchronous mutations.
+
+### Hazard 1: Off-Thread / Asynchronous Inventory Mutation
+```java
+// ❌ CRITICAL HAZARD: Mutating inventory off-thread!
+CompletableFuture.runAsync(() -> {
+    player.getInventory().removeItem(item); // Race condition! Can duplicate if clicked concurrently
+});
+```
+**Absolute Rule**: Minecraft's inventory state is **not thread-safe**. Whenever querying, removing, or adding items to a player, execution **must** occur on the player's entity region thread:
+```java
+// ✔️ SAFE: Execute on the Entity Scheduler
+player.getScheduler().run(plugin, task -> {
+    if (player.getInventory().containsAtLeast(item, requiredAmount)) {
+        player.getInventory().removeItem(item);
+        // Proceed with transaction
+    }
+}, null);
+```
+
+### Hazard 2: Inventory Drag & Fast-Click Race Conditions
+Cheating clients can emit rapid click or drag packets to pick up an item before cancellation handlers finish evaluating.
+```java
+@EventHandler(priority = EventPriority.HIGHEST, ignoreCancelled = true)
+public void onInventoryClick(InventoryClickEvent event) {
+    if (!(event.getInventory().getHolder() instanceof CustomMenuHolder)) {
+        return;
+    }
+
+    // 1. Cancel the event immediately
+    event.setCancelled(true);
+
+    // 2. Prevent fast-click exploits via per-player debounce
+    Player player = (Player) event.getWhoClicked();
+    if (!DebounceManager.canClick(player.getUniqueId(), 200)) {
+        return;
+    }
+
+    // 3. Process only top menu slot actions
+    if (event.getClickedInventory() == event.getInventory()) {
+        processMenuButton(player, event.getSlot());
+    }
+}
+
+@EventHandler
+public void onInventoryDrag(InventoryDragEvent event) {
+    if (event.getInventory().getHolder() instanceof CustomMenuHolder) {
+        event.setCancelled(true); // Always cancel drag events in custom menus
+    }
+}
+```
+
+---
+
+## 2. Monetary Safety & Numeric Bounds Validation
+
+Floating-point precision errors and lack of numeric validation are among the most common causes of server economic collapse.
+
+### Exploitation Vectors: `NaN`, `Infinity`, and Negative Numbers
+Malicious players enter unexpected inputs in payment or shop commands, such as:
+- `/pay Alice -1000000` (deducts money from the receiver and credits the sender)
+- `/pay Alice NaN` (corrupts player balance to `NaN` permanently, breaking database constraints)
+- `/pay Alice 99999999999999999999` (overflows 64-bit integers, wrapping amounts into negatives)
+
+### 🟢 Solution: Strict Numeric Bounds Validator
+```java
+public final class EconomyValidator {
+
+    private static final double MIN_TRANSACTION = 0.01;
+    private static final double MAX_TRANSACTION = 1_000_000_000.0;
+
+    public static double validateAmount(double amount) throws IllegalArgumentException {
+        if (!Double.isFinite(amount)) {
+            throw new IllegalArgumentException("Invalid monetary amount (NaN or Infinity)!");
+        }
+        if (amount < MIN_TRANSACTION) {
+            throw new IllegalArgumentException("Minimum transaction amount is $" + MIN_TRANSACTION);
+        }
+        if (amount > MAX_TRANSACTION) {
+            throw new IllegalArgumentException("Transaction amount exceeds allowable limit!");
+        }
+        // Round to 2 decimal places (cents)
+        return Math.round(amount * 100.0) / 100.0;
+    }
+}
+```
+
+---
+
+## 3. PersistentDataContainer (PDC) Anti-Tamper & Cryptographic Hashing
+
+Never rely on an item's `DisplayName` or `Lore` to determine whether an item possesses custom abilities or rare server tiers.
+
+### 🔴 The Vulnerability
+Players can rename normal items using anvils or packet injection to mimic custom gear titles and lore text.
+
+### 🟢 Solution: PDC Verification with Cryptographic Salt
+Store immutable identifiers and cryptographic signatures inside the item's PDC:
+```java
+public class SecureItemManager {
+    private static NamespacedKey KEY_ID;
+    private static NamespacedKey KEY_HASH;
+    private static final String SERVER_SALT = "MySecretSaltKey_2026";
+
+    public static void init(Plugin plugin) {
+        KEY_ID = new NamespacedKey(plugin, "custom_id");
+        KEY_HASH = new NamespacedKey(plugin, "integrity_hash");
+    }
+
+    public static void signItem(ItemStack item, String customId) {
+        item.editMeta(meta -> {
+            String hash = generateSignature(customId, SERVER_SALT);
+            PersistentDataContainer pdc = meta.getPersistentDataContainer();
+            pdc.set(KEY_ID, PersistentDataType.STRING, customId);
+            pdc.set(KEY_HASH, PersistentDataType.STRING, hash);
+        });
+    }
+
+    public static boolean verifyItem(ItemStack item, String expectedId) {
+        if (item == null || !item.hasItemMeta()) return false;
+        PersistentDataContainer pdc = item.getItemMeta().getPersistentDataContainer();
+        String id = pdc.get(KEY_ID, PersistentDataType.STRING);
+        String hash = pdc.get(KEY_HASH, PersistentDataType.STRING);
+
+        if (id == null || hash == null || !id.equals(expectedId)) {
+            return false;
+        }
+        return hash.equals(generateSignature(id, SERVER_SALT));
+    }
+
+    private static String generateSignature(String data, String salt) {
+        return Integer.toHexString((data + salt).hashCode());
+    }
+}
+```
+
+---
+
+## 4. Mitigating Denial of Service (DoS) from Synchronous Chunk Freezes
+
+If a plugin allows teleportation to arbitrary coordinates (e.g. random teleport or `/tppos`), malicious players can request far-flung coordinates (like 30,000,000) to freeze the server main thread while loading dozens of chunks from disk.
+
+### 🟢 Solution: Asynchronous Chunk Teleportation
+```java
+public static CompletableFuture<Boolean> safeTeleportAsync(Player player, Location target) {
+    World world = target.getWorld();
+    int chunkX = target.getBlockX() >> 4;
+    int chunkZ = target.getBlockZ() >> 4;
+
+    // 1. Load target chunk asynchronously without blocking game ticks
+    return world.getChunkAtAsync(chunkX, chunkZ, true).thenCompose(chunk -> {
+        // 2. Once chunk is loaded, execute teleport on player entity scheduler
+        CompletableFuture<Boolean> tpResult = new CompletableFuture<>();
+        player.getScheduler().run(plugin, task -> {
+            boolean success = player.teleport(target);
+            tpResult.complete(success);
+        }, null);
+        return tpResult;
+    });
+}
+```
+
+---
+
+## 5. Preventing SQL Injection & Connection Pool Starvation
+
+### 🔴 The SQL Injection Vulnerability
+```java
+// CRITICAL HAZARD: SQL Injection if input contains quotes
+String sql = "SELECT * FROM users WHERE name = '" + playerName + "'";
+statement.executeQuery(sql);
+```
+
+### 🟢 Solution: PreparedStatements & HikariCP Pool
+```java
+String sql = "SELECT * FROM users WHERE uuid = ?";
+try (Connection conn = dataSource.getConnection();
+     PreparedStatement stmt = conn.prepareStatement(sql)) {
+    stmt.setString(1, playerUuid.toString());
+    try (ResultSet rs = stmt.executeQuery()) {
+        if (rs.next()) {
+            // Process record safely
+        }
+    }
+} catch (SQLException e) {
+    logger.severe("Database error: " + e.getMessage());
+}
+```
+
+---
+
+## 6. Eliminating Memory Leaks from Lingering Bukkit References
+
+Holding references to `Player`, `World`, or `Chunk` instances in static collections prevents the JVM Garbage Collector from freeing gigabytes of world and network connection data:
+
+### 🔴 Memory Leak Pattern
+```java
+public static Map<Player, Long> lastAction = new HashMap<>(); // LEAK: Player never garbage collected!
+```
+
+### 🟢 Clean Architecture
+```java
+// 1. Store UUID primitives only
+public static Map<UUID, Long> lastAction = new ConcurrentHashMap<>();
+
+// 2. Invalidate on PlayerQuitEvent
+@EventHandler
+public void onQuit(PlayerQuitEvent event) {
+    lastAction.remove(event.getPlayer().getUniqueId());
+}
+```
+
+---
+
+## 7. The Exploit-Proof Verification Checklist
+
+- [x] **Zero asynchronous player inventory modifications.**
+- [x] **Inventory click debounce (150-200ms) enforced.**
+- [x] **Monetary inputs validated against `!Double.isFinite()` and bounds.**
+- [x] **Custom items identified via PDC rather than display lore.**
+- [x] **Asynchronous chunk loading used for all dynamic coordinates.**
+- [x] **PreparedStatements used for all database queries.**
+- [x] **UUIDs stored rather than `Player` instances in static caches.**
+- [x] **Player caches invalidated on `PlayerQuitEvent`.**
+- [x] **`folia-supported: true` declared with proper regional scheduling.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "papermc-skill",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Interactive CLI and architectural development skill for modern Paper & Folia Minecraft Java plugins",
   "main": "bin/cli.js",
   "bin": {
@@ -12,6 +12,7 @@
     "templates",
     "docs",
     "skills",
+    "assets",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"