cwhitelist

# CWhitelist - Advanced Whitelist Management for Minecraft <div align="center"> <br> <em>🔒 Intelligent Whitelist System with API Integration for Modern Minecraft Servers</em> </div> <p align="center"> <a href="https://github.com/SkyDreamLG/CWhitelist/releases"><img alt="release" src="https://img.shields.io/github/v/release/SkyDreamLG/CWhitelist?style=for-the-badge&color=4A90E2"></a> <a href="https://github.com/SkyDreamLG/CWhitelist/issues"><img alt="issues" src="https://img.shields.io/github/issues/SkyDreamLG/CWhitelist?style=for-the-badge&color=FF6B6B"></a> <a href="./LICENSE"><img alt="license" src="https://img.shields.io/badge/license-LGPL--3.0-blue?style=for-the-badge"></a> <a href="https://neo-forge.net/"><img alt="NeoForge" src="https://img.shields.io/badge/NeoForge-1.21.x-7B68EE?style=for-the-badge&logo=curseforge"></a> </p> --- ## ✨ Features ### 🔐 Multi-Dimensional Authentication - **Player Name**: Traditional username-based whitelisting - **UUID**: Secure player identification - **IP Address**: IP-based authentication with wildcard support (e.g., `192.168.*.*`) - **Configurable Check Types**: Enable/disable each authentication method independently ### 🌐 API Integration - **Dual-Mode Operation**: API-first with local fallback - **Centralized Management**: Single source of truth across multiple servers - **Real-time Synchronization**: Automatic whitelist updates - **Token-based Authentication**: Secure API communication with permission levels - **Health Monitoring**: Built-in API health checks ### 📊 Intelligent Logging System - **Comprehensive Audit Trail**: Player login attempts with timestamps - **Log Rotation**: Automatic file management with size limits - **Retention Policies**: Configurable log retention periods - **Remote Logging**: Optional API-based event logging ### 🛠️ Advanced Management - **Async Operations**: Non-blocking API calls and file operations - **Smart Caching**: Configurable cache durations to reduce API load - **Error Resilience**: Graceful degradation when API is unavailable - **Hot Reloading**: Configuration changes without server restart ### 🎮 User Experience - **Permission-Based Commands**: Granular command access control - **Real-time Feedback**: Immediate operation confirmation - **Comprehensive Status**: Detailed API and token information - **Fallback Protection**: Seamless local operation during API outages ## 🚀 Quick Start ### Installation 1. Download the latest `cwhitelist-x.x-NeoForge-1.21.x.jar` from (https://github.com/SkyDreamLG/CWhitelist/releases) 2. Place it in your server's `mods` folder 3. Start the server to generate default configuration 4. Restart the server after configuration ### Basic Configuration **For Local-Only Mode:** ```toml # config/cwhitelist-common.toml enableLogging = true logRetentionDays = 7 logCutSizeMB = 10 enableNameCheck = true enableUuidCheck = true enableIpCheck = true enableApi = false # Disable API integration ``` **For API-Enabled Mode:** ```toml enableApi = true baseUrl = "http://your-api-server.com/api" token = "your-secure-api-token-here" useHeaderAuth = true timeoutSeconds = 10 syncOnStartup = true logLoginEvents = true ``` Backend program repository address：(https://github.com/SkyDreamLG/cwhitelist-backend) ## ⚙️ Configuration Guide ### Basic Settings (``) | Parameter | Default | Description | Range | |-----------|---------|-------------|-------| | `enableLogging` | `true` | Enable local file logging | boolean | | `logRetentionDays` | `7` | Days to keep log files | 1-365 | | `logCutSizeMB` | `10` | Maximum log file size (MB) | 1-100 | ### Check Settings (``) | Parameter | Default | Description | |-----------|---------|-------------| | `enableNameCheck` | `true` | Validate by player name | | `enableUuidCheck` | `true` | Validate by player UUID | | `enableIpCheck` | `true` | Validate by IP address | ### API Settings (``) | Parameter | Default | Description | |-----------|---------|-------------| | `enableApi` | `false` | Enable API integration | | `baseUrl` | `http://127.0.0.1:5000/api` | API server base URL | | `token` | `""` | API authentication token | | `useHeaderAuth` | `true` | Use Authorization header (true) or query param (false) | | `timeoutSeconds` | `10` | API request timeout | | `cacheDurationSeconds` | `30` | Local cache duration (0 to disable) | | `syncOnStartup` | `true` | Sync with API on server start | | `logLoginEvents` | `true` | Send login events to API | | `serverId` | `""` | Optional server identifier | | `sendServerId` | `false` | Include server ID in API requests | | `includeExpired` | `false` | Include expired entries when syncing | ## 📋 Command Reference ### 🎮 Player Commands | Command | Description | Permission | |---------|-------------|------------| | No direct player commands | All whitelist management requires admin permissions | - | ### 👑 Admin Commands **Basic Whitelist Ma