Add low-priority enhancements and polish

This commit implements 5 low-priority improvements to enhance
documentation, activation handling, and overall plugin polish:

1. Improve GitHub update checker caching strategy
   - Increased cache duration from 6 to 12 hours (configurable constant)
   - Added debug logging for cache operations
   - Better error handling with structured logging
   - Improved handling of API failures and edge cases

2. Add activation/deactivation logic improvements
   - PHP version requirement check (7.2+) on activation
   - WordPress version requirement check (5.0+) on activation
   - Prevent settings overwrite on re-activation
   - Track activation timestamp and version
   - Clear options cache on deactivation
   - Comprehensive logging of activation/deactivation events

3. Complete internationalization (i18n)
   - Wrapped all wp_die() error messages in translation functions
   - Added text domain to all user-facing strings
   - Improved consistency across OIDC and SAML error messages
   - Plugin now fully translatable via .po/.mo files

4. Add CHANGELOG.md file
   - Comprehensive changelog following Keep a Changelog format
   - Documents all versions from 1.0.0 to current
   - Includes security notices and upgrade notes
   - Categorized changes (Added, Changed, Fixed, Security)

5. Enhance inline documentation
   - Added detailed PHPDoc blocks with @SInCE tags
   - Included usage examples in docblocks
   - Better parameter and return value documentation
   - Enhanced class-level documentation
   - Improved method descriptions with context

These changes improve the overall polish and maintainability of the
plugin without affecting functionality.

Author: cjscrofani

CHANGELOG.md

