CWhitelist - Advanced Whitelist Management for Minecraft

🔒 Intelligent Whitelist System with API Integration for Modern Minecraft Servers

English | 中文

✨ 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

Download the latest cwhitelist-x.x-NeoForge-1.21.x.jar from Releases
Place it in your server's mods folder
Start the server to generate default configuration
Restart the server after configuration

Basic Configuration

For Local-Only Mode:

# config/cwhitelist-common.toml
[basic]
enableLogging = true
logRetentionDays = 7
logCutSizeMB = 10

[checks]
enableNameCheck = true
enableUuidCheck = true
enableIpCheck = true

[api]
enableApi = false  # Disable API integration

For API-Enabled Mode:

[api]
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：cwhitelist-backend

⚙️ Configuration Guide

Basic Settings (`[basic]`)

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 (`[checks]`)

Parameter	Default	Description
`enableNameCheck`	`true`	Validate by player name
`enableUuidCheck`	`true`	Validate by player UUID
`enableIpCheck`	`true`	Validate by IP address

API Settings (`[api]`)

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 Management:

# Add entries
/cwhitelist add name <username>
/cwhitelist add uuid <uuid>
/cwhitelist add ip <ip-address>

# Remove entries
/cwhitelist remove name <username>
/cwhitelist remove uuid <uuid>
/cwhitelist remove ip <ip-address>

# View entries
/cwhitelist list

# Reload configuration
/cwhitelist reload

API Management Commands:

# Check API status
/cwhitelist api status

# Verify API token
/cwhitelist api verify

# Perform health check
/cwhitelist api health

# Manual sync from API
/cwhitelist api sync

# Clear API cache
/cwhitelist api clearcache

🔌 API Integration

API Requirements

CWhitelist supports integration with compatible API servers that implement the following endpoints:

GET /health - Health check (no authentication required)
GET /whitelist/sync - Retrieve whitelist entries (requires read permission)
POST /whitelist/entries - Add new entries (requires write permission)
DELETE /whitelist/entries/{type}/{value} - Remove entries (requires delete permission)
POST /login/log - Log login events (requires write permission)
GET /tokens/verify - Verify token validity (requires authentication)

Token Permissions

API tokens must be created with appropriate permissions:

Read: Required for syncing whitelist
Write: Required for adding entries and logging events
Delete: Required for removing entries
Manage: System administration (not typically needed)

Authentication Methods

Header Authentication (Recommended):

Authorization: Bearer your-token-here

Query Parameter Authentication:

GET /api/whitelist/sync?token=your-token-here

🗂️ File Structure

config/
├── cwhitelist-common.toml          # Main configuration
└── cwhitelist_entries.json         # Local whitelist backup

logs/
└── cwhitelist/
    ├── 2024-01-01.log              # Daily log files
    └── 2024-01-01.log.1704067200000 # Rotated logs

Data Files Format

cwhitelist_entries.json:

[
  {"type": "name", "value": "PlayerOne"},
  {"type": "uuid", "value": "123e4567-e89b-12d3-a456-426614174000"},
  {"type": "ip", "value": "192.168.1.*"}
]

🔄 Operation Modes

Mode 1: Local-Only (Default)

All data stored locally
No external dependencies
Simple deployment
Suitable for single servers

Mode 2: API-Primary with Fallback

Primary: Sync with central API
Fallback: Use local cache if API unavailable
Automatic re-sync when API restored
Ideal for multi-server setups

Mode 3: API-Only

All operations through API
No local whitelist storage
Centralized management
Requires reliable API connection

🛡️ Security Features

Authentication Security

Token-based Authentication: Secure API communication
Permission Validation: Granular access control
Token Expiry: Automatic token validity checks
No Hardcoded Secrets: Config file-based token management

Data Protection

Local Encryption: Sensitive data in configuration
Access Control: Admin-only command permissions (level 4)
Audit Logging: Comprehensive access logging
Input Validation: Sanitized API request parameters

Network Security

HTTPS Support: Secure API communication (when configured)
Timeout Protection: Configurable request timeouts
Retry Logic: Graceful error handling
Rate Limiting: Built-in request queuing

📈 Performance Optimization

Caching Strategy

// Configurable cache duration
cacheDurationSeconds = 30  // Balance between freshness and API load

// Smart cache invalidation
- Add/Remove operations clear cache
- Manual sync refreshes cache
- Automatic periodic validation

Async Operations

Non-blocking API Calls: HTTP requests on separate threads
Parallel Processing: Concurrent request handling
Queue Management: Ordered request processing
Resource Optimization: Efficient memory usage

🐛 Troubleshooting

Common Issues

API Connection Failed:

[Server] WARN API health check failed, falling back to local file

Solution: Verify API server is running and accessible. Check network connectivity and firewall settings.

Authentication Failed:

[Server] ERROR Token verification failed: Authentication required

Solution: Verify API token is correct and has required permissions. Use /cwhitelist api verify to test.

Permission Denied:

[Server] ERROR Token does not have write permission

Solution: Generate new token with appropriate permissions or use existing token with correct permissions.

Cache Issues:

[Server] DEBUG API cache cleared

Solution: Cache automatically clears on modification. Use /cwhitelist api clearcache to force refresh.

Log Files

Check log files for detailed error information:

Location: logs/cwhitelist/YYYY-MM-DD.log
Contains: API calls, authentication attempts, errors
Format: [HH:mm:ss] [RESULT] PlayerName UUID IP

Debug Commands

