Gate

Secure authentication for offline-mode Paper and Folia servers.

Gate verifies premium Java players through Mojang's normal session proof, authenticates offline Java players with native Paper Dialogs, and supports trusted Floodgate identities or native password forms for Bedrock players. It uses Argon2id password hashing, persistent lockouts, and no /login or /register commands.

Features

• premium Java verification with encrypted login and Mojang session proof
• permanent protection against premium names falling back to offline identities
• native password dialogs for offline Java players, with an opt-in legacy chat flow
• trusted Floodgate authentication or native Bedrock password forms
• configurable in-memory IP sessions for password-authenticated players
• SQLite persistence, Argon2id hashes, lockouts, and operator recovery commands
• Paper and Folia support with entity-scheduler-safe player operations

Requirements

• Java 25
• Paper or Folia 26.2
• PacketEvents 2.13.0 or a compatible newer release
• Floodgate 2.2.5 or a compatible newer release for Bedrock support
• Geyser configured for Floodgate when accepting Bedrock clients

Gate requires online-mode=false. PacketEvents must load before Gate. Floodgate is optional when Bedrock support is not needed.

Installation

1. Build the project with gradle clean build, or obtain a trusted release jar.
2. Install PacketEvents on the backend server.
3. Install Floodgate and Geyser if Bedrock players should connect.
4. Copy the shaded jar from build/libs/ to the server's plugins/ directory.
5. Set online-mode=false in server.properties.
6. Start the server once, then review plugins/gate/config.yml and plugins/gate/offline.yml.

Back up plugins/gate/gate.db before upgrades or account maintenance. Do not modify the database while the server is running.

Configuration and operations

Gate defaults to native Paper Dialogs for offline Java players and trusted Floodgate authentication for Bedrock players. Configure the plugin in plugins/gate/config.yml after first launch.

Operators with gate.admin can reload configuration, manage forced-offline Java names, inspect accounts, clear lockouts, and reset password accounts:

/gate reload
/gate offline add <name>
/gate offline remove <name>
/gate offline list
/gate status java <name>
/gate status bedrock <xuid>
/gate unlock java <name>
/gate unlock bedrock <xuid>
/gate reset java <name> confirm
/gate reset bedrock <xuid> confirm

See the setup guide for the full configuration reference, player flows, security notes, and recovery procedures.

Development

This repository has no Gradle wrapper. Use the locally installed Gradle command:

gradle test build
gradle runServer

runServer starts a development server with pinned PacketEvents, Geyser, Floodgate, and DiscordSRV dependencies.

Documentation

• Setup, configuration, recovery, and security
• Manual acceptance checklist