---

🤖 AI Usage Disclosure

AI tools were used to assist with code development, translations, and this README/documentation.

---

✨ Features

🔐 Authentication

• Paper, Folia & Velocity support.
• Verified account auto-login — Authenticated Minecraft accounts can join without creating a local password when ownership is successfully verified.
• Login sessions — Skip passwords on trusted reconnects for a configurable period.
• Brute-force protection — Limit failed login attempts.
• IP account limits — Control how many accounts can be registered from one IP.
• Login timeout — Automatically disconnect unauthenticated players.
• Limbo system — Block movement, commands and chat until authentication.
• Safe teleportation — Send players to a safe location before login and restore their previous location afterward.
• Username conflict handling — Prevent conflicts between different account and UUID modes.

🛰️ Velocity Integration

• Zero manual proxy configuration — PkLogin automatically detects the network's forwarding configuration.
• Authenticated proxy messages — Uses HMAC signing derived from Velocity's modern forwarding secret.
• Backend verification — The proxy can verify that authentication servers are running PkLogin and using the same signing key.
• Requires Velocity modern forwarding for secure verified-account auto-login.

🔑 Password Security

Supports multiple hashing algorithms:

Algorithm	Use
BCrypt	Recommended default
Argon2id	Strong password hashing
PBKDF2	600,000 iterations
SHA-512 / SHA-256	Salted compatibility modes
AuthMe SHA256	Read-only migration support

Automatic hash migration: Change the configured algorithm at any time. Existing supported password hashes are detected automatically and re-hashed after the player's next successful login.

🔒 Two-Factor Authentication

• Discord 2FA with DM-based verification codes.
• Single-use 6-digit codes.
• Codes expire after 5 minutes and have limited attempts.
• Additional 2FA methods are planned for future releases.

🗄️ Database Support

• SQLite — Default, zero configuration
• H2
• MySQL
• MariaDB
• PostgreSQL

🔄 Migration

AuthMe → PkLogin

/pklogin authme-import

Imports existing accounts while preserving supported passwords, IP information and registration dates.

Database Migration

/pklogin migrate <engine>

Move accounts between supported database engines without deleting the original data.

Existing accounts are skipped, making migrations safe to re-run.

🌍 Internationalization

20+ built-in languages, including:

English, Spanish, Portuguese, French, German, Russian, Chinese, Polish, Italian, Turkish, Vietnamese and more.

📡 UUID Modes

Choose how account UUIDs are handled:

• REAL — Uses the authenticated Minecraft account UUID.
• RANDOM — Generates a random UUID.
• OFFLINE — Uses Minecraft's standard offline UUID generation.

---

🛡️ Security

PkLogin is designed around secure authentication by default.

Verified Account Auto-Login

PkLogin can verify eligible Minecraft accounts and allow them to join without creating a separate PkLogin password.

For unknown usernames, PkLogin can query Mojang's account services and, when applicable, perform the standard Minecraft online authentication handshake.

Successful authentication provides cryptographic verification of the connecting account.

If external account services are temporarily unavailable, PkLogin can use the server's configured local authentication behavior instead of relying on an unverified online authentication result.

On standalone Paper servers, verified-account auto-login requires PacketEvents or ProtocolLib. Velocity handles the required proxy-side authentication flow automatically.

Login Sessions

Sessions allow authenticated players to reconnect without entering their password again.

Security:
  session:
    enable: true
    timeout: 5

Sessions are:

• Time-limited
• Bound to the player's IP address
• Single-use
• Stored only in memory

They are automatically invalidated when passwords or 2FA settings change, accounts are deleted, or PkLogin is reloaded.

Security note: IP addresses are not unique identities. Keep session timeouts short, especially on shared networks.

---

🛠️ Commands

Player Commands

Command	Description
/login <password>	Log in
/register <pass> <confirm>	Register a local account
/changepassword <old> <new>	Change password
/unregister <password>	Delete local credentials
/premium confirm	Enable verified Minecraft account mode
/offline	Switch to local account mode
/2fa discord	Link Discord 2FA
/2fa verify2fa <code>	Verify a 2FA code

Admin Commands

Every command has its own permission.

Command	Description
/pklogin help	Show admin commands
/pklogin reload	Reload configuration
/pklogin authme-import	Import AuthMe accounts
/pklogin migrate <engine>	Migrate database engines
/pklogin forcelogin <user>	Force-login a player
/pklogin unregister <user>	Remove a player's local password
/pklogin delete <user>	Permanently delete an account
/pklogin changepass <user> <pass>	Change a player's password
/pklogin verify <user>	View account information
/pklogin dupeip <ip/user>	Find accounts sharing an IP
/pklogin setspawn	Set the pre-login spawn
/pklogin update	Download the latest version

---

⚙️ Configuration

PkLogin is highly configurable while remaining simple to set up.

Security:
  time-to-login: 45
  hash-algorithm: BCRYPT

  password:
    small: 5
    large: 15

  session:
    enable: true
    timeout: 5

autologin:
  premium:
    enable: true
    cache-minutes: 60

  bedrock:
    enable: true
    skip-register: true

passwords:
  bruteforce:
    max-login-tries: 3

security:
  ip-limit:
    enable: true
    limit: 3

teleport:
  safe-location: true
  last-location: true

limbo:
  blindness-effect: false

username-appender:
  enabled: false

---

🔌 Proxy Setup

PkLogin requires no additional proxy secret or proxy-mode option.

When running behind Velocity, PkLogin automatically reads the forwarding configuration already used by the network and derives a separate signing key from Velocity's modern forwarding secret.

This provides:

• Secure proxy → backend authentication
• Protection against forged authentication messages
• Automatic backend compatibility checks
• No duplicated secrets across multiple configuration files

For production networks, Velocity modern forwarding + firewalling backend ports is strongly recommended.

---

🔒 Discord 2FA

Configuration:

# plugins/PkLogin/2fa/discord.yml

enable: false

authentication:
  token: "YOUR_BOT_TOKEN_HERE"

Link an account with:

/2fa discord

Then send the generated verification code to the configured Discord bot.

---

🔄 Migrating from AuthMe

1. Place your authme.db in:

plugins/AuthMe/authme.db

2. Run:

/pklogin authme-import

PkLogin imports compatible accounts asynchronously and preserves their supported existing password hashes.

When possible, hashes are automatically migrated to the configured hashing algorithm after a successful login.

---

📄 License

MIT License — © 2020–2026 PkLogin Contributors