The Fortress Framework for Minecraft Servers. One unified codebase for 1.16.0 → 26.x+ on Fabric, Forge, and NeoForge.
Server-side Minecraft authentication that works in both online-mode and offline-mode (cracked) environments, hardened against bypasses, race-condition-free under burst load, and engineered to hold 500k+ registered accounts and thousands of concurrent players with flat, spike-free resource usage.
AuthCore is a universal, server-side authentication and security framework for Minecraft servers. It solves the problem every server operator eventually faces: Minecraft's account system alone cannot protect your server. Offline-mode servers have no password protection at all, mixed communities of premium and cracked players are hard to serve safely, and bot farms, credential stuffing, and session hijacking are constant threats on both modes.
AuthCore answers with one framework that:
Authenticates players with /register and /login, per-account passwords, TOTP 2FA, and email recovery, or automatically verifies premium accounts against Mojang session servers so legitimate players never type a password.
Runs in both online-mode and offline-mode (allow-offline-players): on an online-mode server, verified premium players auto-login while offline/cracked players authenticate with passwords; on offline-mode servers everyone gets full password protection.
Defends the join path with a 7-layer detection stack, risk-score captchas, brute-force lockouts, rate limits, honeypots, and CIDR IP rules.
Scales: O(1) UUID-keyed lookups, bounded caches, zero per-tick work, and no database queries on hot paths keep memory and CPU flat during join storms.
Each released jar is dual-role: a native Fabric / Forge / NeoForge server mod and a BungeeCord / Velocity proxy plugin, with network-wide SSO over Redis. Players never install anything: AuthCore is 100% server-side.
? Quick Start in 5 Minutes
graph LR
A[Pick Range Jar] --> B[Drop into mods/ or plugins/]
B --> C[Start Server]
C --> D[Auto-Generated Config & DB]
D --> E[Players Join & Authenticate]
Pick the Right Jar: Select the jar matching your server loader and Minecraft version from the Jar Matrix via Modrinth or GitHub Releases.
Install: Drop the jar file directly into your server's mods/ directory (or your proxy's plugins/ directory).
Start the Server: AuthCore boots out of the box with zero required configuration. An embedded SQLite database (authCore-db.sqlite) is automatically provisioned under config/authcore/database/.
First Join Experience:
Premium Players: Verified asynchronously against Mojang session servers with background retry resilience. Auto-logged in without requiring passwords.
Cracked / Offline Players: Anchored inside the secure limbo lobby, prompted with interactive chat buttons or commands: /register <password> <confirm> or /login <password>.
Administer: Run /authcore validate to dry-run configuration integrity. For remote administration, enable the optional web panel (disabled by default) and reach it at http://127.0.0.1:25570 with your access token.
[!NOTE]
New to AuthCore? Check out the full Server Admin Guide for visual step-by-step walkthroughs, permission setups, and proxy topologies.
? Which Jar Do I Need?
Each compiled jar performs both roles: a native server mod (Fabric, Forge, or NeoForge) and a BungeeCord/Velocity proxy plugin (automatically detected upon startup). Select the jar corresponding to your Minecraft version range and loader:
Jar Artifact
Minecraft Versions
Loader
Target Java
Era & Architecture
authcore-1.16-1.18-fabric-<v>.jar
1.16.0 – 1.18.2
Fabric
17
Intermediary mappings era
authcore-1.16-1.18-forge-<v>.jar
1.16.0 – 1.18.2
Forge
17
Intermediary mappings era
authcore-1.19-1.21-fabric-<v>.jar
1.19.0 – 1.21.11
Fabric
21
Intermediary mappings era
authcore-1.19-1.21-neoforge-<v>.jar
1.19.0 – 1.21.11
NeoForge
21
Intermediary mappings era
authcore-26.1-26.3-fabric-<v>.jar
26.1 – 26.3+ & Snapshots
Fabric
25
Unobfuscated era (Official Mojang names, forward-compatible)
authcore-26.1-26.3-neoforge-<v>.jar
26.1 – 26.3+ & Snapshots
NeoForge
25
Unobfuscated era (Official Mojang names, forward-compatible)
[!TIP]
Why range jars? Minecraft 26.0+ ships completely unobfuscated code and Fabric intermediary is deprecated for 26.x onwards (see Fabric announcement). Each range jar is thoroughly verified across every endpoint in its version bracket using our parallel Docker test harness.
AuthCore deploys a 7-layer defense-in-depth security stack designed to make automated client bypasses, bot farm attacks, and credential stuffing attacks mathematically and practically infeasible:
Layer
Mechanism
Threat Vectors Mitigated
1. Session Binding
Per-server random 32-byte companion attestation key rotated on reload
Fail-Closed Defaults: Proxy authentication mandates Redis synchronization; an empty trusted-proxies list automatically turns off insecure proxy ingestion.
Cryptographic Independence: No hardcoded keys exist in the binary; attestation secrets are dynamically generated with high-entropy CSPRNG on first boot.
State Integrity & Memory Protection: All detection and IP tracking maps have enforced cardinality bounds and auto-cleanse on tick to thwart memory-exhaustion attacks.
No Single Point of Failure: Each defense layer executes independently; even if an attacker bypasses client branding checks, packet timing and behavioral analysis remain active.
?️ Commands
Player Commands
Command
Syntax & Usage
Purpose
/register
/register <password> [<confirm>] [<2fa>]
Create and bind a new player account with password rules enforcement
/login
/login <password> [<2fa>]
Authenticate the account and exit the limbo lobby
/account
/account logout · set-password <new> · codes
Manage active sessions, update password, or generate one-time recovery codes
/account
/account email <address> · nickname <name>
Configure password recovery email or set localized display nickname
/account
/account set-mode online|offline
Toggle player's authentication mode between automatic Mojang login and password login
/account
/account recover <email> [<code> <new-password>]
Self-service password recovery via one-time SMTP email verification
/account
/account unregister
Permanently wipe account credentials (subject to server policies)
/discord
/discord link · /discord unlink
Generate Discord account link code to synchronize with DiscordSRV or panel
Admin Commands
Access requires Minecraft OP level 3+, LuckPerms permission node, or server console execution. Every command's permission node and OP level is configurable in commands.conf.
Command
Syntax & Usage
Purpose
/authcore reload
/authcore reload
Hot-reload all split configuration blocks and locale files
/authcore validate
/authcore validate
Perform dry-run validation of configuration files and database connections
/authcore compat
/authcore compat
Generate system report: loader environment, config versions, DiscordSRV/InteractiveChat status
Give a player a map showing a rendered 128x128 image (test pattern, a generated QR code, or a captcha code) and take it back; cleanup is automatic on logout/crash. Enabled by default (lobby.map-image)
/authcore simulate
/authcore simulate
Run the built-in self-test / simulation suite inside the live server (18 checks: hashing, live DB, landing geometry, session flow, proxy gate, SRG runtime, bounded caches, map rendering, map give/take lifecycle, map content/QR/captcha). Owner-only and disabled by default (commands.admin.simulate)
⚙️ Configuration
AuthCore generates all configuration files inside config/authcore/. The architecture utilizes one file per configuration domain, guaranteeing clean version control diffs and zero credential leakage into gameplay configs:
Configuration File
Domain Scope
Primary Settings
settings.conf
Root Settings
language, debug-mode, logging, cache-max-users, schema version
session.conf
Session & Security
Session TTLs, account locking, SSO, web panel, SMTP email, ClientGuard
AuthCore ships with 7 languages: English is built in, plus 6 bundled community translations. The active language is controlled via language = "en" in settings.conf:
Code
Language
Code
Language
en
English (built in)
de
Deutsch (German)
zh
简体中文 (Simplified Chinese)
fr
Français (French)
es
Español (Spanish)
pt
Português (Portuguese)
ru
Русский (Russian)
[!TIP]
Custom Locales: Place a custom messages-<lang>.conf file into config/authcore/. AuthCore automatically loads your strings and logs any missing keys against the English fallback template.
? Proxy & Network (Velocity / BungeeCord)
AuthCore natively supports modern Minecraft proxy architectures, whether deployed as a backend mod or directly on the proxy:
Universal IP Forwarding Auto-Detection: Automatically parses BungeeCord and Velocity legacy (ip\0uuid\0properties) handshake payloads. The authentic remote IP address is immediately applied to GeoIP lookup, session validation, rate limiting, and login intelligence.
Velocity Modern Identity Forwarding: High-security HMAC-verified velocity:player_info login receiver reads credentials securely using the shared velocity-secret configured in velocity.toml.
Cross-Mod Interop Channel (authcore:auth): Emits AUTH_CHANGED|<uuid>|<username>|<1|0> network packets, allowing AuthCore to run alongside foreign backend auth plugins.
Redis SSO Hub-to-Game Transfers: Players authenticated in hub/limbo servers maintain session validity when transferred across backend game nodes without being re-prompted for passwords.
Fail-Closed Proxy Enforcement: Direct connections bypassing the proxy are rejected outright when proxy support is active.
⚡ Performance
Engineered from inception to scale to 500,000+ registered accounts and thousands of concurrent logins without thread contention or memory spikes:
O(1) Lockless User Resolvers: Hot path events (packet interception, movement checks, inventory clicks, and chat events) resolve the player in O(1) time through a UUID-keyed ConcurrentHashMap (User.getUser(player)). Zero string allocations and zero database queries occur on hot paths.
Concurrency Without Deadlocks: Thread-safe canonical in-memory user cache guarantees exactly one User instance exists per account. Cache-miss database fetches serialize under fine-grained locks; background I/O operations execute on a bounded daemon pool.
Flat Memory Curves & Throttled Packets: User activity timestamps update at most once per minute rather than per packet. Limbo position corrections enforce a minimum interval, preventing position packet flooding and eliminating camera screen jitter.
Zero Per-Tick Workload: The plugin conducts no tick-based polling loops. All lifecycle logic is strictly event-driven upon network packet, join, login, or disconnect triggers.
High-Speed Cache Optimization: SQLite operates in WAL journal mode with synchronous=NORMAL and tuned page caches. MySQL and PostgreSQL utilize connection pools with automatic query preparation.
? Low-Resource Servers (≤ 250 MB RAM / 1 Core)
For ultra-compact nodes (e.g. VPS or low-cost cloud containers with 256MB RAM), add these flags to your launch script:
Optimization recommendations: Keep cache-max-users = 5000 in settings.conf, utilize default embedded SQLite storage (avoids external DB network drivers), and keep the web panel disabled.
? Multi-Version & Multi-Loader Compatibility
AuthCore maintains a single unified codebase utilizing Stonecutter and Stonecraft conditional compilation:
Unobfuscated 26.x Compatibility: Forward-compatible Mojang mappings allow instant builds against modern and future Minecraft versions; future snapshot lines are detected automatically at build time.
Non-Invasive Mixins: Mixins touch only login and authentication network stages, ensuring zero incompatibilities with performance optimization mods including Lithium, C2ME, Krypton, ModernFix, FerriteCore, and Spark.
?? Building From Source
Gradle toolchains auto-provision JDK 17, 21, and 25 (one per version group), so any installed JDK 17+ can launch the build. If portable JDKs are preferred, run test/install-java-and-provided-jars.sh to install Adoptium JDKs and the vendored proxy/API jars automatically. See CONTRIBUTING.md for the full developer guide.
# Build ALL 6 range variants (jars staged automatically into dist/)
./gradlew buildAll
# Build the currently active variant (1.21.11-fabric)
./gradlew build
# Build a specific loader and version target
./gradlew :1.18.2-fabric:build # -> dist/authcore-1.16-1.18-fabric-1.0.2.jar
./gradlew :1.18.2-forge:build # -> dist/authcore-1.16-1.18-forge-1.0.2.jar
./gradlew :1.21.11-fabric:build # -> dist/authcore-1.19-1.21-fabric-1.0.2.jar
./gradlew :1.21.11-neoforge:build # -> dist/authcore-1.19-1.21-neoforge-1.0.2.jar
./gradlew :26.3-fabric:build # -> dist/authcore-26.1-26.3-fabric-1.0.2.jar
./gradlew :26.3-neoforge:build # -> dist/authcore-26.1-26.3-neoforge-1.0.2.jar
? Security Testing
AuthCore features an autonomous security testing harness located in test/ with 229 automated unit and cryptographic checks plus an 18-check in-mod simulation suite:
# Compile and execute the full security test suite
./gradlew buildAll
test/run-security-tests.sh
# Run end-to-end local validation (compile + security suite + Docker host smoke tests)
./gradlew testAll
Migration Engine: Automated checks validating legacy single-file to split-configuration migrations.
Map images (new): palette discovery, map-data round-trip, locked-map behaviour, the give/take lifecycle (death, offhand, crash recovery, rate limits), an in-mod QR encoder verified against two independent decoders, captcha single-use/expiry/attempt limits, and the input bounds of every entry point. The map-content path is pure computation over bounded inputs - no file, network, process or reflection access and no client-controlled input - so it adds no RCE or bypass surface; QR payloads are never logged.
? Docker Verification (Host Tests)
To guarantee flawless runtime stability, our test harness boots every range jar across real Minecraft server containers in parallel using official Eclipse Temurin JRE images:
# Execute smoke matrix across all loader targets
test/docker/run-tests.sh --smoke
# Execute full matrix across all range endpoints
test/docker/run-tests.sh --all
# Run specific version brackets
test/docker/run-tests.sh --groups 1.16-1.18 --java 17
test/docker/run-tests.sh --groups 1.19-1.21 --java 21
test/docker/run-tests.sh --groups 26.1-26.3 --java 25
Each automated test validates:
Clean server startup with 0 errors and 0 severe warnings.
Banner accuracy (compiled version string, target loader, and Java runtime).
Configuration generation, SQLite database initialization, and network port binding.
The in-mod simulation suite (18/18 checks): hashing, live database, landing geometry, session flow, proxy gate, SRG runtime, bounded caches, map rendering, the map give/take lifecycle and map content/QR/captcha.
The matrix covers 17 (version, loader) combinations: Fabric 1.16.5/1.17.1/1.18.2/1.19.4/1.20.6/1.21.1/1.21.11/26.1.2/26.2/26.3, Forge 1.18.2 and NeoForge 1.20.6/1.21.1/1.21.11/26.1.2/26.2/26.3. Two SKIPs are genuine platform limits (Forge 1.16.5/1.17.1 cannot run a Java-17 jar; NeoForge does not exist for 1.19.4), not harness gaps.
Complete history of releases, feature additions, and security patches
❓ FAQ
Can offline and premium players both play on an online-mode server?
Yes. AuthCore features a built-in hybrid mode. On online-mode servers, ensure enable-secure-profile=false in server.properties so clients without Mojang chat signatures can connect. With allow-offline-players = true (default in settings.conf), both cracked and premium players can connect. Premium players auto-authenticate via async Mojang verification, while cracked players authenticate with passwords.
Does AuthCore work in LAN or offline test environments?
Yes. Private and loopback IP addresses (127.0.0.1, 10.x.x.x, 192.168.x.x) are never forwarded to external Mojang or GeoIP APIs. The server boots without requiring active internet connectivity.
Are there known incompatibilities with other mods?
None known. AuthCore has been extensively tested against performance optimization and utility mods including C2ME, Chunky, Lithium, Krypton, Ledger, ModernFix, FerriteCore, and Spark.
Can multiple servers share a single player credentials database?
Yes. Configure a shared MySQL or PostgreSQL database in database.conf, and activate Redis in session.conf for network-wide SSO session syncing and the cross-server security event bus.
Do players need to install client mods to connect?
No. AuthCore operates 100% server-side. Players connect using vanilla Minecraft clients or standard modded clients without installing any additional client-side software.
?️ Roadmap
Universal Multi-Loader Support: One codebase targeting Fabric, Forge, and NeoForge across 1.16.0 → 26.x+.
7-Layer Defense-in-Depth: Behavioral profiling, packet state machines, look-pattern analysis, and honeypots.
Browser Web Panel: Token-authenticated REST administration interface with live metrics.
Proxy Parity: Modern Velocity HMAC forwarding, legacy BungeeCord detection, and fail-closed security.
Automated Test Rigor: 229 automated cryptographic and security checks, an 18-check in-mod simulation suite, and a 17-endpoint parallel Docker matrix.
Split Configuration Architecture: Separate domain configs (lobby.conf, session.conf, database.conf) with automatic legacy migration.
? Community & Contributing
We warmly welcome community contributions, bug reports, and feature proposals!
Found a bug? Please open a GitHub Issue using the bug report form; include your AuthCore version, loader, and Minecraft/Java versions.
Have an idea? Open a feature request issue or start a thread in Discussions.
Want to submit code? Read CONTRIBUTING.md first; it covers the Stonecutter workspace, real build/test commands, branch guidance, and PR expectations, then fork and open a Pull Request.
Found a security vulnerability? Do not open a public issue; follow SECURITY.md and report it privately.
Need community support? Join us on Discord!
? License
AuthCore is licensed under the Apache License 2.0 with the Commons Clause. The authoritative text is the repo's LICENSE file. In short:
✅ You are free to use, fork, modify, and distribute AuthCore for any purpose, including commercial use, modpacks, and building products or services around it.
❌ You may not sell the software itself: AuthCore (or a product/service whose value derives entirely or substantially from it) may not be offered for sale as a paid product.
? The LICENSE file is authoritative; this section is only a friendly summary, not legal advice or the binding terms.
Contributions make the open-source community such an amazing place to learn, inspire and create. Any contributions you make are greatly appreciated - see CONTRIBUTING.md and the good first issues. Security concerns: please use SECURITY.md (private vulnerability reporting), not public issues.
⭐ Star History
Every public PotenFYR Studios repository on one live chart, served by star-history.com.
生命周期无内存泄漏且无重复。 地图从任何槽位(包括副手)移除,并将替换物品放回地图刚刚离开的槽位,因此完整库存不会吞没它;仅当地图仍被携带时才恢复物品,因此中途死亡/重生永远不会导致重复。断开连接会在保存玩家数据之前清除显示,地图 ID 持久化到 config/authcore/map-images.txt(有界),以便在下一次加入时清理崩溃/显示中断期间的残留。
无新增攻击面。 整个地图内容路径(编码、字形渲染、调色板查找)纯粹是对长度受限的字符串和整型数组的计算:不涉及文件、网络、进程或反射访问,不进行反序列化,也没有客户端可控的输入——唯一的输入来源是管理员命令或服务器端 API 调用。所有输入均经过边界限制和验证(有效载荷大小、QR 模块比例、标签字符集/长度、验证码答案标准化),失败时抛出 IllegalArgumentException,而不是分配内存或部分渲染。新的模组内 map-content-simulation 检查通过真实调色板渲染 QR 码和验证码文本,采样每个模块/字形单元格,测试验证码状态机并断言输入边界,从而确保管道在每个端点/加载器上都得到验证。
评论 0
登录后参与评分
还没有评论,来抢沙发吧