Module de.cuioss.http
Package de.cuioss.http.security.core

Interface HttpSecurityValidator

All Known Implementing Classes:
AbstractValidationPipeline, CharacterValidationStage, DecodingStage, HTTPHeaderValidationPipeline, LengthValidationStage, NormalizationStage, PatternMatchingStage, URLParameterValidationPipeline, URLPathValidationPipeline
Functional Interface:
This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.
@FunctionalInterface public interface HttpSecurityValidator
Core functional interface for HTTP security validation.

This interface defines the contract for validating HTTP components against security threats. It follows the "String in, String out, throws on violation" pattern consistently across all implementations, enabling clean functional programming patterns and easy composition.

Design Principles

  • Functional Interface - Can be used with lambda expressions and method references
  • Fail Secure - Throws UrlSecurityException on any security violation
  • String/throws Pattern - Simple contract: input string, output string, throws on failure
  • Composable - Multiple validators can be chained or combined
  • Thread Safe - Implementations should be thread-safe for concurrent use

Usage Examples

 // Simple validation
 HttpSecurityValidator pathValidator = input -> {
     if (input.contains("../")) {
         throw UrlSecurityException.builder()
             .failureType(UrlSecurityFailureType.PATH_TRAVERSAL_DETECTED)
             .validationType(ValidationType.URL_PATH)
             .originalInput(input)
             .build();
     }
     return input;
 };

 // Using with streams
 List<String> validPaths = paths.stream()
     .map(pathValidator::validate)
     .collect(Collectors.toList());

 // Composing validators
 HttpSecurityValidator compositeValidator = input ->
     secondValidator.validate(firstValidator.validate(input));

Implementation Guidelines

  • Always validate the most dangerous patterns first
  • Provide clear, actionable error messages in exceptions
  • Consider performance - validators may be called frequently
  • Be consistent with null handling (typically reject null inputs)
  • Log security violations appropriately without exposing sensitive data
Implements: Task B3 from HTTP verification specification
Since:
1.0
See Also:

  • Method Details

    • validate

      Optional<String> validate(@Nullable String value) throws UrlSecurityException
      Validates the input string and returns the sanitized/normalized version.

      This method should examine the input for security violations and either:

      • Return the input unchanged if it's safe
      • Return a sanitized/normalized version if safe transformations are possible
      • Return Optional.empty() if the input was null
      • Throw UrlSecurityException if the input represents a security threat

      The decision between sanitization and rejection depends on the specific validator and security requirements. Critical security validators should prefer rejection over sanitization to avoid bypasses.

      Parameters:
      value - The input to validate. May be null.
      Returns:
      The validated, potentially sanitized or normalized value wrapped in Optional. Returns Optional.empty() if the input was null.
      Throws:
      UrlSecurityException - If the input represents a security violation that cannot be safely sanitized. The exception should include detailed context about the failure for logging and debugging purposes.
      IllegalArgumentException - If the input is malformed in a way that prevents security analysis (distinct from security violations).

    • andThen

      default HttpSecurityValidator andThen(HttpSecurityValidator after)
      Creates a composite validator that applies this validator followed by the given validator.

      This is a convenience method for chaining validators. The resulting validator will:

      1. Apply this validator to the input
      2. Apply the after validator to the result
      3. Return the final result

      If either validator throws an exception, the composition stops and the exception is propagated.

      Parameters:
      after - The validator to apply after this validator
      Returns:
      A composite validator that applies both validators in sequence
      Throws:
      NullPointerException - if after is null
      Since:
      1.0

    • compose

      default HttpSecurityValidator compose(HttpSecurityValidator before)
      Creates a composite validator that applies the given validator followed by this validator.

      This is a convenience method for chaining validators. The resulting validator will:

      1. Apply the before validator to the input
      2. Apply this validator to the result
      3. Return the final result
      Parameters:
      before - The validator to apply before this validator
      Returns:
      A composite validator that applies both validators in sequence
      Throws:
      NullPointerException - if before is null
      Since:
      1.0

    • when

      default HttpSecurityValidator when(Predicate<String> predicate)
      Creates a validator that applies this validator only if the given predicate is true. If the predicate is false, the input is returned unchanged.

      This is useful for conditional validation based on input characteristics:

       // Only validate non-empty strings
 HttpSecurityValidator conditionalValidator = validator.when(s -> s != null && !s.isEmpty());

 // Only validate strings that look like URLs
 HttpSecurityValidator urlValidator = validator.when(s -> s.startsWith("http"));
      Parameters:
      predicate - The condition under which to apply this validator
      Returns:
      A conditional validator that only applies this validator when the predicate is true
      Throws:
      NullPointerException - if predicate is null
      Since:
      1.0

    • identity

      static HttpSecurityValidator identity()
      Creates an identity validator that always returns the input unchanged. This is useful as a no-op validator or as a starting point for composition.
      Returns:
      An identity validator that performs no validation
      Since:
      1.0

    • reject

      static HttpSecurityValidator reject(UrlSecurityFailureType failureType, ValidationType validationType)
      Creates a validator that always rejects input with the specified failure type. This is useful for creating validators that unconditionally block certain inputs.
      Parameters:
      failureType - The failure type to use in the exception
      validationType - The validation type context
      Returns:
      A validator that always throws UrlSecurityException
      Throws:
      NullPointerException - if either parameter is null
      Since:
      1.0