Document possibility of Path Traversal attacks in path validators (#900)

Fixes #899

src/main/java/org/kiwiproject/validation/DirectoryPath.java

@@ -15,7 +15,9 @@
 import java.lang.annotation.Target;
 
 /**
- * The annotated element must point to an existing directory.
+ * The annotated element must point to an existing directory. Please read the implementation note regarding
+ * intended usage of this annotation with respect to the potential for
+ * <a href="https://owasp.org/www-community/attacks/Path_Traversal">Path Traversal</a> attacks.
  * <p>
  * By default does not permit null values. If the element being validated allows {@code null} values, you can
  * set {@link #allowNull()} to {@code true}.
@@ -39,6 +41,12 @@
  * {@literal @}DirectoryPath(ensureReadable = true, ensureWritable = true, mkdirs = true)
  *  private String tempDir;
  * </pre>
+ *
+ * @implNote This annotation is not intended to validate user input from client-side applications, because of the
+ * possibility of <a href="https://owasp.org/www-community/attacks/Path_Traversal">Path Traversal</a> attacks. Instead,
+ * the intended usage is to validate application configuration parameters, e.g. an application reads a local
+ * configuration file at startup. Even this is not 100% safe, since the configuration could come from a remote
+ * location such as a configuration service, so users should understand the usage risks and mitigate when possible.
  */
 @Documented
 @Constraint(validatedBy = {DirectoryPathValidator.class})

src/main/java/org/kiwiproject/validation/DirectoryPathValidator.java

@@ -18,6 +18,9 @@
  * <p>
  * As mentioned in the documentation for {@link DirectoryPath}, this may also attempt to create the directory
  * if it does not already exist, which may be an unexpected side-effect.
+ *
+ * @implNote Please read the implementation note in {@link DirectoryPath} regarding the possibility of
+ * <a href="https://owasp.org/www-community/attacks/Path_Traversal">Path Traversal</a> attacks.
  */
 @Slf4j
 public class DirectoryPathValidator implements ConstraintValidator<DirectoryPath, String> {

src/main/java/org/kiwiproject/validation/FilePath.java

@@ -15,7 +15,9 @@
 import java.lang.annotation.Target;
 
 /**
- * The annotated element must point to an existing file.
+ * The annotated element must point to an existing file. Please read the implementation note regarding
+ * intended usage of this annotation with respect to the potential for
+ * <a href="https://owasp.org/www-community/attacks/Path_Traversal">Path Traversal</a> attacks.
  * <p>
  * By default does not permit null values. If the element being validated allows {@code null} values, you can
  * set {@link #allowNull()} to {@code true}.
@@ -29,6 +31,12 @@
  * {@literal @}FilePath(allowNull = true)
  *  public String getLocation() { return this.location; }
  * </pre>
+ *
+ * @implNote This annotation is not intended to validate user input from client-side applications, because of the
+ * possibility of <a href="https://owasp.org/www-community/attacks/Path_Traversal">Path Traversal</a> attacks. Instead,
+ * the intended usage is to validate application configuration parameters, e.g. an application reads a local
+ * configuration file at startup. Even this is not 100% safe, since the configuration could come from a remote
+ * location such as a configuration service, so users should understand the usage risks and mitigate when possible.
  */
 @Documented
 @Constraint(validatedBy = {FilePathValidator.class})

src/main/java/org/kiwiproject/validation/FilePathValidator.java

@@ -11,6 +11,9 @@
 
 /**
  * Validates that a string value is a valid path, exists, and is a regular file (not a directory).
+ *
+ * @implNote Please read the implementation note in {@link FilePath} regarding the possibility of
+ * <a href="https://owasp.org/www-community/attacks/Path_Traversal">Path Traversal</a> attacks.
  */
 @Slf4j
 public class FilePathValidator implements ConstraintValidator<FilePath, String> {