AuthCore

The Fortress Framework for Minecraft Servers. One unified codebase for 1.16.0 → 26.x+ on Fabric, Forge, and NeoForge.
Hardened against every attack scenario, race-condition-free under burst load, and engineered to hold 500k+ registered accounts and thousands of concurrent players with flat, spike-free resource usage.

Quick Start • Highlights • Jar Matrix • Architecture • Commands • Configuration • Security Model • Live Metrics • Community

---

📑 Contents

✨ Highlights & Core Philosophy

🚀 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]

1. Pick the Right Jar: Select the jar matching your server loader and Minecraft version from the Jar Matrix via Modrinth or GitHub Releases.
2. Install: Drop the jar file directly into your server's mods/ directory (or your proxy's plugins/ directory).
3. Start the Server: AuthCore boots out of the box with zero required configuration. An embedded SQLite database (authcore.db) is automatically provisioned in config/authcore/.
4. 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 or check the interactive web panel at https://127.0.0.1:25570.

┌─────────────────────────────────────────────────────────────┐
│  ✓  AUTHCORE v1.0.0 — FORTRESS FRAMEWORK INITIALIZED       │
├─────────────────────────────────────────────────────────────┤
│  Platform         : Fabric / Forge / NeoForge / Velocity   │
│  Minecraft        : 1.16.0 → 26.x+ (Universal Range Engine) │
│  Database         : SQLite (WAL) / MySQL / PostgreSQL       │
│  Security Stack   : 7-Layer Detection Bypass Resistance     │
│  Crypto           : Argon2id (M:64MB, T:3, P:1) + SCRAM     │
│  Proxy Forwarding : Auto-Detected (Velocity HMAC / Bungee)  │
│  Web Panel        : https://127.0.0.1:25570 (Token Guarded) │
│  Status           : 0 Warnings · 180+ Security Audits PASS  │
└─────────────────────────────────────────────────────────────┘

