CrossAuth & CrossForward: The Complete Manual
1.0 Introduction
CrossAuth is a distributed authentication framework designed for Minecraft networks running on the BungeeCord protocol. Unlike traditional auth plugins that run on a single server, CrossAuth operates on the Network Layer (Proxy), providing global authentication. CrossForward is the downstream client that enforces the proxy's will on the game servers.

1.1 Architecture
The system utilizes a Master-Slave architecture:

• The Master (CrossAuth - BungeeCord): Handles database I/O, API requests, encryption, session tokens, and command parsing.
  
  
• The Slave (CrossForward - Spigot): Listens for binary plugin messages (crossauth:data). It has no database access and no configuration. It simply obeys "Lock" and "Unlock" commands.

2.0 Installation & Network Topology
2.1 Network Requirements

• Java Runtime: JDK 21 (Required for modern encryption libraries).
  
  
• Proxy: BungeeCord, Waterfall, or WaterdogPE.
  
  
• Backend: Spigot, Paper, Purpur (1.21+ recommended).

2.2 The "Offline Mode" Security Gap
To run a hybrid server, your backend Spigot servers MUST be set to online-mode: false. This creates a massive security vulnerability: if a user can connect directly to your Spigot server's port (e.g., 25565) bypassing the Proxy, they can join as "Notch" or "Admin" without a password.

CRITICAL SECURITY STEP: You must configure your firewall (UFW/IPTables) to DENY all connections to your Spigot ports except from Localhost (127.0.0.1).

Example UFW Command (Linux):

codeBash

sudo ufw deny 25565/tcp
sudo ufw allow from 127.0.0.1 to any port 25565 proto tcp
Failure to do this renders any Auth plugin useless.

3.0 Configuration Deep Dive
The configuration is generated automatically in plugins/CrossAuth20/config.yml on the Proxy.

3.1 Security Settings
codeYaml

# Time in SECONDS before a player is kicked if they don't login
login-timeout: 60
This controls the window a cracked player has to enter credentials. If they idle, the proxy disconnects them to save resources.

codeYaml

# Time in MINUTES to keep a session active
session-minutes: 30
CrossAuth uses IP-based session persistence. If a player disconnects, their IP is cached in memory. If they return within 30 minutes from the same IP, the password prompt is skipped. This is vital for "Hub -> Survival" server switching.

codeYaml

# Prevent cracked players from joining with a Premium username
protect-premium-names: true
Mechanism:

1. Player Notch joins.
   
   
2. CrossAuth queries Mojang API.
   
   
3. Result: Notch is a valid Premium account.
   
   
4. CrossAuth checks the connection type.
   
   
5. If connection is Offline (Cracked client), CrossAuth blocks the connection immediately.
   This prevents identity theft of famous users.

3.2 Spawn & Teleportation
codeYaml

force-spawn-join: true
spawn-server-name: 'lobby'
When enabled, this overrides the player's last location.

• Scenario: A player logs out in a lava pool in Survival.
  
  
• On Join: CrossAuth intercepts the connection and forces them to the lobby server to authenticate safely.
  
  
• After Auth: CrossAuth calculates their previous server and sends them back (if configured) or keeps them in the lobby.

3.3 Encryption Internals
codeYaml

encryption-key: 'a1b2c3d4...'
DO NOT SHARE THIS KEY.
CrossAuth uses this key to salt and encrypt the local local_data.db file.

• Algorithm: AES-256 (Advanced Encryption Standard).
  
  
• Hashing: SHA-256 for password comparison.
  
  
• Impact: If you lose this key, ALL cracked player data becomes unreadable. Back up your config file!

4.0 The Verification Process (Technical Flow)
When a player connects, the following asynchronous logic chain triggers:

1. Pre-Login:
   • Proxy accepts connection.
     
     
   • Proxy performs handshake.
2. Async Auth Check (PostLoginEvent):
   • Step 1: Local Session: Check memory for active session. If valid -> ALLOW.
     
     
   • Step 2: Cloud Verification: The plugin sends a GET request to the proprietary API node.
     • Payload: UUID, Username, IP.
       
       
     • Response: JSON object indicating if the user is known as Premium in the global database.
   • Step 3: Mojang Fallback: If Cloud Node returns false, query Mojang Profile API.
     • If Mojang returns 200 OK -> Mark as PREMIUM -> Save to Cloud -> ALLOW.
       
       
     • If Mojang returns 204 No Content -> Mark as CRACKED.
3. The Cracked Pathway:
   • Player is marked as "Pending Auth".
     
     
   • Proxy sends Plugin Message Lock -> Spigot.
     
     
   • CrossForward (Spigot):
     • Cancels PlayerMoveEvent (X/Z axis).
       
       
     • Cancels InventoryOpenEvent.
       
       
     • Cancels AsyncPlayerChatEvent.
       
       
     • Applies Potion Effects (Blindness 255).
   • Reminder Task: Every 5 seconds, Proxy sends a Title/Actionbar message.
4. The Unlock:
   • Player types /login password.
     
     
   • Proxy hashes input: SHA256(input).
     
     
   • Compares with local_data.db (AES Decrypted).
     
     
   • If Match:
     • Update Session map.
       
       
     • Send Plugin Message Unlock -> Spigot.
       
       
     • CrossForward: Removes potions, plays sound, clears listener blocks.

5.0 API & Webhooks
The plugin communicates with a backend endpoint defined internally.

• Endpoint: HIDDEN_FOR_SECURITY
  
  
• Method: POST/GET
  This allows the server to sync Premium status across multiple distinct networks using the same software, creating a "Global Trust" network for premium players.

6.0 Troubleshooting
6.1 "Authentication Service Unavailable"

• Cause: The Proxy server cannot reach the API or Mojang.
  
  
• Fix: Check your server's DNS settings. Ensure outbound connections to api.mojang.com are allowed.

6.2 "You must authenticate first" (Spam)

• Cause: The player is trying to move, but CrossForward is doing its job.
  
  
• Fix: This is intended behaviour. The player must type /login.

6.3 Database Decryption Failed

• Cause: You deleted or changed the encryption-key in config.ym,l but kept the old local_data.db file.
  
  
• Fix: Restore the old key from a backup, or delete local_data.db to reset all cracked accounts.

© 2025 SkipTheUpdate. All Rights Reserved.