🏰🔐 AuthCore

The Fortress Framework for Minecraft Servers, login & security for offline-mode servers, one codebase for Minecraft 1.16.0 → 26.1-26.2 on Fabric/Forge/NeoForge, servers AND clients.

⚔️ 🔥 🏰 🔥 ⚔️
"No bots, no griefers, no password guessers, only real players."

✅ One codebase, every Minecraft version & every loader, 1.16.0 → 26.1-26.2, on servers AND clients, behind Velocity/BungeeCord or standalone, on Fabric / Forge / NeoForge (see 🔮 Multi-Version & Multi-Loader).

🧭 New here? Start with the Server Admin Guide, jar selection, install, config walkthrough, auth flows, commands and troubleshooting, plus a learning path that maps every topic to the deeper docs (CONFIG / PROXY / WEBPANEL / SECURITY / DEVELOPMENT) so you can go from zero to expert step by step. All docs are also hosted as a styled site: authcore.potenfyr.in.

🔥 Highlights

📦 Which jar do I need?

Each jar plays all three roles, server mod (Fabric/Forge/NeoForge), client companion, and a BungeeCord/Velocity proxy plugin (auto-detected by the loader you drop it into). Pick the jar matching your Minecraft version range and loader:

Why range jars? Minecraft 26.0+ ships unobfuscated code and Fabric's intermediary no longer exists there, see Fabric's announcement. Each jar is booted on every version of its range by the host-test harness before release. Details in 26.x builds.

🚀 Installation

1. Install your loader: Fabric (Loader + Fabric API), Forge, or NeoForge.
2. Grab the right jar (version range × loader) from Modrinth or GitHub Releases.
3. Drop it into mods/, start the server, config is generated automatically in config/authcore/.

First join: premium → auto-logged-in · offline → moved to the lobby → /register <pw> <pw> or /login <pw> → back where they were, session saved.

🛠️ Commands

Players

Admins (OP 3+, LuckPerms node, or console)

⚙️ Configuration

Files are generated on first start: config/authcore/settings.conf + messages.conf. The settings you'll actually change:

language = "en"              # en | zh | es | de | fr | pt | ru

session {
    server-mode = "offline"  # ← set on cracked servers
    timeout-ms = 3600000     # session validity (60 min)

    account-lock { enabled = true
                   max-failed-logins = 8
                   lock-duration-ms = 600000 }

    security { webhook-url = "" }   # ← Discord webhook for security alerts

    proxy-support { enabled = false  # BungeeCord / Velocity IP forwarding
                    protocol = "auto" }

    web-panel { enabled = true
                host = "127.0.0.1"
                port = 25570
                token = "CHANGE_ME" }   # generate: openssl rand -hex 16

    email { enabled = true              # login alerts + password recovery
            host = "smtp.gmail.com"
            port = 587
            username = "you@gmail.com"
            password = "app-password"
            from = "AuthCore <you@gmail.com>" }
}

📖 Every option (~180 settings), default and use-case: Configuration Reference

🌍 Languages

Custom locales: drop a messages-<lang>.conf into config/authcore/, missing keys are logged.

🔁 Proxy & Network (Velocity / BungeeCord)

AuthCore runs on the mod server, Fabric, Forge or NeoForge, and supports every proxy setup properly:

• IP forwarding auto-detect (session.proxy-support.protocol = "auto"), BungeeCord and Velocity-legacy (ip\0uuid\0properties) parsed from the handshake; real client IP used for GeoIP, sessions, rate limits and login intelligence
• Velocity modern identity forwarding, HMAC-verified velocity:player_info login receiver applies the real UUID/username (velocity-secret from velocity.toml)
• Interop channel authcore:auth (+ BungeeCord subchannel AuthCore), AuthCore broadcasts AUTH_CHANGED|<uuid>|<username>|<1|0> so a network can coexist with a different auth mod on the backend
• Separate config per role, server settings.conf, client authcore-client.json, optional database.conf override (credentials outside the main config); Redis config sync distributes network-wide settings
• 📖 Full guide: Proxy Support

