Mods Whitelist

A secure modpack enforcement mod for Minecraft Forge and NeoForge.

This description currently only applies to Minecraft 1.21.1-2.0.0 and 1.20.1-3.0.0 . Other versions will be updated gradually to match the same feature and config structure over time.

Due to changes in modern Minecraft networking, reliable client mod verification is no longer possible using a server-only approach.
This project therefore uses a server + lightweight client verification model to provide accurate and tamper-resistant mod checks.

✨ Features

Both-side required mods
Enforce mods that must exist on both server and client.
Client-only required mods
Require specific client-side mods even when they are not installed on the server.
Client-only optional mods
Allow selected client-side mods such as performance, QoL, or visual mods without making them mandatory.
Server-only mod separation
Keep server-only mods documented separately so they do not end up in the required client list.
Denied mods and files
Instantly reject players using forbidden mods or blocked jar files.
Strict mode
When enabled, only explicitly allowed mods and files are accepted.
File integrity verification (SHA-256)
Optional hardcore mode that verifies exact filenames and hashes.
Controlled collect workflow
Automatically classify mods and files using a trusted reference client.
Legacy config migration
Automatically migrates old single-file configs to the new multi-file structure.
Configurable kick messages
Supports custom messages, clickable pack links, and clearer formatted kick reasons.
Server-authoritative
All decisions are enforced by the server. No analytics, tracking, or third-party services.

📁 Config Structure

Modwhitelist uses a multi-file config layout:

config/modwhitelist/
  settings.json
  both_side_required.json
  client_required.json
  client_optional.json
  server_only.json
  deny.json

File overview

`settings.json`

Global settings such as:

strict
strictFiles
collectMode
collectWhitelist
customMessage
packLink

`both_side_required.json`

Mods and files that must exist on both server and client.

`client_required.json`

Client-only mods and files that are still required.

`client_optional.json`

Client-only mods and files that are allowed but optional.

`server_only.json`

Mods and files that are only used on the server.

`deny.json`

Hard blacklist for forbidden mods and files.

🔒 Privacy / Data Protection

Only technical mod identifiers and optional file hashes are transmitted
No personal data is collected or stored
No tracking, analytics, or third-party services
Server logs only contain minimal moderation information such as kick reasons

🛠 Recommended Setup / Collect Workflow

Modwhitelist includes a controlled collect mode to help generate the initial config structure safely.

1. Start the server once

On first start, Modwhitelist creates the config folder and the required JSON files automatically.

2. Add a trusted admin UUID

Open config/modwhitelist/settings.json and add the UUID of a trusted admin to collectWhitelist.

Example:

{
  "collectWhitelist": [
    "1696566b-f0c6-473c-89b0-0f16d41a9608"
  ]
}

Only players listed there are allowed to join while collect mode is active.

3. Enable collect mode

Run:

/modwhitelist collect on

This temporarily disables strict mode and allows the trusted setup client to join.

4. Join with the reference client pack

Join the server once with the exact client setup you want to use as your baseline.

During this process, Modwhitelist compares:

server mods/files
client mods/files

5. Automatic classification

After the trusted client joins successfully, Modwhitelist automatically classifies entries into:

both_side_required.json
client_optional.json
server_only.json

6. Review client-only entries

Any client-only mods detected during collect are placed into client_optional.json by default.

If some of these client-only mods should be mandatory, move them manually from:

client_optional.json

to:

client_required.json

This is intentional, because only the server admin can decide which client-only mods should actually be required.

7. Collect mode finishes automatically

After a successful collect run:

collectMode is disabled automatically
strict is restored automatically

Recommended setup logic

Use the files like this:

both_side_required.json for mods required on both sides
client_required.json for client-only mandatory mods
client_optional.json for client-only allowed mods
server_only.json for documentation and separation of server-only mods
deny.json for mods or files that should never be allowed

📜 Commands

All commands require operator permissions.

`/modwhitelist reload`

Reloads all config files from disk.

Use this after manually editing the JSON files.

`/modwhitelist init`

Creates the multi-file config structure if it does not exist yet.

In most cases this is only needed for fresh setups. If configs already exist or were migrated automatically, you usually do not need this command.

`/modwhitelist collect on`

Enables collect mode and temporarily disables strict mode.

`/modwhitelist collect off`

Disables collect mode.

`/modwhitelist collect clear`

Clears the automatically collected manifests:

both_side_required.json
client_optional.json
server_only.json

This does not clear client_required.json.

🚫 deny.json

deny.json is the hard blacklist.

Everything listed here is always blocked, even when strict=false.

Use it for:

cheat mods
xray mods
incompatible mods
specific jar files you never want on the server

Format

{
  "mods": [],
  "files": []
}

Block mods by mod ID

{
  "mods": [
    "xray",
    "freecam",
    "example*"
  ],
  "files": []
}

Notes:

xray blocks exactly that mod ID
example* blocks everything starting with example
wildcard matching with * is supported

Block files by filename

{
  "mods": [],
  "files": [
    {
      "name": "badmod.jar",
      "sha256": "*"
    }
  ]
}

This blocks the file by filename only.

Block one exact file version

{
  "mods": [],
  "files": [
    {
      "name": "badmod-1.0.0.jar",
      "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
    }
  ]
}

This only blocks that exact file version.

Recommended usage

Use mods for normal blacklist entries
Use files with sha256: "*" if you want to block by jar filename
Use a real SHA-256 hash only if you want to block one exact file version

deny.json is checked before normal whitelist and strict handling.

That means:

matching entries are rejected immediately
this also applies when strict=false

Notes

Old single-file configs are migrated automatically on first start
Auto-collect overwrites:
- both_side_required.json
- client_optional.json
- server_only.json
client_required.json is intentionally kept manual so admins can decide which client-only mods are truly required
Colored kick messages help players immediately see what is missing, blocked, or not allowed

Mod Whitelist Forge NeoForge