##
---

## Plugin Overview

ChunkifyAuth is an enterprise-grade authentication and security plugin for Minecraft servers (1.16.5+). It provides comprehensive account security, session management, audit logging, and caching with multi-language support and cross-version compatibility.

✓ Supports Minecraft 1.16.5 through Latest Versions

---

## Core Security Features

### Password Management

• BCrypt Hashing: Industry-standard password encryption with configurable cost factor (4-31)
• Automatic Migration: Legacy password rehashing with optional user prompts
• Password Validation: Configurable strength requirements (min length, special chars, etc.)
• Secure Storage: Passwords never stored in plain text, even in logs

### Rate Limiting & Brute Force Protection

• Login Attempt Tracking: Track failed attempts per player/IP
• Account Lockout: Automatic lockout after configurable failed attempts
• IP-Based Blocking: Block IPs after suspicious activity
• Cooldown System: Progressive cooldowns between attempts

### Security Manager

• 
  al Backoff:[/B] Increasing delays after failed authentication
• Persistent Threat Tracking: Remember suspicious IPs and accounts
• Admin Controls: Commands to unlock accounts and manage threats
• Real-time Monitoring: Log security events with full context

---

## Session Management

### Session Features

• Active Session Tracking: Know exactly which players are authenticated
• Configurable Timeouts: Set session duration (default 1 hour)
• Per-Player Sessions: Individual timeout per player
• Forced Re-Authentication: Automatic logout on timeout

### Player Protection

• Chat/Command Blocking: Prevent unauthenticated actions
• Block Breaking Prevention: No resource gathering before login
• Block Placement Prevention: No building before login
• Item Drop Prevention: No item loss before authentication
• Combat Blocking: No damage taken/dealt before login

---

## Multi-Backend Storage

### Database Support

• MySQL/MariaDB: Enterprise-grade database storage
• JSON Local Storage: Built-in file-based fallback
• Connection Pooling: HikariCP for optimized connections
• Automatic Failover: Falls back to JSON if MySQL unavailable

### Data Features

• Automatic Migration: Local → Database migration on startup
• Health Checks: Regular database connectivity verification
• Retry Logic: Configurable retry attempts with backoff
• Connection Timeout: Customizable timeout per operation

---

## ⚡ High-Performance Caching

### Cache System

• Session Caching: Fast authentication checks with LRU eviction
• Configurable TTL: Set expiration time per use case
• Statistics Tracking: Monitor cache performance (hits/misses)
• LRU Eviction: Automatic least-recently-used cleanup
• Auto Cleanup: Background thread removes expired entries

### Performance Benefits

• Reduced database queries
• Sub-millisecond authentication checks
• Lower server CPU usage
• Configurable cache size (default 10,000 entries)

---

## Audit Logging

### Comprehensive Event Tracking

• Login Attempts: All authentication events with outcomes
• Failed Attempts: Track and log security threats
• Account Management: Register, unregister, unlock events
• Admin Actions: All admin commands logged

### Log Data

• Player name and UUID
• IP address and timestamp
• Event type and status
• Configurable retention policy
• Easy to parse format

---

## Multi-Language Support

### Built-in Languages

• ✓ English (en)
• ✓ Spanish (es)
• Extensible: Easy to add more languages

### Message Customization

• Configurable language in config.yml
• Custom messages per server
• Color code support (&c, &a, etc.)
• Dynamic placeholders (player names, etc.)

---

## ✅ Cross-Version Compatibility

### Version Support

• ✓ Minecraft 1.16.5 - Minimum supported
• ✓ Minecraft 1.17-1.19 - Full compatibility
• ✓ Minecraft 1.20.x - Latest stable
• ✓ Minecraft 1.20.5+ - Forward compatible

### Automatic Detection

• No NMS (Net Minecraft Server) code used
• Automatic version detection at startup
• Graceful fallback mechanisms
• Works with Spigot, Paper, Purpur, Folia

---

## Player Commands

### Authentication Commands

Command	Description
/login <password>	Login to your account
/register <password> <confirm>	Create new account
/logout	Logout from current session

---

## ⚙️ Admin Commands

### Management Commands

Command	Permission	Description
/unregister <player>	chunkifyauth.admin	Remove player account
/authreload	chunkifyauth.admin	Reload configuration
/authAdmin unlock <player>	chunkifyauth.admin	Unlock account
/authAdmin stats	chunkifyauth.admin	View authentication stats
/authAdmin audit <player>	chunkifyauth.admin	View audit log
/authAdmin cache	chunkifyauth.admin	View cache statistics
/authAdmin security	chunkifyauth.admin	View security stats

---

## ️ Bypass Permissions

### Permission Nodes

• chunkifyauth.bypass - Skip authentication requirement
• chunkifyauth.admin - Access admin commands
• chunkifyauth.reload - Reload configuration

---

## ⚙️ Configuration

### Main Settings
---

## Performance Specifications

### System Requirements

• Java: 8+
• Minecraft: 1.16.5+
• RAM: 128MB minimum (512MB+ recommended)
• Storage: 50MB for installation + database

### Performance Benchmarks

• Login check: < 1ms (cached)
• Authentication: 50-200ms (depends on bcrypt cost)
• Cache lookup: < 0.1ms
• Database query: 10-50ms
• Audit log write: Async (non-blocking)

---

## Enterprise Features

### Reliability

• Health Checks: Regular database connectivity verification
• Automatic Failover: Falls back to JSON if database unavailable
• Retry Logic: Configurable retries with exponential backoff
• Error Handling: Graceful degradation on errors

### Monitoring

• Event Logging: All security events tracked
• Statistics: Cache hit rates, authentication counts
• Performance Metrics: Response times and error rates
• Admin Dashboard: Commands to view real-time stats

---

## Changelog - v1.2.0

### Major Updates

• ✓ NEW: Cross-version compatibility layer
• ✓ NEW: VersionCompat automatic detection
• ✓ NEW: ChatCompat unified messaging
• ✓ NEW: EventCompat safe operations
• ✓ NEW: Cache statistics tracking
• ✓ NEW: LRU cache eviction policy
• IMPROVED: Database health checking
• IMPROVED: Configuration validation
• IMPROVED: Error handling throughout

### Bug Fixes

• Fixed compatibility with Paper servers
• Improved fallback mechanisms for older versions
• Enhanced null pointer safety
• Better error messages

---

## License & Support

### Compatibility Notes

• Works with vanilla Bukkit
• Fully compatible with Paper
• Supports Purpur
• Compatible with Folia (threading-safe)

### Support Channels

• Documentation: See included .md files
• Issues: Check TROUBLESHOOTING section in docs
• Configuration: See config.yml with full comments

---

## Why Choose ChunkifyAuth?

• Enterprise-grade security with BCrypt encryption
• 100% version compatibility (1.16.5+)
• High-performance caching with LRU eviction
• Multi-language support (English, Spanish)
• Comprehensive audit logging
• Zero external dependencies (shaded)
• Active development and maintenance
• Extensive documentation
• Production-ready and battle-tested

---


---