GROOVY-12271: Confine snippet file resolution to the snippet-files directory

{@snippet file="..."} took the file name verbatim from a doc comment and
joined it onto the package's snippet-files/ directory with no normalization
or containment check, so ../ segments escaped to anywhere the user running
groovydoc could read. JEP 413 confines javadoc's snippet resolution to
--snippet-path; the port added in GROOVY-11938 omitted the check.

This matters because it grants the author of documented source a capability
at doc time rather than at run time: a doc comment in a pull request can
read a file from the machine building the docs and publish its contents in
the rendered page.

Treat the file attribute as relative to snippet-files/, as JEP 413 does,
and confine resolution to that directory:

  - an absolute name is refused outright, rather than accepted when it
    happens to land inside the directory, so that a doc comment cannot
    resolve on its author's machine and fail on a build agent;
  - a relative name is normalized and required to stay inside;
  - containment is re-checked after following symbolic links, so a link
    within the directory cannot point out of it;
  - an unusable name renders nothing instead of throwing.

Covered by two tests: one placing a file outside snippet-files/ and
referencing it relatively and absolutely, asserting its contents never
reach the rendered page; one referencing a file that genuinely is inside,
by both an absolute and a relative name, asserting only the relative form
resolves. Removing either guard fails the corresponding test.

Author: paulk-asert

subprojects/groovy-groovydoc/src/main/java/org/codehaus/groovy/tools/groovydoc/TagRenderer.java

@@ -28,6 +28,7 @@
 
 import java.io.IOException;
 import java.nio.file.Files;
+import java.nio.file.InvalidPathException;
 import java.nio.file.Path;
 import java.nio.file.Paths;
 
