Add PathFence

[garydgregory]

A Path fence guards against using paths outside of a "fence" of made of root paths.

This was extracted from Apache Commons Text's private PathFence.

Thanks for your contribution to Apache Commons! Your help is appreciated!

Before you push a pull request, review this list:

• Read the contribution guidelines for this project.
• Read the ASF Generative Tooling Guidance if you use Artificial Intelligence (AI).
• I used AI to create any part of, or all of, this pull request: The initial unit test was created and then heavily and manually modified using Co-Pilot.
• Run a successful build using the default Maven goal with mvn; that's mvn on the command line by itself.
• Write unit tests that match behavioral changes, where the tests fail if the changes to the runtime are not applied. This may not always be possible, but it is a best-practice.
• Write a pull request description that is detailed enough to understand what the pull request does, how, and why.
• Each commit in the pull request should have a meaningful subject line and body. Note that a maintainer may squash commits during the merge process.

[garydgregory]

@ppkarwasz
Any thoughts?

[ppkarwasz]

This API needs a clear security model: is it intended for reading existing files, creating new files or both?

The path resolution strategy should change depending on the use case:

1. Reading trusted configuration files
   When reading from trusted system locations (e.g. configuration directories managed by sysadmins), we typically must allow symlinks. Example: On Debian, CATALINA_BASE is /var/lib/tomcat, but /var/lib/tomcat/conf is a symlink to /etc/tomcat, which should be allowed.

2. Reading files from untrusted user input
   For user-supplied paths, following symlinks can enable path traversal attacks. In this case, symlinks should generally not be followed.

At the moment, the class performs only syntactic path validation using path.toAbsolutePath().normalize(). This is sufficient for trusted environments (e.g. system-managed configuration directories), but it does not call Path.toRealPath(), which resolves symlinks. As a result, when used with a root directory that may contain untrusted content, it can be bypassed by symlink-based path traversal attacks.

[ppkarwasz]

Suggested change

	final Path pathAbs = path.normalize().toAbsolutePath();
	final Path pathAbs = path.toAbsolutePath().normalize();

If you call it in the reverse order, normalize() will not remove leading .. segments. For example on UNIX:

• if path equals ../../etc/passwd,
• then path.normalize() equals ../../etc/passwd,
• and path.normalize().toAbsolutePath() equals /home/piotr/../../etc/passwd.