Improve SigningKeys validation error handling and user experience

[ZzAve]

Background

Following the excellent SigningKeys sealed hierarchy implementation in MR #6, we now have a solid foundation for key management. However, the current error handling could be enhanced to provide better
developer experience and more actionable error messages.

Current State

The current implementation uses generic ConfigValidationException types:

• InvalidPemFormatException
• InvalidRsaKeyException
• KeyMismatchException

While functional, these provide limited context about which key failed and at what stage.

Proposed Improvements

1. Enhanced Exception Hierarchy

Create a more specific exception hierarchy that provides:

• Key Type Context: Which key failed (private, public, or compatibility)
• Validation Stage: Where in the process the failure occurred (PEM parsing, RSA validation, compatibility check)
• Actionable Messages: Specific guidance on how to fix common issues

public sealed class SigningKeyValidationException extends ConfigValidationException {
    private final KeyType keyType;
    private final ValidationStage stage;

    public static final class PrivateKeyValidationException extends SigningKeyValidationException { }
    public static final class PublicKeyValidationException extends SigningKeyValidationException { }
    public static final class KeyMismatchValidationException extends SigningKeyValidationException { }
}

public enum KeyType { PRIVATE, PUBLIC, BOTH }
public enum ValidationStage { PEM_PARSING, RSA_VALIDATION, COMPATIBILITY_CHECK, CRYPTOGRAPHIC_OPERATION }

2. User-Friendly Error Messages

Replace generic messages with specific, actionable guidance:

Current:
Failed to load private key: Invalid key format

Proposed:
Private key validation failed during PEM parsing: PKCS#1 format detected. Please convert to PKCS#8 format using:
openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in private_key.pem -out private_key_pkcs8.pem

3. Common Issue Detection

Add specific detection and guidance for common problems:
- PKCS#1 vs PKCS#8 format confusion
- Encrypted private keys (not supported)
- Truncated PEM content
- Wrong key type (RSA vs EC)
- Mismatched key pairs

4. Programmatic Error Handling

Enable code to react differently to different error types:

try {
    Config config = new Config(server, serviceName, apiKey, privateKeyPem, publicKeyPem);
} catch (PrivateKeyValidationException e) {
    if (e.getStage() == ValidationStage.PEM_PARSING) {
        // Show PEM format help
    }
} catch (KeyMismatchValidationException e) {
    // Suggest regenerating key pair
}

5. Validation Summary

For tools/CLIs, provide comprehensive validation results:

public class ValidationResult {
    private final List<SigningKeyValidationException> errors;

    public static ValidationResult validateSigningKeys(SigningKeys keys) {
        // Validate all aspects and collect all errors
    }
}

Benefits

- Better Developer Experience: Clear, actionable error messages
- Faster Debugging: Specific context about what and where things failed
- Tool Integration: Programmatic access to error details for IDEs/CLIs
- User Guidance: Concrete steps to fix common configuration issues

Implementation Notes

- Keep changes backward compatible
- Consider adding error codes for internationalization
- Add comprehensive test coverage for all error scenarios
- Update documentation with common troubleshooting scenarios