🖥️ Client Companion

Both jars ship environment: "*" with the login-screen companion built in. It shows a custom username/password screen before connecting to protected servers and auto-runs /login after joining. The screen needs 1.20.2+ (classic line) / native on 26.1-26.2, older clients load safely and skip it (auto-login via chat still works). Configure interception in config/authcore-client.json (enable, auto-login, servers: ["*"], theme colors).

⚡ Performance

• Zero per-tick work, everything happens on join/login/logout events
• Mojang & GeoIP lookups cached (hours-long TTLs), a 500-player burst costs a few HTTP requests
• All external I/O non-blocking; every cache bounded & self-cleaning (no memory leaks)
• Lazy user loading, 100k+ registered accounts stay light (bounded 20k LRU)
• SQLite tuned for low-end boxes (WAL + synchronous=NORMAL, ~2 MB page cache)
• Web panel is OFF by default, the mod runs as a basic, lean auth plugin until you opt in
• Mixins are login/player-only, no conflicts with C2ME, Lithium, Krypton, ModernFix, FerriteCore

🪶 Low-resource servers (≤ 250 MB RAM / 1 core)

AuthCore itself is tiny; the server JVM dominates. For a 1-core / ≤250 MB box, add to your start script:

java -Xmx192M -Xms64M -XX:+UseSerialGC -XX:TieredStopAtLevel=1 \
     -XX:-UsePerfData -XX:MaxMetaspaceSize=96M -jar fabric-server.jar nogui

Tips: keep cache-max-users at its default (20 000) or lower it (e.g. 5000) in settings.conf, leave MySQL/PostgreSQL/Redis disabled (SQLite is the lightest), and keep the web panel disabled (session.web-panel.enabled = false, the default).

🔮 Multi-Version & Multi-Loader Compatibility

Seven jars from one codebase, 3 version ranges × Fabric/Forge/NeoForge, verified by the host-test harness:

• Multi-loader is the core of the project, Fabric, Forge and NeoForge variants share the same tree (loader constants fabric/forge/neoforge/forgeLike), with thin per-loader entrypoints (FabricEntry, ForgeEntry/ForgeEntryModern, NeoForgeEntry) and per-loader metadata (fabric.mod.json, mods.toml, neoforge.mods.toml). Adding or bumping a loader is one line in the Stonecutter matrix, not a port.
• Multi-version workspace (Stonecutter + Stonecraft), one Mojang-mapped source tree in src/main/java with /*? if ... {*/ version/loader conditionals; per-version dependencies in versions/dependencies/.
• Merged client + server, one jar is server mod, client companion and BungeeCord/Velocity proxy plugin at the same time.
• Host-test harness (tools/host-tests): boots every range jar inside Docker on every range endpoint (1.16.5 … 26.2) and runs the functional checks (mod load, mixins, commands, web panel, honeypot, DB), 8/8 endpoints × 7/7 loader targets PASS.
• CI (one workflow): builds all variants, runs the security checks, publishes to GitHub Releases on v* tags.
• Untested versions get a startup warning banner (never refuse to load), silence with logging.show-untested-version-warning = false.

🧑‍💻 Building From Source

Requires JDK 25 for Gradle itself (the 26.1-26.2 variants enforce it); the foojay toolchain resolver downloads 17/21/25 automatically.

./gradlew build                    # the ACTIVE variant (1.21.11-fabric)
./gradlew chiseledBuild            # ALL SEVEN variants (3 ranges x fabric/forge/neoforge)

