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

🧭 New here? Read the Server Admin Guide — jar selection, install, every config option explained, how the auth flows work, commands and troubleshooting.

🔥 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):

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 docs/26x.md.

🚀 Installation

1. Install Fabric Loader + Fabric API on your server.
2. Grab the right jar 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 = "[email protected]"
            password = "app-password"
            from = "AuthCore <[email protected]>" }
}

📖 Every option (~180 settings), default and use-case: docs/CONFIG.md

🌍 Languages

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

🔁 Proxy & Network (Velocity / BungeeCord)

AuthCore runs on the Fabric server 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: docs/PROXY.md

🖥️ 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 Compatibility

Three range jars from one codebase, verified by the host-test harness:

• 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/.
• Multi-loader ready — Fabric now, Forge/NeoForge variants share the same tree (loader constants fabric/forge/neoforge/forgeLike).
• 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).
• 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 :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 docs/DEVELOPMENT.md.

🧪 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
• 🔮 26.1-26.2 support — Mojang-named modern jar, unobfuscated era
• 🧪 Security suite — 73 automated checks, honest 3-role CI (server/client/proxy)

🔜 Planned:

• NeoForge / Forge port — the security core is loader-independent; the compat layer already isolates version-specific APIs
• 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.