A lightweight staff-only 2FA plugin for Velocity 3 (MC 1.21.x). Premium-only (online-mode) friendly.

Built with the tools and technologies:

Quick Links

• Overview
• Features
• Project Structure
  • Project Index
• Getting Started
  • Prerequisites
  • Installation
  • Usage
  • Testing
• Project Roadmap
• Contributing
• License
• Acknowledgments

---

Overview

Kr2FA is a Two-Factor Authentication plugin explicitly designed for Minecraft Velocity proxy servers. It provides an additional layer of security for staff members by requiring TOTP-based authentication (compatible with Google Authenticator/Authy) before granting access to backend servers. The plugin blocks staff from connecting to game servers or executing commands until they complete 2FA verification, preventing unauthorized access even if credentials are compromised.

---

Features

• Staff-Only 2FA: Only prompts users with configurable staff permissions (staff, moderator, admin, helper, or velocity2fa.staff)

• TOTP Authentication: Uses industry-standard Time-based One-Time Passwords compatible with Google Authenticator, Authy, and similar apps

• Server Connection Blocking: Blocks staff from joining backend servers until 2FA verification is complete

• Command Restriction: Blocks all commands (except /2fa) until authentication is successful

• Persistent Secrets: Securely stores TOTP secrets in plugins/Kr2FA/secrets.json

• Session Cache: Configurable session duration to avoid re-verifying too often (default 12h)

• Admin Management: Dedicated admin command (/2fa-admin) for managing staff 2FA settings

• Limbo Server Support: Allows players to connect to a designated limbo/lobby server while pending authentication

• Configurable Message Prefix: Prepend a custom, editable prefix to all plugin messages for clear branding

---

Project Structure

└── Kr2FA/
    ├── .github
    │   └── workflows
    ├── LICENSE
    ├── README.md
    ├── pom.xml
    ├── src
    │   └── main
    └── target
        ├── classes
        └── maven-status

Project Index

KR2FA/

__root__

.github

workflows

build.yml

GitHub Actions workflow for building, testing, and packaging the Velocity plugin with automatic version bumping

target

maven-status

maven-compiler-plugin

compile

default-compile

inputFiles.lst

Maven compiler plugin input file list for tracking source files

classes

config.json	Plugin configuration file defining session TTL and limbo server settings
velocity-plugin.json	Velocity plugin metadata descriptor

src

main

resources

config.json	Default plugin configuration with session TTL and limbo server settings
velocity-plugin.json	Velocity plugin descriptor defining plugin metadata and dependencies

java

com

queazified

velocity2fa

TwoFactorManager.java	Manages TOTP secret generation, storage, and verification using Google Authenticator library
TwoFactorCommand.java	Handles player 2FA commands for setup and code verification
Velocity2FA.java	Main plugin class handling initialization, event listeners, and authentication state management
AdminCommand.java	Administrative commands for managing player 2FA settings (reset, status, etc.)
ConfigManager.java	Handles loading and parsing of plugin configuration from JSON files

---

Getting Started

Prerequisites

Before getting started with Kr2FA, ensure your runtime environment meets the following requirements:

• Programming Language: Java 21 or higher (build may require matching JDK)
• Build Tool: Maven 3.6+
• Server: Velocity 3.1.1+ proxy server

Installation

Install Kr2FA using one of the following methods:

Build from source:

1. Clone the Kr2FA repository:

❯ git clone https://github.com/KryptonSystems/Kr2FA

2. Navigate to the project directory:

❯ cd Kr2FA

3. Build the project using Maven:

❯ mvn clean package

4. Copy the generated JAR to your Velocity plugins folder:

❯ cp target/Kr2FA-*.jar /path/to/velocity/plugins/

Usage

1. Start or restart your Velocity proxy server
2. Grant staff members the appropriate permission (any of the following will work):

   /lp group staff permission set staff true

3. When staff members first join, they'll be prompted to set up 2FA:

   /2fa setup

4. Staff members verify their TOTP code on each session:

   /2fa <6-digit-code>

Configuration

Edit plugins/Velocity2FA/config.json after first run. New option:

• messagePrefix: A short tag prepended to all player/console messages sent by the plugin. Default: [Kr2FA].

Example snippet:

{
	"serverName": "Proxy-01",
	"limboServer": "Hub",
	"messagePrefix": "[Kr2FA]",
	"issuerName": "Kr2FA"
}

Testing

Run the test suite using the following command:

❯ mvn test

---

Project Roadmap

• Task 1: Implement core TOTP authentication.
• Task 2: Add session caching for improved user experience.
• Task 3: Implement command blocking until authentication.
• Task 4: Add backup codes for account recovery.
• Task 5: Implement IP-based session trust.
• Task 6: Add Discord/webhook notifications for 2FA events.

---

Contributing

• 💬 Join the Discussions: Share your insights, provide feedback, or ask questions.
• 🐛 Report Issues: Submit bugs found or log feature requests for the Kr2FA project.
• 💡 Submit Pull Requests: Review open PRs, and submit your own PRs.

Contributing Guidelines

1. Fork the Repository: Start by forking the project repository to your github account.
2. Clone Locally: Clone the forked repository to your local machine using a git client.

   git clone https://github.com/KryptonSystems/Kr2FA

3. Create a New Branch: Always work on a new branch, giving it a descriptive name.

   git checkout -b new-feature-x

4. Make Your Changes: Develop and test your changes locally.
5. Commit Your Changes: Commit with a clear message describing your updates.

   git commit -m 'Implemented new feature x.'

6. Push to github: Push the changes to your forked repository.

   git push origin new-feature-x

7. Submit a Pull Request: Create a PR against the original project repository. Clearly describe the changes and their motivations.
8. Review: Once your PR is reviewed and approved, it will be merged into the main branch. Congratulations on your contribution!

Contributor Graph

---

License

This project is protected under the MIT License. For more details, refer to the LICENSE file.

---

Acknowledgments

• Google Authenticator Library for TOTP implementation
• ZXing for QR code generation
• Velocity for the proxy platform
• Gson for JSON handling
• All contributors and the Minecraft server community

---