monban (Whitelist)

monban is a whitelist, access-control, and permissions plugin with explicit ONLINE, OFFLINE, and FLOODGATE player identities. It supports standalone Bukkit/Spigot and Paper/Folia servers, and can act as the central access authority for a Velocity network with Geyser/Floodgate support, player groups, scoped backend access, and synchronized backend permissions.

Supported platforms

The Paper/Folia artifact is a Paper plugin and is separate from the Bukkit/Spigot compatibility artifact. Hybrid authentication-flow selection belongs to Velocity; the Paper/Folia plugin does not implement deployment.mode: VELOCITY.

Features

• Explicit ONLINE, OFFLINE, and FLOODGATE identities instead of inferring trust from the presence of a UUID.
• Optional Geyser/Floodgate integration on Velocity for authenticated Bedrock players.
• Player groups separate from Velocity SERVER_GROUP definitions.
• Group and direct player permissions for proxy and backend plugins.
• NETWORK, SERVER_GROUP, and SERVER scopes for access rules and permissions.
• Group access grants for individual backend servers and server groups.
• One /monban whitelist administration model across supported platforms.
• Runtime /monban whitelist enable and /monban whitelist disable.
• Automatic ONLINE profile lookup by player name, with explicit UUID input still available.
• Interactive whitelist and scoped-access lists with pagination and filter-preserving navigation.
• Network-wide whitelist enforcement on Velocity.
• Per-backend OPEN and GRANT_REQUIRED access policies.
• /monban lookup <player> on Velocity for identity and whitelist status details.
• /monban status on Velocity for a runtime access summary.
• Effective access inspection with group and direct-grant origins.
• Optional Velocity hybrid ONLINE / OFFLINE authentication-flow selection.
• Centralized Velocity state synchronization to Bukkit and Paper backends.
• Local backend permissions without requiring LuckPerms.
• Permission-aware command help and backend command-tree refresh after permission updates.
• Floodgate administration across whitelist, scoped access, groups, and direct permissions.
• Native Folia-compatible scheduling at the Paper platform boundary.
• Strict, versioned YAML configuration and persistent access state.
• Fail-closed startup and access verification for security-sensitive initialization failures.

Requirements

monban plugin bytecode targets Java 21. Server runtime requirements are platform/version-specific; in particular, Paper 26.1+ requires Java 25 to run.

Install

1. Download the build for your platform from Modrinth or GitHub Releases.
2. Put the JAR in the platform's plugins/ directory.
3. For standalone Bukkit/Spigot or Paper/Folia, set the native Minecraft whitelist to white-list=false.
4. Start the server once, configure plugins/monban/config.yml, then restart.
5. Manage access with /monban whitelist .... Velocity additionally provides /monban access ..., /monban lookup ..., /monban group ..., /monban user ..., and /monban status.

Do not install multiple monban platform builds on the same server.

Standalone servers

For standalone servers, monban is the whitelist authority. Disable the native whitelist in server.properties:

white-list=false

The whitelist can be changed at runtime:

/monban whitelist enable
/monban whitelist disable

For automatic ONLINE profile resolution, use:

/monban whitelist add online <name>

Explicit UUID input remains available with /monban whitelist add online <name> <uuid> and bypasses profile lookup.

Floodgate identity resolution belongs to the Velocity build. Standalone and backend builds continue to use Java ONLINE and OFFLINE identities.

Velocity networks

Velocity is the central authority for the network whitelist, backend access, groups, and permissions. Install monban-velocity on Velocity and the matching Bukkit/Spigot or Paper/Folia build on every backend that should apply synchronized permissions.

Enable backend permissions on Velocity:

backend-permissions:
  enabled: true

Velocity creates plugins/monban/sync.yml automatically. Copy the generated file with the same contents to every enabled backend. Do not copy state-revision to backends.

Enable backend permissions in the backend's config.yml and set server-name to the exact registered server name from Velocity:

backend-permissions:
  enabled: true
  server-name: lobby

The backend creates server-groups.yml automatically. Matching server-group mappings are only needed when SERVER_GROUP permissions or access grants are used.

In centralized mode, whitelist, group, and permission administration is performed on Velocity. Backend servers do not manage a separate local monban state, preventing different whitelists or permissions on different servers.

Example backend permission setup using Chunky:

/monban group create moderator
/monban group moderator access grant server lobby
/monban group moderator permission add server lobby chunky.command.start
/monban group moderator permission add server lobby chunky.command.cancel
/monban user hanamuramiyu offline group add moderator

Reconnect the player and check /chunky tab completion, then run /chunky start or /chunky cancel as appropriate.

Geyser and Floodgate

Geyser and Floodgate support is available on Velocity. Geyser accepts Bedrock connections, Floodgate supplies the authenticated Bedrock identity, and monban evaluates that connection as a FLOODGATE identity. The Bukkit and Paper builds continue to use ONLINE and OFFLINE identities for Java players; they do not resolve Floodgate identities themselves.

Install Geyser, Floodgate, and monban on the proxy. Enable Floodgate in the generated Velocity configuration:

identity:
  mode: AUTO
  floodgate:
    enabled: true
    require-provider: true

Floodgate integration is disabled by default. require-provider: true is recommended when Bedrock access control is part of the production network: monban will fail visibly at startup instead of running without the expected Floodgate provider.

Use the normalized Floodgate Java username reported to monban, including its configured prefix, when adding a Bedrock player. For an unlinked Bedrock account this is normally the server-visible name:

/monban whitelist add floodgate .BedrockName

The normalized name is the durable access key. An optional XUID may be supplied with /monban whitelist add floodgate <name> <xuid>, but it remains metadata and does not change identity matching. A Floodgate name change therefore changes the access key.

Synchronized backend permissions are attached to the Java ONLINE or OFFLINE identity that the backend can resolve. Floodgate groups and direct permissions are evaluated by Velocity for admission and proxy permissions; they are not re-matched as FLOODGATE identities on a backend.

Documentation

Full setup, configuration, commands, storage, permissions, Geyser/Floodgate, backend synchronization, and hybrid authentication documentation is available at monban.miyu.pw.

Building

./gradlew clean build

License

monban is licensed under the Mozilla Public License 2.0.