# single variant:
./gradlew :1.18.2-fabric:build     # -> versions/1.18.2-fabric/build/libs/authcore-1.16-1.18-fabric-1.0.0.jar
./gradlew :1.18.2-forge:build      # -> versions/1.18.2-forge/build/libs/authcore-1.16-1.18-forge-1.0.0.jar
./gradlew :1.21.11-neoforge:build  # -> versions/1.21.11-neoforge/build/libs/authcore-1.19-1.21-neoforge-1.0.0.jar
./gradlew :26.2-fabric:build       # -> versions/26.2-fabric/build/libs/authcore-26.1-26.2-fabric-1.0.0.jar
./gradlew :26.2-neoforge:build     # -> versions/26.2-neoforge/build/libs/authcore-26.1-26.2-neoforge-1.0.0.jar

Per-variant dependency pins live in versions/dependencies/<mc>.properties. The Docker host-test harness (tools/host-tests) verifies every jar on every version of its range; see Development & Architecture.

🧪 Security Testing

Standalone suite (no Minecraft needed): tools/security-tests/, 67 checks covering all 6 hashing algorithms, unique salts, captcha lifecycle, email recovery (incl. cooldown & attempt limits), rate limiting, proxy parsing, fingerprints and timing-safe comparisons.

.\gradlew.bat build
powershell -ExecutionPolicy Bypass -File tools\security-tests\run-tests.ps1

📚 Documentation

❓ FAQ

Premium player blocked as "not online-mode"? Fixed, premium detection is outage-proof now.

Works on localhost / LAN? Yes, private & local IPs are never sent to external APIs.

Conflicts with other mods? None known, tested against C2ME, Chunky, Lithium, Krypton, Ledger, ModernFix, FerriteCore, Spark.

Several servers on one account database? Yes, shared MySQL/PostgreSQL + Redis for session sync, distributed config and the cross-server security event bus.

Do players need the client mod? No, the companion is optional convenience; login works via normal chat commands.

🗺️ Roadmap

✅ Shipped (1.0.0):

• 🔑 Authentication core, register/login, 2FA (TOTP), CAPTCHA (TPS-adaptive), recovery codes, account locking, session system, premium auto-login
• 🛡️ Anti-abuse, brute-force lockout, rate limits, IP allow/deny rules, honeypot, shadow-ban, maintenance mode, progressive punishment, password history
• 🗄️ Storage & networks, SQLite/MySQL/PostgreSQL (dialect-aware), Redis session/ban sync, cross-server event bus, distributed config
• 🌐 Web panel, token auth (full + read-only), HTTPS, brute-force lockout, /metrics
• ✉️ Email & Discord, SMTP alerts + recovery, webhooks, Discord account linking
• 🔁 Proxy support, BungeeCord/Velocity IP forwarding auto-detect, Velocity modern identity forwarding (HMAC), interop channel with other auth mods, full proxy-side auth (block unauthenticated players before any backend, Redis session validation, fail-open)
• 🖥️ Client companion, login screen + auto-login, bundled in every jar
• 🧩 Multi-loader, Fabric / Forge / NeoForge server mods for every version range (7 jars from one source tree, thin per-loader entrypoints, per-loader metadata)
• 🔮 26.1-26.2 support, Mojang-named modern jar, unobfuscated era
• 🧪 Security suite, 73 automated checks, honest 3-role × 3-loader CI

🔜 Planned:

• Loader parity finishing touches, block/item-use restrictions and the Velocity modern-identity receiver are Fabric-only today; Forge/NeoForge rely on the loader-neutral mixins (lobby restrictions, handshake forwarding, chat). Porting the remaining hooks to the Forge/NeoForge event buses is the top priority.
• 26.1-26.2 snapshot compile checks, ✅ already live: the CI runs a daily snapshot job that compiles the modern source against the newest 26.1-26.2 release the moment Fabric publishes mappings for it (fails visibly when a new release breaks)

🤝 Contributing & Support

Fork → branch → PR at github.com/DawnOfDedSec/AuthCore/pulls (Google Java Format). Bugs & ideas: Issues · Discussions

License: CC0 1.0 Universal (Public Domain), use, modify and distribute freely.