Fiw Mods API

A Fabric 1.20.1 mod that enforces an official modpack whitelist on your Minecraft SMP server. Players with unauthorized mods are kicked; players without the mod time out and are kicked. All verified players are frozen until the check completes.

How it works

1. When a player joins, the server sends a 32-byte random nonce.
2. The client collects all loaded mod IDs + SHA-256 hashes of their JARs, signs the list with HMAC-SHA256, and sends it back.
3. The server verifies the HMAC and checks every mod against whitelist.json:
   • Required mods must be present with a matching hash.
   • Optional mods may be absent; if present their hash must match (unless sha256 is null).
   • Any unknown mod (not in either list) → kick.
4. Players are frozen (cannot move or interact) during the verification window.

The HMAC key is derived from the mod's own compiled bytecode — modifying the JAR breaks the key.

Installation

Server

1. Place fiw-mods-api-*.jar in your server's mods/ folder.
2. Copy whitelist.example.json to config/fiw-mods-api/whitelist.json and fill in your mod hashes.
3. Start the server. The config file is created automatically on first run if absent.

Client

Every player must have fiw-mods-api-*.jar in their mods folder.

Configuration

config/fiw-mods-api/whitelist.json — see whitelist.example.json for the format.

{
  "verification": {
    "timeout_seconds": 10,
    "kick_message": "This is not the official modpack",
    "timeout_message": "Mod verification timed out. Install the official modpack."
  },
  "mods": {
    "required": [
      { "id": "fiw-mods-api", "sha256": "<jar-sha256>" }
    ],
    "optional": [
      { "id": "jei",     "sha256": "<jar-sha256>" },
      { "id": "essential", "sha256": null }
    ]
  }
}

• sha256: null — mod is allowed regardless of version/hash (useful for runtime-loaded sub-libraries like Essential's).
• Players may freely remove optional mods; only extra unknown mods trigger a kick.

Getting SHA-256 hashes

sha256sum mods/*.jar

Or use the included hash-mods.sh helper:

./hash-mods.sh /path/to/your/mods/folder

Hot-reloading the whitelist

/fiwmods reload

Requires OP level 4. No server restart needed.

Commands

Command	Permission	Description
/fiwmods reload	OP 4	Reload whitelist.json from disk

Building

./gradlew build

Output: build/libs/fiw-mods-api-1.0.0.jar

Important: every build produces a new JAR with a different SHA-256. Update fiw-mods-api's hash in whitelist.json and redeploy after each rebuild.

Future plans

• NeoForge 1.21.6 port (planned)

License

GNU General Public License v3.0