Mod Whitelist Forge NeoForge

Changelog – ModWhitelist (Forge 1.18.2)

✨ Feature

• Complete rewrite of the ModWhitelist system for Forge 1.18.2
• Client companion based verification
  • Server actively requests a mod scan from the client on join
  • Client reports loaded mod IDs and mod file SHA-256 hashes
• Strict mod ID enforcement
  • Required mods must be present
  • Extra mods are rejected unless explicitly allowed
• Hardcore file integrity enforcement
  • Enforces exact modpack integrity using mod file names and SHA-256 hashes
  • Prevents modified or replaced mod JAR files
• Client-only mod support
  • Client-only mod IDs can be explicitly allowed
  • Client-only mod files are validated if present
• One-time client-only collect mode
  • Allows a whitelisted player to join once with additional client mods
  • Automatically collects:
    • client-only mod IDs into allowClientOnly
    • client-only mod files (name + SHA-256) into clientOnlyFiles
  • After a successful collection run:
    • strict is automatically enabled
    • collectClientOnly is automatically disabled
• Automatic modpack generation
  • /modwhitelist generate scans installed server mods
  • Generates required mod ID list and full /mods file manifest
  • Writes results directly to configfile

🔧 Improvement

• Much more reliable enforcement compared to the legacy Forge 1.18.2 implementation
• Cleaner and more informative kick messages
  • Supports custom messages and modpack download links
• Improved logging for setup, collect mode, and debugging

🧩 Refactor

• Removed legacy mixin-heavy join blocking system
• Replaced fragile early-login hooks and packet suppression logic
• Reworked internal validation flow to be deterministic and state-driven
• Centralized config normalization and validation logic

📦 Modpack/Config

• Deterministic and stable config output
  • All relevant lists are automatically:
    • de-duplicated (case-insensitive)
    • sorted alphabetically
• Affects:
  • allowed
  • allowClientOnly
  • allowedFiles
  • clientOnlyFiles
  • deny
• Configs from very old Forge versions are not compatible
  → Regenerate using /modwhitelist generate

⚙️ Compatibility

• Due to modern Minecraft networking limitations:
  • Pure server-side mod verification is no longer possible
  • Client companion approach is effective against unmodified clients
  • Not cryptographically tamper-proof against fully modified clients

🐛 Fix

• Fixed unreliable join blocking present in the legacy Forge version
• Fixed inconsistent modpack enforcement caused by timing-sensitive login hooks
• Fixed non-deterministic config ordering leading to unnecessary diffs