This is an automated email from the ASF dual-hosted git repository.
pjfanning pushed a commit to branch trunk
in repository https://gitbox.apache.org/repos/asf/poi.git
The following commit(s) were added to refs/heads/trunk by this push:
new b05c33b58c WordToHtmlConverter: allow a custom hyperlink validator
(#1459)
b05c33b58c is described below
commit b05c33b58c0b1f5d5dfab5494356a955a434b9d9
Author: PJ Fanning <[email protected]>
AuthorDate: Thu Oct 22 23:31:28 2026 +0100
WordToHtmlConverter: allow a custom hyperlink validator (#1459)
A validator set with setHyperlinkValidator can reject further HYPERLINK
targets, e.g. to only link to some hosts. It is only consulted for targets
that pass WordToHtmlUtils.isSafeHyperlink, so it can never let a
javascript: or other script target through.
The isSafeHyperlink test now uses Hamcrest so a failure lists the targets
that were classified wrongly.
Follow-up to #1455.
Co-authored-by: Claude Opus 5.5 <[email protected]>
---
.../poi/hwpf/converter/WordToHtmlConverter.java | 31 ++++++-
.../apache/poi/hwpf/converter/WordToHtmlUtils.java | 9 +-
.../hwpf/converter/TestWordToHtmlConverter.java | 95 ++++++++++++++++------
3 files changed, 110 insertions(+), 25 deletions(-)
diff --git
a/poi-scratchpad/src/main/java/org/apache/poi/hwpf/converter/WordToHtmlConverter.java
b/poi-scratchpad/src/main/java/org/apache/poi/hwpf/converter/WordToHtmlConverter.java
index d8bb7dbf53..508626821c 100644
---
a/poi-scratchpad/src/main/java/org/apache/poi/hwpf/converter/WordToHtmlConverter.java
+++
b/poi-scratchpad/src/main/java/org/apache/poi/hwpf/converter/WordToHtmlConverter.java
@@ -25,6 +25,7 @@ import java.util.Deque;
import java.util.LinkedList;
import java.util.List;
import java.util.Objects;
+import java.util.function.Predicate;
import javax.xml.parsers.DocumentBuilder;
import javax.xml.parsers.ParserConfigurationException;
@@ -90,6 +91,8 @@ public class WordToHtmlConverter extends AbstractWordConverter
private Element notes;
+ private Predicate<String> hyperlinkValidator = hyperlink -> true;
+
/**
* Creates new instance of WordToHtmlConverter. Can be used for
* output several {@link HWPFDocument}s into single HTML document.
@@ -186,6 +189,32 @@ public class WordToHtmlConverter extends
AbstractWordConverter
return htmlDocumentFacade.getDocument();
}
+ /**
+ * @return the extra check a HYPERLINK field target has to pass to be
written as a link
+ * @see #setHyperlinkValidator(Predicate)
+ * @since 6.0.1
+ */
+ public Predicate<String> getHyperlinkValidator()
+ {
+ return hyperlinkValidator;
+ }
+
+ /**
+ * Sets an extra check a HYPERLINK field target has to pass to be written
as the
+ * {@code href} of a link, e.g. to only link to some hosts. The validator
is only
+ * consulted for targets that pass {@link
WordToHtmlUtils#isSafeHyperlink(String)}, so
+ * it can reject standard URLs but never let a {@code javascript:} or
other script
+ * target through. The text of a field whose target is rejected is kept,
but it is not
+ * linked. The default accepts every target that passes the built-in check.
+ *
+ * @param hyperlinkValidator returns true for the targets to write as links
+ * @since 6.0.1
+ */
+ public void setHyperlinkValidator( Predicate<String> hyperlinkValidator )
+ {
+ this.hyperlinkValidator = Objects.requireNonNull( hyperlinkValidator,
"hyperlinkValidator" );
+ }
+
@Override
protected void outputCharacters( Element pElement,
CharacterRun characterRun, String text )
@@ -318,7 +347,7 @@ public class WordToHtmlConverter extends
AbstractWordConverter
{
// keep the text of a link to e.g. a javascript: target, but don't
make it a link
Element basicLink = currentBlock;
- if ( WordToHtmlUtils.isSafeHyperlink( hyperlink ) ) {
+ if ( WordToHtmlUtils.isSafeHyperlink( hyperlink ) &&
hyperlinkValidator.test( hyperlink ) ) {
basicLink = htmlDocumentFacade.createHyperlink( hyperlink );
currentBlock.appendChild( basicLink );
}
diff --git
a/poi-scratchpad/src/main/java/org/apache/poi/hwpf/converter/WordToHtmlUtils.java
b/poi-scratchpad/src/main/java/org/apache/poi/hwpf/converter/WordToHtmlUtils.java
index 58bccd1dd8..31989cbabf 100644
---
a/poi-scratchpad/src/main/java/org/apache/poi/hwpf/converter/WordToHtmlUtils.java
+++
b/poi-scratchpad/src/main/java/org/apache/poi/hwpf/converter/WordToHtmlUtils.java
@@ -188,8 +188,15 @@ public class WordToHtmlUtils extends AbstractWordUtils
* paths), Windows drive paths and the common document link schemes are
accepted. The
* scheme is looked up the way browsers parse it, i.e. after dropping tabs
and line breaks
* anywhere and control characters and spaces at the start.
+ * <p>
+ * {@link WordToHtmlConverter} always applies this check, before any
validator set with
+ * {@link
WordToHtmlConverter#setHyperlinkValidator(java.util.function.Predicate)}.
+ *
+ * @param hyperlink the target of a HYPERLINK field
+ * @return true if the target can be written as the {@code href} of a link
+ * @since 6.0.1
*/
- static boolean isSafeHyperlink( final String hyperlink )
+ public static boolean isSafeHyperlink( final String hyperlink )
{
StringBuilder target = new StringBuilder( hyperlink.length() );
for ( int i = 0; i < hyperlink.length(); i++ )
diff --git
a/poi-scratchpad/src/test/java/org/apache/poi/hwpf/converter/TestWordToHtmlConverter.java
b/poi-scratchpad/src/test/java/org/apache/poi/hwpf/converter/TestWordToHtmlConverter.java
index 7bce7bbe29..8bbabc954b 100644
---
a/poi-scratchpad/src/test/java/org/apache/poi/hwpf/converter/TestWordToHtmlConverter.java
+++
b/poi-scratchpad/src/test/java/org/apache/poi/hwpf/converter/TestWordToHtmlConverter.java
@@ -18,6 +18,8 @@ package org.apache.poi.hwpf.converter;
import static org.apache.poi.POITestCase.assertContains;
import static org.apache.poi.POITestCase.assertNotContains;
+import static org.hamcrest.MatcherAssert.assertThat;
+import static org.hamcrest.Matchers.empty;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertNotNull;
@@ -31,6 +33,9 @@ import java.io.StringWriter;
import java.nio.charset.StandardCharsets;
import java.time.Duration;
import java.util.Arrays;
+import java.util.List;
+import java.util.function.Predicate;
+import java.util.stream.Collectors;
import java.util.regex.Matcher;
import javax.xml.transform.OutputKeys;
@@ -186,35 +191,55 @@ public class TestWordToHtmlConverter {
void testScriptHyperlink() throws Exception {
// the target of a HYPERLINK field is copied into the href of the
link, so a
// javascript: target ran script in the page when the link was followed
- try (POIFSFileSystem fs = new
POIFSFileSystem(SAMPLES.openResourceAsStream("hyperlink.doc"))) {
- replaceText(fs, "http://testuri.org/", "javascript:alert(1)");
+ String result = getScriptHyperlinkHtml(null);
+ assertNotContains(result, "javascript:");
+ assertContains(result, "<span class=\"s1\">Hyperlink text</span>");
+ }
- try (HWPFDocument hwpfDocument = new HWPFDocument(fs)) {
- String result = getHtmlText(hwpfDocument, true);
- assertNotContains(result, "javascript:");
- assertContains(result, "<span class=\"s1\">Hyperlink
text</span>");
- }
+ @Test
+ void testCustomHyperlinkValidator() throws Exception {
+ // a validator only applies to standard URLs, it can't let a
javascript: target through
+ String result = getScriptHyperlinkHtml(h -> true);
+ assertNotContains(result, "javascript:");
+ assertContains(result, "<span class=\"s1\">Hyperlink text</span>");
+
+ try (HWPFDocument hwpfDocument = new
HWPFDocument(SAMPLES.openResourceAsStream("hyperlink.doc"))) {
+ result = getHtmlText(hwpfDocument, true, h ->
h.startsWith("http://testuri.org/"));
+ assertContains(result, "<a href=\"http://testuri.org/\">");
+ }
+
+ try (HWPFDocument hwpfDocument = new
HWPFDocument(SAMPLES.openResourceAsStream("hyperlink.doc"))) {
+ result = getHtmlText(hwpfDocument, true, h -> false);
+ assertNotContains(result, "<a href");
+ assertContains(result, "<span class=\"s1\">Hyperlink text</span>");
}
}
@Test
void testIsSafeHyperlink() {
- assertTrue(WordToHtmlUtils.isSafeHyperlink("http://testuri.org/"));
- assertTrue(WordToHtmlUtils.isSafeHyperlink("HTTPS://testuri.org/"));
-
assertTrue(WordToHtmlUtils.isSafeHyperlink("mailto:[email protected]"));
- assertTrue(WordToHtmlUtils.isSafeHyperlink("file:///C:/docs/a.doc"));
- assertTrue(WordToHtmlUtils.isSafeHyperlink("C:\\docs\\a.doc"));
-
assertTrue(WordToHtmlUtils.isSafeHyperlink("\\\\server\\share\\a.doc"));
- assertTrue(WordToHtmlUtils.isSafeHyperlink("docs/a.doc"));
- assertTrue(WordToHtmlUtils.isSafeHyperlink("#_Toc1"));
- assertTrue(WordToHtmlUtils.isSafeHyperlink("a.doc#x:y"));
- assertTrue(WordToHtmlUtils.isSafeHyperlink(""));
- assertFalse(WordToHtmlUtils.isSafeHyperlink("javascript:alert(1)"));
- assertFalse(WordToHtmlUtils.isSafeHyperlink("JavaScript:alert(1)"));
- assertFalse(WordToHtmlUtils.isSafeHyperlink("
\u0001javascript:alert(1)"));
-
assertFalse(WordToHtmlUtils.isSafeHyperlink("java\tscr\nipt:alert(1)"));
- assertFalse(WordToHtmlUtils.isSafeHyperlink("vbscript:msgbox(1)"));
-
assertFalse(WordToHtmlUtils.isSafeHyperlink("data:text/html,<script>alert(1)</script>"));
+ List<String> safe = Arrays.asList(
+ "http://testuri.org/",
+ "HTTPS://testuri.org/",
+ "mailto:[email protected]",
+ "file:///C:/docs/a.doc",
+ "C:\\docs\\a.doc",
+ "\\\\server\\share\\a.doc",
+ "docs/a.doc",
+ "#_Toc1",
+ "a.doc#x:y",
+ "");
+ List<String> unsafe = Arrays.asList(
+ "javascript:alert(1)",
+ "JavaScript:alert(1)",
+ " \u0001javascript:alert(1)",
+ "java\tscr\nipt:alert(1)",
+ "vbscript:msgbox(1)",
+ "data:text/html,<script>alert(1)</script>");
+
+ assertThat("safe targets that are rejected",
+ safe.stream().filter(h ->
!WordToHtmlUtils.isSafeHyperlink(h)).collect(Collectors.toList()), empty());
+ assertThat("unsafe targets that are accepted",
+
unsafe.stream().filter(WordToHtmlUtils::isSafeHyperlink).collect(Collectors.toList()),
empty());
}
@Test
@@ -250,6 +275,21 @@ public class TestWordToHtmlConverter {
throw new IllegalStateException("font " + oldName + " not found");
}
+ /**
+ * Converts hyperlink.doc with the target of its HYPERLINK field changed
to a javascript: one.
+ *
+ * @param hyperlinkValidator the validator to set on the converter, or
null for the default
+ */
+ private static String getScriptHyperlinkHtml(Predicate<String>
hyperlinkValidator) throws Exception {
+ try (POIFSFileSystem fs = new
POIFSFileSystem(SAMPLES.openResourceAsStream("hyperlink.doc"))) {
+ replaceText(fs, "http://testuri.org/", "javascript:alert(1)");
+
+ try (HWPFDocument hwpfDocument = new HWPFDocument(fs)) {
+ return getHtmlText(hwpfDocument, true, hyperlinkValidator);
+ }
+ }
+ }
+
/**
* Overwrites every occurrence of a text in the WordDocument stream, in
place: the new
* text must have the same length as the old one.
@@ -281,9 +321,18 @@ public class TestWordToHtmlConverter {
}
private static String getHtmlText(HWPFDocument hwpfDocument, boolean
emulatePictureStorage) throws Exception {
+ return getHtmlText(hwpfDocument, emulatePictureStorage, null);
+ }
+
+ private static String getHtmlText(HWPFDocument hwpfDocument, boolean
emulatePictureStorage,
+ Predicate<String> hyperlinkValidator)
throws Exception {
Document newDocument = XMLHelper.newDocumentBuilder().newDocument();
WordToHtmlConverter wordToHtmlConverter = new
WordToHtmlConverter(newDocument);
+ if (hyperlinkValidator != null) {
+ wordToHtmlConverter.setHyperlinkValidator(hyperlinkValidator);
+ }
+
if (emulatePictureStorage) {
wordToHtmlConverter.setPicturesManager((content, pictureType,
suggestedName, widthInches, heightInches) -> suggestedName);
}
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]