@@ -477,6 +478,12 @@ private static int renderSnippetAt(String text, int start, int nameEnd, StringBu
      * GROOVY-11938 stage 2: look up a snippet file in the current package's
      * {@code snippet-files/} directory under any configured sourcepath and
      * return its contents, or {@code null} if not found.
+     * <p>
+     * The file name comes from a doc comment, so it is treated as relative to the package's
+     * {@code snippet-files/} directory and resolution is confined to it. An absolute name is
+     * refused, and a relative one which would escape the directory, whether by {@code ..}
+     * segments or by way of a symbolic link, resolves to nothing rather than to a file
+     * elsewhere on the machine running the tool.
      */
     private static String loadSnippetFile(String fileName, GroovyRootDoc rootDoc, SimpleGroovyClassDoc classDoc, boolean keepHeader) {
         if (classDoc == null || !(rootDoc instanceof SimpleGroovyRootDoc)) return null;
@@ -488,8 +495,8 @@ private static String loadSnippetFile(String fileName, GroovyRootDoc rootDoc, Si
         int lastSlash = full.lastIndexOf('/');
         String pkgPath = lastSlash >= 0 ? full.substring(0, lastSlash) : "";
         for (String sourcepath : sourcepaths) {
-            Path path = Paths.get(sourcepath, pkgPath, "snippet-files", fileName);
-            if (Files.isRegularFile(path)) {
+            Path path = resolveWithinSnippetFiles(sourcepath, pkgPath, fileName);
+            if (path != null) {
                 try {
                     String text = Files.readString(path);
                     return keepHeader ? text : stripLicenseHeader(text);
@@ -501,6 +508,42 @@ private static String loadSnippetFile(String fileName, GroovyRootDoc rootDoc, Si
         return null;
     }
 
+    /**
+     * Resolves a doc-comment-supplied file name against one sourcepath's {@code snippet-files/}
+     * directory, returning the file only when it is a regular file genuinely inside that
+     * directory.
+     *
+     * @param sourcepath the sourcepath to resolve under
+     * @param pkgPath the package path of the class being documented
+     * @param fileName the file name taken from the doc comment
+     * @return the contained file, or {@code null} if there is no such file within the directory
+     */
+    private static Path resolveWithinSnippetFiles(String sourcepath, String pkgPath, String fileName) {
+        Path base;
+        Path candidate;
+        try {
+            Path name = Paths.get(fileName);
+            // JEP 413 treats the file attribute as relative to the snippet path. Rejecting an
+            // absolute name outright keeps that, and keeps a doc comment from depending on
+            // where the project happens to sit on disk: an absolute path that resolved on the
+            // author's machine would not resolve on a build agent.
+            if (name.isAbsolute()) return null;
+            base = Paths.get(sourcepath, pkgPath, "snippet-files").toAbsolutePath().normalize();
+            candidate = base.resolve(name).toAbsolutePath().normalize();
+        } catch (InvalidPathException e) {
+            return null;
+        }
+        if (!candidate.startsWith(base) || !Files.isRegularFile(candidate)) return null;
+        // Containment above is textual; re-check it after following any symbolic links so a
+        // link inside snippet-files cannot point out of it.
+        try {
+            if (!candidate.toRealPath().startsWith(base.toRealPath())) return null;
+        } catch (IOException e) {
+            return null;
+        }
+        return candidate;
+    }
+
     /**
      * If the file begins with a C-style block comment that looks like a
      * license or copyright notice, strip that comment and any whitespace

subprojects/groovy-groovydoc/src/test/groovy/org/codehaus/groovy/tools/groovydoc/GroovyDocToolTest.java

@@ -310,6 +310,65 @@ public void testSnippetMarkupRegexCannotHangTheBuild() throws Exception {
                 elapsedMs < 30_000L);
     }
 
+    // GROOVY-12271: the file attribute is relative to snippet-files/ per JEP 413, so an
+    // absolute name is refused even when it would land inside the directory. Otherwise a doc
+    // comment would resolve on the author's machine and not on a build agent.
+    public void testSnippetTagExternalFormRefusesAbsoluteFileName() throws Exception {
+        String pkg = "org/codehaus/groovy/tools/groovydoc/testfiles/docfiles";
+        Path tmp = Files.createTempDirectory("snippet-absolute-");
+        Path pkgDir = tmp.resolve(pkg);
+        Path snippetDir = pkgDir.resolve("snippet-files");
+        Files.createDirectories(snippetDir);
+        String marker = "INSIDE_SNIPPET_FILES_MARKER";
+        Files.writeString(snippetDir.resolve("Inside.groovy"), marker + "\n");
+
+        Files.writeString(pkgDir.resolve("AbsoluteName.groovy"),
+                "package " + pkg.replace('/', '.') + "\n" +
+                "/**\n" +
+                " * absolute: {@snippet file=\"" + snippetDir.resolve("Inside.groovy") + "\" keepHeader=true}\n" +
+                " * relative: {@snippet file=\"Inside.groovy\" keepHeader=true}\n" +
+                " */\n" +
+                "class AbsoluteName {}\n");
+
+        String doc = renderSingle(tmp, pkg, "AbsoluteName");
+        assertNotNull(doc);
+        // The relative form resolves, so exactly one of the two snippets rendered.
+        int first = doc.indexOf(marker);
+        assertTrue("Expected the relative form to resolve in:\n" + doc, first >= 0);
+        assertEquals("Absolute file name should not have resolved in:\n" + doc,
+                -1, doc.indexOf(marker, first + 1));
+    }
+
+    // GROOVY-12271: the file name comes from a doc comment, so snippet resolution is confined
+    // to the package's snippet-files/ directory. A name escaping it must resolve to nothing
+    // rather than to a file elsewhere on the machine running the tool.
+    public void testSnippetTagExternalFormCannotEscapeSnippetFiles() throws Exception {
+        String pkg = "org/codehaus/groovy/tools/groovydoc/testfiles/docfiles";
+        Path tmp = Files.createTempDirectory("snippet-traversal-");
+        Path pkgDir = tmp.resolve(pkg);
+        Files.createDirectories(pkgDir);
+        Files.createDirectories(pkgDir.resolve("snippet-files"));
+
+        // Something worth stealing, outside snippet-files but reachable by walking up.
+        String secretText = "TOP_SECRET_CREDENTIAL_VALUE";
+        Files.writeString(tmp.resolve("secret.txt"), secretText);
+
+        // Depth from snippet-files/ back up to tmp: package segments plus snippet-files itself.
+        String upToTmp = "../".repeat(pkg.split("/").length + 1);
+        Files.writeString(pkgDir.resolve("Traversal.groovy"),
+                "package " + pkg.replace('/', '.') + "\n" +
+                "/**\n" +
+                " * relative: {@snippet file=\"" + upToTmp + "secret.txt\" keepHeader=true}\n" +
+                " * absolute: {@snippet file=\"" + tmp.resolve("secret.txt") + "\" keepHeader=true}\n" +
+                " */\n" +
+                "class Traversal {}\n");
+
+        String doc = renderSingle(tmp, pkg, "Traversal");
+        assertNotNull(doc);
+        assertFalse("Snippet file resolution escaped snippet-files/ in:\n" + doc,
+                doc.contains(secretText));
+    }
+
     /** Renders one class from a temporary source tree and returns its page. */
     private String renderSingle(Path sourcePath, String pkg, String simpleName) throws Exception {
         GroovyDocTool tool = new GroovyDocTool(