[!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:

[!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.

🧩 Architecture & Authentication Lifecycle

flowchart TD
    subgraph Connect["1. Handshake & Threat Interception"]
        Join([Player Joins Server]) --> DetectProxy["Detect Proxy & Forwarding\n(BungeeCord / Velocity HMAC)"]
        DetectProxy --> Intercept["ClientGuard Inspection\nPacket Floods · Ghost Anomaly · Look Variance"]
        Intercept --> RateLimit{"Exceeds Rate Limits\nor Denied IP CIDR?"}
        RateLimit -->|Yes| KickDrop["Drop Connection / Honeypot Alert"]
        RateLimit -->|No| Limbo["Anchor Player in Limbo\nInert Inventory · Zero Drift · Throttled Teleport"]
    end

    subgraph AuthEval["2. Authentication & Verification"]
        Limbo --> CheckMode{"Server / Account Mode"}
        CheckMode -->|Premium Auto-Login| MojangCheck["Async Mojang Session Verification\n(Resilient to Mojang API Outages)"]
        MojangCheck -->|Verified| PassAuth["Bypass Password Auth"]
        CheckMode -->|Offline / Cracked| PromptAuth["Display Dynamic Title / Action Bar\nPrompt /register or /login"]
        PromptAuth --> CaptchaCheck{"Risk Score Triggered?"}
        CaptchaCheck -->|High Risk| TaskCaptcha["Enforce Action Captcha\n(Sneak / Jump / Head Turn)"]
        CaptchaCheck -->|Normal| CredentialCheck["Verify Hash (Argon2id/BCrypt/SCRAM)\nOr TOTP 2FA / Email OTP"]
        TaskCaptcha --> CredentialCheck
    end

    subgraph SessionBind["3. Session Binding & In-Game Release"]
        CredentialCheck -->|Success| PassAuth
        PassAuth --> SessionIssue["Issue Session Token & Redis SSO Broadcast"]
        SessionIssue --> RestoreState["Restore Player Position, Inventory & Capabilities"]
        RestoreState --> InGame([Full Game Access Granted])
    end

🛡️ Detection Bypass Resistance

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:

Architectural Security Guarantees

• 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

Admin Commands

Access requires Minecraft OP level 3+, LuckPerms permission node, or server console execution.

⚙️ 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:

Example Configuration Snippet

# settings.conf
language = "en"              # en | zh | es | de | fr | pt | ru
cache-max-users = 20000      # Bounded LRU cache size

# session.conf
session {
    # Server online/offline mode is automatically detected from server.properties!
    timeout-ms = 3600000     # Active session validity (60 minutes)

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

    security {
        webhook-url = "https://discord.com/api/webhooks/..." # Discord security alerts
    }

    proxy-support {
        enabled = false       # Enable when placed behind Velocity or BungeeCord
        protocol = "auto"     # Supports "auto", "velocity", "bungeecord"
    }

    web-panel {
        enabled = false       # REST administration dashboard
        host = "127.0.0.1"
        port = 25570
        token = "CHANGE_ME"   # Generate via: openssl rand -hex 16
    }

    email {
        enabled = false       # SMTP recovery codes and login alerts
        host = "smtp.gmail.com"
        port = 587
        username = "[email protected]"
        password = "app-password"
        from = "AuthCore Security <[email protected]>"
    }
}

# lobby.conf
lobby {
    movement-correction-radius = 1.5      # Distance before non-jittery snap-back
    movement-correction-interval-ms = 600 # Minimum time between position corrections
}

🚦 Feature Setup at a Glance

All features in AuthCore are modular and optional. Zero setup is required for basic SQLite usage. Activate only what your network demands:

🌍 Languages

AuthCore natively includes 7 community-translated languages out of the box. The active language is controlled via language = "en" in settings.conf:

[!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 coexist seamlessly 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 effortlessly 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:

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

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:

src/main/java/          --> Shared canonical Java source tree
├── in/potenfyr/authcore/
│   ├── api/            --> AuthCore public developer API
│   ├── auth/           --> Authentication controllers & 2FA
│   ├── cache/          --> High-throughput lockless caches
│   ├── command/        --> Cross-platform command handlers
│   ├── config/         --> Split HOCON configuration manager
│   ├── database/       --> SQLite, MySQL, PostgreSQL, Redis drivers
│   ├── listener/       --> Cross-loader event listeners
│   ├── mixin/          --> Universal platform mixins
│   ├── model/          --> User and session data models
│   ├── proxy/          --> Velocity & BungeeCord IP forwarding
│   ├── security/       --> 7-layer detection bypass & ClientGuard
│   └── web/            --> HTTPS token-authenticated REST web panel

• Loader Independence: Thin entrypoints (FabricEntry, ForgeEntry, NeoForgeEntry) bridge native loader hooks into AuthCore's universal engine.
• Unobfuscated 26.x Compatibility: Forward-compatible Mojang mappings allow instant builds against modern and future Minecraft versions.
• 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

AuthCore requires JDK 25 to compile all project targets (enforced by the modern 26.1–26.2 build pipeline). If portable JDKs are needed, execute test/install-java-and-provided-jars.sh to automatically install Adoptium JDKs 17, 21, and 25.

# 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.0.jar
./gradlew :1.18.2-forge:build       # -> dist/authcore-1.16-1.18-forge-1.0.0.jar
./gradlew :1.21.11-fabric:build     # -> dist/authcore-1.19-1.21-fabric-1.0.0.jar
./gradlew :1.21.11-neoforge:build   # -> dist/authcore-1.19-1.21-neoforge-1.0.0.jar
./gradlew :26.2-fabric:build        # -> dist/authcore-26.1-26.2-fabric-1.0.0.jar
./gradlew :26.2-neoforge:build      # -> dist/authcore-26.1-26.2-neoforge-1.0.0.jar

🧪 Security Testing

AuthCore features an autonomous security testing harness located in test/ with 180+ automated unit and cryptographic checks:

# 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

Audited components include:

• Hashing Algorithms: Argon2id, BCrypt, SCrypt, PBKDF2, SHA-256, and legacy hash transparent auto-upgrading.
• Cryptographic Security: CSPRNG salt uniqueness, constant-time comparisons, and timing leak prevention.
• Exploit & Abuse Defenses: Captcha state machine lifecycle, SMTP token expiry, camera look-pattern variance, and bot farm concurrency detection.
• Migration Engine: 18 automated checks validating legacy single-file to split-configuration migrations.

🐳 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

# 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.2 --java 25

Each automated test validates:

1. Clean server startup with 0 errors and 0 severe warnings.
2. Banner accuracy (compiled version string, target loader, and Java runtime).
3. Admin console command execution (/authcore validate, /authcore reload, /authcore backup).
4. Configuration generation, SQLite database initialization, and network port binding.

📚 Documentation

Detailed documentation guides are hosted at authcore.potenfyr.in:

❓ FAQ

🗺️ 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.
• Multi-Factor Authentication: TOTP authenticator apps, backup recovery codes, and one-time SMTP email verification.
• Anti-Abuse Engine: Brute-force lockouts, dynamic action captchas, CIDR IP filters, and shadow-bans.
• Enterprise Storage: High-performance SQLite (WAL), MySQL, PostgreSQL, and Redis SSO event buses.
• 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: 180+ automated cryptographic and security checks with parallel Docker host tests.
• Split Configuration Architecture: Separate domain configs (lobby.conf, session.conf, database.conf) with automatic legacy migration.

📈 Activity, Star History & Metrics

🌟 Real-time Star History

📈 Live star graph rendered via star-history.com. Updates in real-time as users star the repository.

🤝 Community & Contributing

We warmly welcome community contributions, bug reports, and feature proposals!

• Found a bug or have an idea? Submit an issue on the Issue Tracker or start a thread in Discussions.
• Submitting code? Fork the repository, create a descriptive branch, and submit a Pull Request conforming to Google Java Format standards.
• Need community support or direct assistance? Join us on Discord!

📜 License

This project is licensed under the CC0 1.0 Universal (Public Domain) license. You may freely use, modify, distribute, and integrate AuthCore into personal, commercial, or modpack distributions without restriction.

Crafted with passion by PotenFYR Studios
Support & Inquiries: [email protected]