# Check current mode
/cwhitelist list

# Verify API connectivity
/cwhitelist api health

# Test token permissions
/cwhitelist api verify

# View detailed status
/cwhitelist api status

🧩 API Compatibility

Supported API Versions

Minimum: v1.0.0
Recommended: v1.1.0+
Tested With: CWhitelist API v1.2.0

Response Format Expectations

{
  "success": true,
  "message": "Operation successful",
  "data": { /* operation-specific data */ }
}

Error Handling

The mod handles the following HTTP status codes:

200-299: Success - Process response
401: Unauthorized - Token invalid/expired
403: Forbidden - Insufficient permissions
429: Rate Limited - Automatic retry with backoff
500+: Server Error - Fallback to local mode

🔧 Development

Building from Source

# Clone repository
git clone https://github.com/SkyDreamLG/CWhitelist.git
cd CWhitelist

# Build with Gradle
./gradlew build

# Output: build/libs/cwhitelist-x.x.x.jar

Prerequisites

Java: 17 or higher
Minecraft: 1.21.x
NeoForge: Latest recommended build
Build Tools: Gradle 8.0+

Project Structure

src/main/java/org/skydream/cwhitelist/
├── Cwhitelist.java              # Main mod class
├── Config.java                  # Configuration management
├── ApiClient.java               # API communication
├── WhitelistManager.java        # Core whitelist logic
├── WhitelistCommand.java        # Command implementation
├── LogHandler.java              # Logging system
└── WhitelistEntry.java          # Data model

Extending the Mod

Adding New Authentication Methods:

Update Config.java with new check setting
Modify WhitelistManager.isAllowed() method
Add corresponding command handlers
Update API client for new endpoint support

Custom API Integration:

// Implement custom ApiClient interface
public interface CustomApiClient {
    CompletableFuture<List<WhitelistEntry>> fetchEntries();
    CompletableFuture<Boolean> validateEntry(WhitelistEntry entry);
}

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Workflow

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit changes (git commit -m 'Add amazing feature')
Push to branch (git push origin feature/amazing-feature)
Open a Pull Request

Coding Standards

Follow existing code style and patterns
Add comprehensive JavaDoc comments
Include unit tests for new features
Update documentation for API changes
Ensure backward compatibility

Third-Party Licenses

Gson: Apache License 2.0
NeoForge: LGPL 2.1
SLF4J: MIT License

🌟 Acknowledgments

NeoForge Team for the excellent modding framework
Mojang Studios for Minecraft
Contributors who help improve this project
Community for feedback and support

📞 Support

Documentation: GitHub Wiki
Issues: GitHub Issues
Discussions: GitHub Discussions
Email: 1607002411@qq.com

_{Built with ❤️ by SkyDream Team}
_{If you find this project useful, please consider giving it a ⭐ on GitHub!}

🎯 Quick Reference

Deployment Checklist

Verify Java 17+ installation
Configure API token (if using API mode)
Set appropriate permission levels
Test API connectivity
Configure logging preferences
Set up log rotation schedule
Test local fallback functionality

Performance Tips

Cache Duration: Set cacheDurationSeconds based on update frequency
Log Rotation: Configure logCutSizeMB to prevent disk space issues
Timeout Settings: Adjust timeoutSeconds based on network latency
API Calls: Minimize API calls during peak hours

Security Best Practices

Token Security: Store tokens in configuration, not in code
Permission Minimization: Grant minimum required permissions
Regular Audits: Review log files for suspicious activity
API Security: Use HTTPS for API communication
Backup Strategy: Regular backups of local whitelist files

Ready to secure your Minecraft server? Install CWhitelist today and experience professional-grade whitelist management!

Name		Name	Last commit message	Last commit date
Latest commit History 30 Commits
gradle/wrapper		gradle/wrapper
src/main		src/main
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
README_CN.md		README_CN.md
build.gradle		build.gradle
gradle.properties		gradle.properties
gradlew		gradlew
gradlew.bat		gradlew.bat
settings.gradle		settings.gradle

Folders and files

Latest commit

History

Repository files navigation

CWhitelist - Advanced Whitelist Management for Minecraft

✨ Features

🔐 Multi-Dimensional Authentication

🌐 API Integration

📊 Intelligent Logging System

🛠️ Advanced Management

🎮 User Experience

🚀 Quick Start

Installation

Basic Configuration

⚙️ Configuration Guide

Basic Settings ([basic])

Check Settings ([checks])

API Settings ([api])

📋 Command Reference

🎮 Player Commands

👑 Admin Commands

🔌 API Integration

API Requirements

Token Permissions

Authentication Methods

🗂️ File Structure

Data Files Format

🔄 Operation Modes

Mode 1: Local-Only (Default)

Mode 2: API-Primary with Fallback

Mode 3: API-Only

🛡️ Security Features

Authentication Security

Data Protection

Network Security

📈 Performance Optimization

Caching Strategy

Async Operations

🐛 Troubleshooting

Common Issues

Log Files

Debug Commands

🧩 API Compatibility

Supported API Versions

Response Format Expectations

Error Handling

🔧 Development

Building from Source

Prerequisites

Project Structure

Extending the Mod

🤝 Contributing

Development Workflow

Coding Standards

Third-Party Licenses

🌟 Acknowledgments

📞 Support

🎯 Quick Reference

Deployment Checklist

Performance Tips

Security Best Practices

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 6

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Basic Settings (`[basic]`)

Check Settings (`[checks]`)

API Settings (`[api]`)

Packages