# darkkingturkey/darksauth architecture

> Architecture diagram of the GitHub repository darkkingturkey/darksauth, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/darkkingturkey/darksauth
- Repository: https://github.com/darkkingturkey/darksauth

## Overview

DarksAuth is a Paper/Spigot plugin for offline-mode Minecraft servers, combining Mojang packet-handshake verification with password-based cracked-account authentication. Players join through premium profile verification or a cracked-account login/register flow; authenticated sessions then lift gameplay restrictions. Commands, brute-force controls, SQLite persistence, and optional server integrations support that flow. The README documents several capabilities whose implementation was not sampled, so their wiring is shown only where supported by the excerpts or documentation.

Main entry points: [`src/main/java/com/darks/auth/auth/AuthManager.java`](https://github.com/darkkingturkey/darksauth/blob/main/src/main/java/com/darks/auth/auth/AuthManager.java) (Session manager), [`src/main/java/com/darks/auth/protocol/ProtocolLoginHandler.java`](https://github.com/darkkingturkey/darksauth/blob/main/src/main/java/com/darks/auth/protocol/ProtocolLoginHandler.java) (Login handler), [`src/main/java/com/darks/auth/storage/AccountRepository.java`](https://github.com/darkkingturkey/darksauth/blob/main/src/main/java/com/darks/auth/storage/AccountRepository.java) (Account records), [`src/main/java/com/darks/auth/storage/DatabaseManager.java`](https://github.com/darkkingturkey/darksauth/blob/main/src/main/java/com/darks/auth/storage/DatabaseManager.java) (Database manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_startup["Plugin setup"]
  node_plugin["Plugin lifecycle"]
end

subgraph group_identity["Identity checks"]
  node_protocol["Login handler"]
  node_mojangsvc["Mojang lookup<br/>[MojangService.java]"]
  node_encryption["Handshake crypto"]
  node_premium["Profile data<br/>[MojangProfile.java]"]
end

subgraph group_auth["Authentication"]
  node_authmgr["Session manager<br/>[AuthManager.java]"]
  node_sessions["Player sessions<br/>[AuthSession.java]"]
  node_restrictions["Access restrictions"]
  node_register["Register command"]
  node_login["Login command<br/>[LoginCommand.java]"]
  node_password["Password hashing"]
  node_brute["Lockout control"]
end

subgraph group_state["Accounts and state"]
  node_admin["Admin commands"]
  node_overrides["Status overrides"]
  node_accounts["Account records"]
  node_cache["Mojang cache"]
  node_attempts["Login attempts"]
  node_dbmanager["Database manager"]
end

subgraph group_integrations["Server integrations"]
  node_luckperms["LuckPerms context<br/>[LuckPermsHook.java]"]
  node_placeholders["Status placeholders"]
  node_voicehook["Voice isolation<br/>[VoiceChatHook.java]"]
  node_logfilter["Command log filter"]
end

node_player(("Minecraft player"))
node_paper["Paper server"]
node_mojang["Mojang services"]
node_sqlite[("SQLite database")]
node_protocollib["ProtocolLib"]
node_voicechat["Simple Voice Chat"]

node_player -->|"joins"| node_paper
node_paper -->|"pre-login dispatch"| node_protocol
node_protocol -->|"checks overrides"| node_accounts
node_protocol -->|"queries profiles"| node_mojangsvc
node_mojangsvc -->|"requests profile"| node_mojang
node_mojangsvc -->|"reads and writes"| node_cache
node_protocol -->|"starts or completes session"| node_authmgr
node_protocol -->|"uses handshake crypto"| node_encryption
node_protocol -->|"intercepts packets"| node_protocollib
node_register -->|"requests registration"| node_authmgr
node_login -->|"requests login"| node_authmgr
node_register -->|"stores account"| node_accounts
node_login -->|"checks account"| node_accounts
node_register -->|"hashes password"| node_password
node_login -->|"checks password"| node_password
node_login -->|"checks failures"| node_brute
node_brute -->|"tracks lockouts"| node_attempts
node_authmgr -->|"updates account state"| node_accounts
node_authmgr -->|"maintains sessions"| node_sessions
node_authmgr -->|"session state checked"| node_restrictions
node_paper -->|"game events"| node_restrictions
node_admin -->|"manages records"| node_accounts
node_overrides -->|"sets account status"| node_accounts
node_plugin -->|"initializes storage"| node_dbmanager
node_dbmanager -->|"opens database"| node_sqlite
node_accounts -->|"queries and updates"| node_dbmanager
node_cache -->|"queries and updates"| node_dbmanager
node_attempts -->|"queries and updates"| node_dbmanager
node_plugin -->|"registers handler"| node_protocol
node_plugin -->|"initializes manager"| node_authmgr
node_authmgr -.->|"authentication context"| node_luckperms
node_authmgr -.->|"status access"| node_placeholders
node_authmgr -.->|"authentication checks"| node_voicehook
node_voicehook -.->|"mutes and filters audio"| node_voicechat
node_logfilter -->|"filters console commands"| node_paper

click node_plugin "https://github.com/darkkingturkey/darksauth/blob/main/src/main/java/com/darks/auth/DarksAuthPlugin.java"
click node_protocol "https://github.com/darkkingturkey/darksauth/blob/main/src/main/java/com/darks/auth/protocol/ProtocolLoginHandler.java"
click node_mojangsvc "https://github.com/darkkingturkey/darksauth/blob/main/src/main/java/com/darks/auth/api/MojangService.java"
click node_encryption "https://github.com/darkkingturkey/darksauth/blob/main/src/main/java/com/darks/auth/protocol/EncryptionUtils.java"
click node_premium "https://github.com/darkkingturkey/darksauth/blob/main/src/main/java/com/darks/auth/api/MojangProfile.java"
click node_authmgr "https://github.com/darkkingturkey/darksauth/blob/main/src/main/java/com/darks/auth/auth/AuthManager.java"
click node_sessions "https://github.com/darkkingturkey/darksauth/blob/main/src/main/java/com/darks/auth/auth/AuthSession.java"
click node_restrictions "https://github.com/darkkingturkey/darksauth/blob/main/src/main/java/com/darks/auth/listener/PlayerRestrictionListener.java"
click node_register "https://github.com/darkkingturkey/darksauth/blob/main/src/main/java/com/darks/auth/command/RegisterCommand.java"
click node_login "https://github.com/darkkingturkey/darksauth/blob/main/src/main/java/com/darks/auth/command/LoginCommand.java"
click node_password "https://github.com/darkkingturkey/darksauth/blob/main/src/main/java/com/darks/auth/auth/PasswordHasher.java"
click node_brute "https://github.com/darkkingturkey/darksauth/blob/main/src/main/java/com/darks/auth/auth/BruteForceManager.java"
click node_admin "https://github.com/darkkingturkey/darksauth/blob/main/src/main/java/com/darks/auth/command/DarksAuthAdminCommand.java"
click node_overrides "https://github.com/darkkingturkey/darksauth/blob/main/src/main/java/com/darks/auth/command/PremiumCommand.java"
click node_accounts "https://github.com/darkkingturkey/darksauth/blob/main/src/main/java/com/darks/auth/storage/AccountRepository.java"
click node_cache "https://github.com/darkkingturkey/darksauth/blob/main/src/main/java/com/darks/auth/storage/MojangCacheRepository.java"
click node_attempts "https://github.com/darkkingturkey/darksauth/blob/main/src/main/java/com/darks/auth/storage/LoginAttemptRepository.java"
click node_dbmanager "https://github.com/darkkingturkey/darksauth/blob/main/src/main/java/com/darks/auth/storage/DatabaseManager.java"
click node_luckperms "https://github.com/darkkingturkey/darksauth/blob/main/src/main/java/com/darks/auth/hook/LuckPermsHook.java"
click node_placeholders "https://github.com/darkkingturkey/darksauth/blob/main/src/main/java/com/darks/auth/hook/PlaceholderApiHook.java"
click node_voicehook "https://github.com/darkkingturkey/darksauth/blob/main/src/main/java/com/darks/auth/hook/VoiceChatHook.java"
click node_logfilter "https://github.com/darkkingturkey/darksauth/blob/main/src/main/java/com/darks/auth/listener/ConsoleLogFilter.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_plugin toneBlue
class node_protocol,node_mojangsvc,node_encryption,node_premium,node_sqlite toneAmber
class node_authmgr,node_sessions,node_restrictions,node_register,node_login,node_password,node_brute,node_paper toneMint
class node_admin,node_overrides,node_accounts,node_cache,node_attempts,node_dbmanager toneRose
class node_luckperms,node_placeholders,node_voicehook,node_logfilter,node_player,node_mojang,node_protocollib,node_voicechat toneIndigo
```

## Components

### Plugin setup

- [Plugin lifecycle](https://github.com/darkkingturkey/darksauth/blob/main/src/main/java/com/darks/auth/DarksAuthPlugin.java): `src/main/java/com/darks/auth/DarksAuthPlugin.java`

### Identity checks

- [Login handler](https://github.com/darkkingturkey/darksauth/blob/main/src/main/java/com/darks/auth/protocol/ProtocolLoginHandler.java): `src/main/java/com/darks/auth/protocol/ProtocolLoginHandler.java`
- [Mojang lookup](https://github.com/darkkingturkey/darksauth/blob/main/src/main/java/com/darks/auth/api/MojangService.java): `src/main/java/com/darks/auth/api/MojangService.java`
- [Handshake crypto](https://github.com/darkkingturkey/darksauth/blob/main/src/main/java/com/darks/auth/protocol/EncryptionUtils.java): `src/main/java/com/darks/auth/protocol/EncryptionUtils.java`
- [Profile data](https://github.com/darkkingturkey/darksauth/blob/main/src/main/java/com/darks/auth/api/MojangProfile.java): `src/main/java/com/darks/auth/api/MojangProfile.java`

### Authentication

- [Session manager](https://github.com/darkkingturkey/darksauth/blob/main/src/main/java/com/darks/auth/auth/AuthManager.java): `src/main/java/com/darks/auth/auth/AuthManager.java`
- [Player sessions](https://github.com/darkkingturkey/darksauth/blob/main/src/main/java/com/darks/auth/auth/AuthSession.java): `src/main/java/com/darks/auth/auth/AuthSession.java`
- [Access restrictions](https://github.com/darkkingturkey/darksauth/blob/main/src/main/java/com/darks/auth/listener/PlayerRestrictionListener.java): `src/main/java/com/darks/auth/listener/PlayerRestrictionListener.java`
- [Register command](https://github.com/darkkingturkey/darksauth/blob/main/src/main/java/com/darks/auth/command/RegisterCommand.java): `src/main/java/com/darks/auth/command/RegisterCommand.java`
- [Login command](https://github.com/darkkingturkey/darksauth/blob/main/src/main/java/com/darks/auth/command/LoginCommand.java): `src/main/java/com/darks/auth/command/LoginCommand.java`
- [Password hashing](https://github.com/darkkingturkey/darksauth/blob/main/src/main/java/com/darks/auth/auth/PasswordHasher.java): `src/main/java/com/darks/auth/auth/PasswordHasher.java`
- [Lockout control](https://github.com/darkkingturkey/darksauth/blob/main/src/main/java/com/darks/auth/auth/BruteForceManager.java): `src/main/java/com/darks/auth/auth/BruteForceManager.java`

### Accounts and state

- [Admin commands](https://github.com/darkkingturkey/darksauth/blob/main/src/main/java/com/darks/auth/command/DarksAuthAdminCommand.java): `src/main/java/com/darks/auth/command/DarksAuthAdminCommand.java`
- [Status overrides](https://github.com/darkkingturkey/darksauth/blob/main/src/main/java/com/darks/auth/command/PremiumCommand.java): `src/main/java/com/darks/auth/command/PremiumCommand.java`
- [Account records](https://github.com/darkkingturkey/darksauth/blob/main/src/main/java/com/darks/auth/storage/AccountRepository.java): `src/main/java/com/darks/auth/storage/AccountRepository.java`
- [Mojang cache](https://github.com/darkkingturkey/darksauth/blob/main/src/main/java/com/darks/auth/storage/MojangCacheRepository.java): `src/main/java/com/darks/auth/storage/MojangCacheRepository.java`
- [Login attempts](https://github.com/darkkingturkey/darksauth/blob/main/src/main/java/com/darks/auth/storage/LoginAttemptRepository.java): `src/main/java/com/darks/auth/storage/LoginAttemptRepository.java`
- [Database manager](https://github.com/darkkingturkey/darksauth/blob/main/src/main/java/com/darks/auth/storage/DatabaseManager.java): `src/main/java/com/darks/auth/storage/DatabaseManager.java`

### Server integrations

- [LuckPerms context](https://github.com/darkkingturkey/darksauth/blob/main/src/main/java/com/darks/auth/hook/LuckPermsHook.java): `src/main/java/com/darks/auth/hook/LuckPermsHook.java`
- [Status placeholders](https://github.com/darkkingturkey/darksauth/blob/main/src/main/java/com/darks/auth/hook/PlaceholderApiHook.java): `src/main/java/com/darks/auth/hook/PlaceholderApiHook.java`
- [Voice isolation](https://github.com/darkkingturkey/darksauth/blob/main/src/main/java/com/darks/auth/hook/VoiceChatHook.java): `src/main/java/com/darks/auth/hook/VoiceChatHook.java`
- [Command log filter](https://github.com/darkkingturkey/darksauth/blob/main/src/main/java/com/darks/auth/listener/ConsoleLogFilter.java): `src/main/java/com/darks/auth/listener/ConsoleLogFilter.java`

### Other components

- **Minecraft player**
- **Paper server**
- **Mojang services**
- **SQLite database**
- **ProtocolLib**
- **Simple Voice Chat**

## Connections

- Minecraft player → Paper server: joins
- Paper server → Login handler: pre-login dispatch
- Login handler → Account records: checks overrides
- Login handler → Mojang lookup: queries profiles
- Mojang lookup → Mojang services: requests profile
- Mojang lookup → Mojang cache: reads and writes
- Login handler → Session manager: starts or completes session
- Login handler → Handshake crypto: uses handshake crypto
- Login handler → ProtocolLib: intercepts packets
- Register command → Session manager: requests registration
- Login command → Session manager: requests login
- Register command → Account records: stores account
- Login command → Account records: checks account
- Register command → Password hashing: hashes password
- Login command → Password hashing: checks password
- Login command → Lockout control: checks failures
- Lockout control → Login attempts: tracks lockouts
- Session manager → Account records: updates account state
- Session manager → Player sessions: maintains sessions
- Session manager → Access restrictions: session state checked
- Paper server → Access restrictions: game events
- Admin commands → Account records: manages records
- Status overrides → Account records: sets account status
- Plugin lifecycle → Database manager: initializes storage
- Database manager → SQLite database: opens database
- Account records → Database manager: queries and updates
- Mojang cache → Database manager: queries and updates
- Login attempts → Database manager: queries and updates
- Plugin lifecycle → Login handler: registers handler
- Plugin lifecycle → Session manager: initializes manager
- Session manager → LuckPerms context: authentication context
- Session manager → Status placeholders: status access
- Session manager → Voice isolation: authentication checks
- Voice isolation → Simple Voice Chat: mutes and filters audio
- Command log filter → Paper server: filters console commands