AuthCore

✅ One codebase, every Minecraft version — 1.16.0 → 26.x, on servers AND clients, behind Velocity/BungeeCord or standalone. Two jars, built from one source (see 🔮 Multi-Version).

🔥 Highlights

📦 Which jar do I need?

Each jar plays all three roles — Fabric server mod, Fabric client companion, and a BungeeCord/Velocity proxy plugin (auto-detected by the loader you drop it into):

Why two jars? Minecraft 26.0+ ships unobfuscated code and Fabric's intermediary no longer exists there — see Fabric's announcement. 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 = "you@gmail.com"
            password = "app-password"
            from = "AuthCore <you@gmail.com>" }
}

📖 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.x — 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

Two jars from one codebase, verified by CI on every push:

• Shared + versioned sources — src/common/java holds all pure-Java logic (database, hashing, web panel, Redis, security) used by BOTH jars; only MC-coupled code is duplicated in src/classic/java (yarn) and src/modern/java (Mojang).
• Fragile mixins are required:false + tick re-assert guards — a changed signature skips the mixin instead of crashing the server.
• CI (one workflow, 3 jobs): builds both jars, compiles the source against 1.16.5 … 1.21.11, runs 67 security checks, publishes both jars 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

./gradlew clean build                                  # classic jar (1.16 - 1.21.11)  -> build/libs/authcore-classic-1.0.0.jar
./gradlew clean build -Pmodern=true \
  -Pfabric.loom.disableObfuscation=true                # 26.x jar                      -> build/libs/authcore-modern-1.0.0.jar

Java 21+ for the classic build, Java 25 for the modern one. Per-version verification builds: ./gradlew build -Puniversal=false.

🧪 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 both jars
• 🔮 26.x 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.x snapshot compile checks — ✅ already live: the CI runs a daily snapshot job that compiles the modern source against the newest 26.x 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.