feat: Add ExtrasPathValidator for traversal protection

Author: thced

src/main/java/com/retailsvc/http/internal/ExtrasPathValidator.java

@@ -0,0 +1,61 @@
+package com.retailsvc.http.internal;
+
+import com.retailsvc.http.BadRequestException;
+import java.net.URI;
+import java.net.URLDecoder;
+import java.nio.charset.StandardCharsets;
+import java.util.regex.Pattern;
+
+public final class ExtrasPathValidator {
+
+  private static final Pattern ENCODED_BLOCKLIST =
+      Pattern.compile("(?i)%(?:25|2e|2f|5c|00|0[1-9a-f]|1[0-9a-f]|7f)");
+
+  private ExtrasPathValidator() {}
+
+  public static String validateAndDecode(URI uri) {
+    String raw = uri.getRawPath();
+    if (raw == null) {
+      throw new BadRequestException("missing path");
+    }
+    if (ENCODED_BLOCKLIST.matcher(raw).find()) {
+      throw new BadRequestException("path contains disallowed percent-encoded sequence");
+    }
+    if (raw.indexOf('\\') >= 0) {
+      throw new BadRequestException("path contains backslash");
+    }
+    for (int i = 0; i < raw.length(); i++) {
+      char c = raw.charAt(i);
+      if (c < 0x20 || c == 0x7f) {
+        throw new BadRequestException("path contains control character");
+      }
+    }
+
+    String decoded;
+    try {
+      decoded = URLDecoder.decode(raw, StandardCharsets.UTF_8);
+    } catch (IllegalArgumentException e) {
+      throw new BadRequestException("malformed percent-encoding");
+    }
+
+    for (int i = 0; i < decoded.length(); i++) {
+      char c = decoded.charAt(i);
+      if (c < 0x20 || c == 0x7f) {
+        throw new BadRequestException("decoded path contains control character");
+      }
+    }
+
+    String[] segments = decoded.substring(decoded.startsWith("/") ? 1 : 0).split("/", -1);
+    for (int i = 0; i < segments.length; i++) {
+      String s = segments[i];
+      if (s.isEmpty() && i != segments.length - 1) {
+        throw new BadRequestException("empty path segment");
+      }
+      if (".".equals(s) || "..".equals(s)) {
+        throw new BadRequestException("path traversal segment");
+      }
+    }
+
+    return decoded;
+  }
+}

src/test/java/com/retailsvc/http/internal/ExtrasPathValidatorTest.java

@@ -0,0 +1,84 @@
+package com.retailsvc.http.internal;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import com.retailsvc.http.BadRequestException;
+import java.net.URI;
+import org.junit.jupiter.api.Test;
+
+class ExtrasPathValidatorTest {
+
+  @Test
+  void plainPathPasses() {
+    URI uri = URI.create("/files/a/b.txt");
+    assertThat(ExtrasPathValidator.validateAndDecode(uri)).isEqualTo("/files/a/b.txt");
+  }
+
+  @Test
+  void dotDotSegmentRejected() {
+    assertReject("/files/../etc/passwd");
+  }
+
+  @Test
+  void singleDotSegmentRejected() {
+    assertReject("/files/./x");
+  }
+
+  @Test
+  void emptySegmentRejected() {
+    assertReject("/files//x");
+  }
+
+  @Test
+  void encodedDotRejected() {
+    assertReject("/files/%2e%2e/etc/passwd");
+    assertReject("/files/%2E/x");
+  }
+
+  @Test
+  void doubleEncodedDotRejected() {
+    assertReject("/files/%252e%252e/etc/passwd");
+  }
+
+  @Test
+  void encodedSlashRejected() {
+    assertReject("/files/%2fetc/passwd");
+    assertReject("/files/%2Fetc/passwd");
+  }
+
+  @Test
+  void backslashRejected() {
+    assertReject("/files/x%5cy");
+    assertReject("/files/x%5Cy");
+  }
+
+  @Test
+  void literalBackslashRejected() throws Exception {
+    URI uri = new URI("/files/x%5cy");
+    assertThatThrownBy(() -> ExtrasPathValidator.validateAndDecode(uri))
+        .isInstanceOf(BadRequestException.class);
+  }
+
+  @Test
+  void nulByteRejected() {
+    assertReject("/files/x%00.txt");
+  }
+
+  @Test
+  void controlCharRejected() {
+    assertReject("/files/x%0ay");
+  }
+
+  @Test
+  void doubleEncodedPercentRejected() {
+    assertReject("/files/%25xx");
+    assertReject("/files/%2500");
+  }
+
+  private void assertReject(String raw) {
+    URI uri = URI.create(raw);
+    assertThatThrownBy(() -> ExtrasPathValidator.validateAndDecode(uri))
+        .isInstanceOf(BadRequestException.class);
+  }
+}