refactor: improve PasswordPolicyService structure and error handling

- Extract password validation logic into separate private methods for better maintainability
- Add checkPasswordHistory() method for cleaner password history validation
- Add checkPasswordSimilarity() method for username/email similarity checks
- Add validateWithPassay() method to encapsulate Passay validation logic
- Add buildPassayRules() and createSpecialCharacterRule() helper methods
- Implement early returns for history and similarity checks to improve performance
- Add Optional return types for null-safe error handling
- Improve error logging with critical severity for missing common passwords file
- Add debug logging for password rejection reasons

These changes improve code readability, testability, and follow single responsibility principle
by breaking down the large validate() method into focused helper methods.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: devondragon

src/main/java/com/digitalsanctuary/spring/user/service/PasswordPolicyService.java

@@ -35,6 +35,7 @@
 import java.util.ArrayList;
 import java.util.List;
 import java.util.Locale;
+import java.util.Optional;
 
 /**
  * The PasswordPolicyService enforces configurable password validation rules
@@ -104,7 +105,12 @@ private void initCommonPasswords() {
                 commonPasswordRule = new DictionaryRule(dictionary);
                 log.info("Common password dictionary initialized successfully.");
             } catch (Exception e) {
-                log.error("Failed to load common passwords file", e);
+                // Log the error as severe since this is a security feature
+                log.error("CRITICAL: Failed to load common passwords file. " +
+                    "Common password checking is DISABLED. This is a security risk!", e);
+                // In production, you may want to fail fast, but for now we'll allow
+                // the application to start with reduced security to avoid breaking tests
+                // Consider using a profile-based approach for stricter production behavior
             }
         }
     }
@@ -125,6 +131,30 @@ public List<String> validate(User user, String password, String usernameOrEmail,
         }
 
         log.debug("Validating password with configured policy.");
+
+        // Check password history first (early return if reused)
+        Optional<String> historyError = checkPasswordHistory(user, password, locale);
+        if (historyError.isPresent()) {
+            return List.of(historyError.get());
+        }
+
+        // Check similarity to username/email (early return if too similar)
+        Optional<String> similarityError = checkPasswordSimilarity(password, usernameOrEmail, locale);
+        if (similarityError.isPresent()) {
+            return List.of(similarityError.get());
+        }
+
+        // Build and apply Passay rules
+        List<Rule> rules = buildPassayRules();
+        return validateWithPassay(password, rules, locale);
+    }
+
+    /**
+     * Build the list of Passay rules based on configuration.
+     *
+     * @return list of Passay rules
+     */
+    private List<Rule> buildPassayRules() {
         List<Rule> rules = new ArrayList<>();
 
         // Length rule
@@ -141,57 +171,107 @@ public List<String> validate(User user, String password, String usernameOrEmail,
             rules.add(new CharacterRule(EnglishCharacterData.Digit, 1));
         }
         if (requireSpecial) {
-            CharacterData specialCharacterData = new CharacterData() {
-                @Override
-                public String getErrorCode() {
-                    return EnglishCharacterData.Special.getErrorCode();
-
-                }
-
-                @Override
-                public String getCharacters() {
-                    return specialChars;
-                }
-            };
-            rules.add(new CharacterRule(specialCharacterData, 1));
+            rules.add(createSpecialCharacterRule());
         }
 
         // Common Passwords Dictionary Rule
         if (preventCommonPasswords && commonPasswordRule != null) {
             rules.add(commonPasswordRule);
         }
 
-        // Password History Check
-        if (user != null && historyCount > 0) {
-            List<String> oldHashes = passwordHistoryRepository.findRecentPasswordHashes(user,
-                    PageRequest.of(0, historyCount));
-            for (String hash : oldHashes) {
-                if (passwordEncoder.matches(password, hash)) {
-                    String msg = messages.getMessage("password.error.history.reuse", new Object[] { historyCount },
-                            locale);
-                    return List.of(msg);
-                }
+        return rules;
+    }
+
+    /**
+     * Create a special character rule with configured allowed characters.
+     *
+     * @return CharacterRule for special characters
+     */
+    private CharacterRule createSpecialCharacterRule() {
+        CharacterData specialCharacterData = new CharacterData() {
+            @Override
+            public String getErrorCode() {
+                return EnglishCharacterData.Special.getErrorCode();
+            }
+
+            @Override
+            public String getCharacters() {
+                return specialChars;
             }
+        };
+        return new CharacterRule(specialCharacterData, 1);
+    }
+
+    /**
+     * Check if the password has been used before by this user.
+     *
+     * @param user     the user
+     * @param password the password to check
+     * @param locale   the locale for error messages
+     * @return Optional containing error message if password was reused, empty otherwise
+     */
+    private Optional<String> checkPasswordHistory(User user, String password, Locale locale) {
+        if (user == null || historyCount <= 0) {
+            return Optional.empty();
         }
 
-        // Similarity Check
-        if (StringUtils.hasText(usernameOrEmail) && similarityThreshold > 0) {
-            int distance = LevenshteinDistance.getDefaultInstance().apply(password.toLowerCase(),
-                    usernameOrEmail.toLowerCase());
-            int maxLength = Math.max(password.length(), usernameOrEmail.length());
-
-            if (maxLength > 0) {
-                double similarityPercent = (100.0 * (maxLength - distance)) / maxLength;
-                log.debug("Password similarity to username/email: {}%", similarityPercent);
-
-                if (similarityPercent >= similarityThreshold) {
-                    String msg = messages.getMessage("password.error.similarity",
-                            new Object[] { String.format("%.2f", similarityPercent) }, locale);
-                    return List.of(msg);
-                }
+        List<String> oldHashes = passwordHistoryRepository.findRecentPasswordHashes(user,
+                PageRequest.of(0, historyCount));
+
+        for (String hash : oldHashes) {
+            if (passwordEncoder.matches(password, hash)) {
+                String msg = messages.getMessage("password.error.history.reuse",
+                        new Object[] { historyCount }, locale);
+                log.debug("Password rejected: matches historical password");
+                return Optional.of(msg);
             }
         }
 
+        return Optional.empty();
+    }
+
+    /**
+     * Check if the password is too similar to the username or email.
+     *
+     * @param password        the password to check
+     * @param usernameOrEmail the username or email to compare against
+     * @param locale          the locale for error messages
+     * @return Optional containing error message if too similar, empty otherwise
+     */
+    private Optional<String> checkPasswordSimilarity(String password, String usernameOrEmail, Locale locale) {
+        if (!StringUtils.hasText(usernameOrEmail) || similarityThreshold <= 0) {
+            return Optional.empty();
+        }
+
+        int distance = LevenshteinDistance.getDefaultInstance().apply(
+                password.toLowerCase(), usernameOrEmail.toLowerCase());
+        int maxLength = Math.max(password.length(), usernameOrEmail.length());
+
+        if (maxLength == 0) {
+            return Optional.empty();
+        }
+
+        double similarityPercent = (100.0 * (maxLength - distance)) / maxLength;
+        log.debug("Password similarity to username/email: {}%", similarityPercent);
+
+        if (similarityPercent >= similarityThreshold) {
+            String msg = messages.getMessage("password.error.similarity",
+                    new Object[] { String.format("%.2f", similarityPercent) }, locale);
+            return Optional.of(msg);
+        }
+
+        return Optional.empty();
+    }
+
+    /**
+     * Validate password using Passay rules.
+     *
+     * @param password the password to validate
+     * @param rules    the Passay rules to apply
+     * @param locale   the locale for error messages
+     * @return list of error messages if validation fails, empty if valid
+     */
+    private List<String> validateWithPassay(String password, List<Rule> rules, Locale locale) {
         PasswordValidator validator = new PasswordValidator(
                 (detail) -> messages.getMessage(detail.getErrorCode(), detail.getValues(), locale),
                 rules);