CWhitelist Changelog

v2.1 - 2026-01-17

🔧 New Features

API Token Authentication System

• Complete Token Authentication Support: Added secure token authentication mechanism for API servers
• Dual Authentication Methods:
  • Header Authentication: Authenticate via Authorization: Bearer <token> header (Recommended)
  • Query Parameter Authentication: Authenticate via ?token=<token> query parameter
• Permission Validation: Automatically verify token read/write/delete/management permissions
• Token Expiration Detection: Real-time token validity checks with automatic handling of expired tokens

Enhanced Permission Management

• Granular Permission Control:
  • can_read: Read permission for synchronizing whitelist
  • can_write: Write permission for adding entries and logging events
  • can_delete: Delete permission for removing entries
  • can_manage: Management permission for system administration
• Smart Permission Verification: Automatically validates required permissions based on operation type
• Clear Permission Feedback: Detailed permission error messages

Token Status Management

• Token Verification Command: Added /cwhitelist api verify command to validate token effectiveness
• Status Information Display: Detailed token information shown in /cwhitelist api status
• Automatic Verification: Tokens are automatically verified on server startup

⚙️ Configuration Updates

New Configuration Options

[api]
# Basic Authentication Configuration
token = "your-api-token-here"                      # API authentication token
useHeaderAuth = true                              # Authentication method (true:header/false:query parameter)

# Optional Configuration
serverId = ""                                     # Server identifier (optional)
sendServerId = false                              # Whether to include server ID in requests
includeExpired = false                            # Whether to include expired entries

Configuration Change Notes

• Backward Compatible: Existing configurations require no changes, new options have reasonable defaults
• Security Recommendation: Strongly recommend using Header authentication for better security

🎮 Command Extensions

New API Management Commands

Command	Description	Permission
/cwhitelist api verify	Verify API token validity	OP (2)
/cwhitelist api status	Display detailed API and token status	OP (2)

Enhanced Commands

• /cwhitelist api health: Added network error handling and timeout control
• /cwhitelist api sync: Enhanced permission validation, only tokens with read permission allowed
• All API-related operations: Now require valid token authentication

🔒 Security Improvements

Authentication Security

• Secure Token Storage: Tokens stored only in configuration files, not hardcoded
• Secure Communication: Two authentication methods to meet different security needs
• Permission Isolation: Operation scope limited based on token permissions

Error Handling

• Authentication Failure Handling: Automatic fallback to local mode ensuring service availability
• Clear Error Messages: Detailed permission and authentication failure notifications
• Logging: Records all authentication attempts and permission checks

📊 Performance Optimizations

Smart Caching

• Token Verification Cache: Reduces duplicate token validation requests
• Permission Caching: Caches token permission information for faster verification
• Intelligent Refresh: Automatically re-validates tokens upon expiration

Network Optimization

• Connection Reuse: HTTP client connection reuse reduces connection establishment overhead
• Timeout Control: Configurable timeout settings prevent long blocks
• Queue Management: Optimized request queues to avoid concurrency issues

📋 Change Summary

Core Changes

1. API Client Refactor: Rewrote ApiClient class to support token authentication
2. Token Information Model: Added TokenInfo class to manage token data and permissions
3. Authentication Header Management: Simplified to single token configuration, replacing complex header lists

Configuration Simplification

• Removed: API_AUTH_HEADERS configuration option
• Added: API_TOKEN single token configuration
• Optimized: More intuitive authentication method selection

User Experience

• Status Display: More detailed token and permission information
• Error Notifications: More user-friendly permission denial messages
• Operation Feedback: Real-time authentication status feedback

🐛 Known Issues

• None - This version is a feature enhancement release with no bug fixes

---

Update Recommendation: Strongly recommended for all server administrators requiring API integration, providing a more secure and flexible authentication mechanism.

Technical Support: For upgrade issues, please refer to documentation or seek assistance through GitHub Issues.