@@ -0,0 +1,109 @@
+# Changelog
+
+All notable changes to the Cloudflare Zero Trust Login for WordPress plugin will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Centralized logging system with CFZT_Logger class
+- User helper class for consolidated user management
+- Type hints for improved code quality and IDE support
+- Class constants for magic strings (auth methods, app types, etc.)
+- Options caching to reduce database queries
+- PHP and WordPress version checking on activation
+- Activation timestamp tracking
+- Improved GitHub update checker with configurable cache duration
+
+### Changed
+- Improved code organization by extracting duplicate user creation logic
+- Enhanced activation/deactivation hooks with proper cleanup
+- Increased GitHub update cache from 6 to 12 hours
+- Better error handling with structured logging context
+
+### Fixed
+- Version mismatch between plugin header and constant
+- Encryption nonce now uses truly random values instead of wp_create_nonce()
+- All $_SERVER superglobal access now properly sanitized
+- Internationalization completed for all user-facing error messages
+
+### Security
+- **CRITICAL**: Documented SAML signature validation limitation (NOT production-ready)
+- Added security warnings to SAML implementation
+- Improved sanitization across all components
+
+## [1.0.2] - 2025-10-23
+
+### Changed
+- Manual update feature improvements
+- Updated .gitignore
+
+## [1.0.1] - 2025-10-20
+
+### Changed
+- Initial public release refinements
+
+## [1.0.0] - 2025-10-15
+
+### Added
+- Initial release
+- OIDC (OpenID Connect) authentication with Cloudflare Zero Trust
+- Experimental SAML authentication support
+- Support for both SaaS and Self-hosted Cloudflare applications
+- Dual login modes (Primary and Secondary)
+- Automatic user creation with configurable roles
+- AES-256-CBC encryption for credentials (with fallback)
+- Rate limiting (10 attempts per 5 minutes)
+- Session protection with fingerprinting
+- Security headers on login pages
+- GitHub-based auto-update system
+- Environment variable support for credentials
+- Comprehensive admin settings interface
+- Authentication logging capability
+- SAML endpoints (ACS, SLS, metadata)
+- Login page UI modifications
+
+### Security
+- Client secret encryption using WordPress salts
+- Rate limiting to prevent brute force attacks
+- Session ID regeneration after login
+- Security headers (CSP, X-Frame-Options, etc.)
+- Nonce verification for state parameters
+- CSRF protection
+
+---
+
+## Version History Summary
+
+- **1.0.2**: Current release with manual update improvements
+- **1.0.1**: Initial public release refinements
+- **1.0.0**: Initial release with OIDC and experimental SAML support
+
+---
+
+## Upgrade Notes
+
+### Upgrading to Future Versions
+
+When upgrading, the plugin will:
+- Preserve your existing settings
+- Automatically flush rewrite rules
+- Clear cached transients
+- Not delete any user data or metadata
+
+### Important Notes
+
+- **SAML Support**: SAML authentication does not perform cryptographic signature validation and should NOT be used in production. Use OIDC for production deployments.
+- **PHP Requirements**: Requires PHP 7.2+ and WordPress 5.0+
+- **OpenSSL Recommended**: For proper credential encryption
+
+---
+
+## Links
+
+- [GitHub Repository](https://github.com/cjscrofani/cloudflare-zero-trust-wordpress)
+- [Issue Tracker](https://github.com/cjscrofani/cloudflare-zero-trust-wordpress/issues)
+- [Cloudflare Zero Trust Documentation](https://developers.cloudflare.com/cloudflare-one/)
+

class-cfzt-saml.php

@@ -175,12 +175,16 @@ private function create_authn_request() {
     private function handle_acs() {
         // Rate limiting
         if (!$this->security->check_rate_limit()) {
-            wp_die('Too many authentication attempts. Please try again in 5 minutes.', 'Rate Limit Exceeded', array('response' => 429));
+            wp_die(
+                __('Too many authentication attempts. Please try again in 5 minutes.', 'cf-zero-trust'),
+                __('Rate Limit Exceeded', 'cf-zero-trust'),
+                array('response' => 429)
+            );
         }
-        
+
         if (!isset($_POST['SAMLResponse'])) {
             $this->log_authentication('unknown', false, 'No SAML response received');
-            wp_die('No SAML response received.');
+            wp_die(__('No SAML response received.', 'cf-zero-trust'));
         }
 
         $saml_response = base64_decode($_POST['SAMLResponse']);
@@ -191,7 +195,7 @@ private function handle_acs() {
 
         if (!$user_data) {
             $this->log_authentication('unknown', false, 'Invalid SAML response');
-            wp_die('Invalid SAML response. Please check your Cloudflare Zero Trust configuration.');
+            wp_die(__('Invalid SAML response. Please check your Cloudflare Zero Trust configuration.', 'cf-zero-trust'));
         }
 
         // Authenticate user
@@ -385,7 +389,7 @@ private function authenticate_user($user_data, $redirect_to = '') {
         $email = $user_data['email'];
         if (empty($email)) {
             $this->log_authentication('unknown', false, 'No email in SAML assertion');
-            wp_die('No email address provided in SAML assertion.');
+            wp_die(__('No email address provided in SAML assertion.', 'cf-zero-trust'));
         }
 
         // Check if user exists
@@ -421,7 +425,7 @@ private function authenticate_user($user_data, $redirect_to = '') {
             exit;
         } else {
             $this->log_authentication($email, false, 'User creation disabled or failed');
-            wp_die('User authentication failed. Auto-creation may be disabled or you may not have permission to access this site.');
+            wp_die(__('User authentication failed. Auto-creation may be disabled or you may not have permission to access this site.', 'cf-zero-trust'));
         }
     }
 

includes/class-cfzt-auth.php

@@ -129,31 +129,35 @@ public function handle_callback() {
 
         // Rate limiting
         if (!$this->security->check_rate_limit()) {
-            wp_die('Too many authentication attempts. Please try again in 5 minutes.', 'Rate Limit Exceeded', array('response' => 429));
+            wp_die(
+                __('Too many authentication attempts. Please try again in 5 minutes.', 'cf-zero-trust'),
+                __('Rate Limit Exceeded', 'cf-zero-trust'),
+                array('response' => 429)
+            );
         }
-        
+
         // Verify state
         $state = sanitize_text_field($_GET['state']);
         if (!get_transient('cfzt_auth_state_' . $state)) {
             $this->log_authentication('unknown', false, 'Invalid state parameter');
-            wp_die('Invalid state parameter');
+            wp_die(__('Invalid state parameter', 'cf-zero-trust'));
         }
         delete_transient('cfzt_auth_state_' . $state);
-        
+
         // Exchange code for token
         $token_data = $this->exchange_code_for_token(sanitize_text_field($_GET['code']));
-        
+
         if (!$token_data || !isset($token_data['access_token'])) {
             $this->log_authentication('unknown', false, 'Token exchange failed');
-            wp_die('Failed to exchange authorization code. Please check your Cloudflare Zero Trust configuration.');
+            wp_die(__('Failed to exchange authorization code. Please check your Cloudflare Zero Trust configuration.', 'cf-zero-trust'));
         }
-        
+
         // Get user info
         $user_info = $this->get_user_info($token_data['access_token']);
-        
+
         if (!$user_info) {
             $this->log_authentication('unknown', false, 'Failed to retrieve user info');
-            wp_die('Failed to retrieve user information. Check your error logs for details.');
+            wp_die(__('Failed to retrieve user information. Check your error logs for details.', 'cf-zero-trust'));
         }
 
         // Authenticate user
@@ -279,7 +283,7 @@ private function authenticate_user($user_info) {
 
         if (empty($email)) {
             $this->log_authentication('unknown', false, 'No email provided');
-            wp_die('No email address provided by Cloudflare Zero Trust.');
+            wp_die(__('No email address provided by Cloudflare Zero Trust.', 'cf-zero-trust'));
         }
 
         // Check if user exists
@@ -312,7 +316,7 @@ private function authenticate_user($user_info) {
             exit;
         } else {
             $this->log_authentication($email, false, 'User creation disabled or failed');
-            wp_die('User authentication failed. Auto-creation may be disabled or you may not have permission to access this site.');
+            wp_die(__('User authentication failed. Auto-creation may be disabled or you may not have permission to access this site.', 'cf-zero-trust'));
         }
     }