fix: filename encoding of download (#22039)

tltv · web-flow · commit a24d06c9dbaf · 2025-08-25T10:32:35.000+03:00
Applies utf-8 encoding by default in Content-Disposition header for DownloadEvent. Fixes: #22007
diff --git a/flow-server/src/main/java/com/vaadin/flow/internal/EncodeUtil.java b/flow-server/src/main/java/com/vaadin/flow/internal/EncodeUtil.java
@@ -15,6 +15,9 @@
  */
 package com.vaadin.flow.internal;
 
+import java.nio.charset.StandardCharsets;
+import java.util.HexFormat;
+
 import static java.nio.charset.StandardCharsets.UTF_8;
 
 /**
@@ -27,6 +30,8 @@
  */
 public final class EncodeUtil {
 
+    private static final HexFormat HEX_FORMAT = HexFormat.of().withUpperCase();
+
     private EncodeUtil() {
         // Static utils only
     }
@@ -45,7 +50,7 @@ public static String rfc5987Encode(String value) {
         int i = 0;
         while (i < value.length()) {
             int cp = value.codePointAt(i);
-            if (cp < 127 && (Character.isLetterOrDigit(cp) || cp == '.')) {
+            if (cp < 127 && isRFC5987AttrChar(cp)) {
                 builder.append((char) cp);
             } else {
                 // Create string from a single code point
@@ -63,11 +68,59 @@ public static String rfc5987Encode(String value) {
 
     private static void appendHexBytes(StringBuilder builder, byte[] bytes) {
         for (byte byteValue : bytes) {
-            // mask with 0xFF to compensate for "negative" values
-            int intValue = byteValue & 0xFF;
-            String hexCode = Integer.toString(intValue, 16);
-            builder.append('%').append(hexCode);
+            builder.append('%');
+            HEX_FORMAT.toHexDigits(builder, byteValue);
         }
     }
 
+    private static boolean isRFC5987AttrChar(int codePoint) {
+        return Character.isLetterOrDigit(codePoint)
+                || "!#$&+-.^_`|~".indexOf(codePoint) >= 0;
+    }
+
+    /**
+     * Encodes the given header field param as defined in RFC 2047 for use in
+     * e.g. the <code>Content-Disposition</code> HTTP header.
+     *
+     * @param value
+     *            the string to encode, not <code>null</code>
+     * @return the encoded string
+     */
+    public static String rfc2047Encode(String value) {
+        byte[] source = value.getBytes(UTF_8);
+        StringBuilder sb = new StringBuilder(source.length << 1);
+        sb.append("=?").append(UTF_8.name()).append("?Q?");
+        for (byte b : source) {
+            if (b == 32) {
+                sb.append('_'); // Replace space with underscore
+            } else if (isPrintable(b)) {
+                sb.append((char) b);
+            } else {
+                sb.append('=');
+                HEX_FORMAT.toHexDigits(sb, b);
+            }
+        }
+        sb.append("?=");
+        return sb.toString();
+    }
+
+    private static boolean isPrintable(byte c) {
+        int b = c & 0xFF; // Convert to unsigned
+        // RFC 2045, Section 6.7, and RFC 2047, Section 4.2
+        // printable characters are 33-126, excluding "=?_
+        return (b >= 33 && b <= 126) && b != 34 && b != 61 && b != 63
+                && b != 95;
+    }
+
+    /**
+     * Checks if the given string contains only US-ASCII characters.
+     *
+     * @param text
+     *            the string to check, not <code>null</code>
+     * @return <code>true</code> if the string contains only US-ASCII
+     *         characters,
+     */
+    public static boolean isPureUSASCII(String text) {
+        return StandardCharsets.US_ASCII.newEncoder().canEncode(text);
+    }
 }
diff --git a/flow-server/src/main/java/com/vaadin/flow/server/streams/DownloadEvent.java b/flow-server/src/main/java/com/vaadin/flow/server/streams/DownloadEvent.java
@@ -27,6 +27,7 @@
 import com.vaadin.flow.component.Component;
 import com.vaadin.flow.component.UI;
 import com.vaadin.flow.dom.Element;
+import com.vaadin.flow.internal.EncodeUtil;
 import com.vaadin.flow.server.VaadinRequest;
 import com.vaadin.flow.server.VaadinResponse;
 import com.vaadin.flow.server.VaadinSession;
@@ -149,8 +150,20 @@ public void setFileName(String fileName) {
         if (fileName.isEmpty()) {
             response.setHeader("Content-Disposition", "attachment");
         } else {
-            response.setHeader("Content-Disposition",
-                    "attachment; filename=\"" + fileName + "\"");
+            StringBuilder value = new StringBuilder();
+            value.append("attachment; ");
+            if (EncodeUtil.isPureUSASCII(fileName)) {
+                value.append("filename=\"").append(fileName).append("\"");
+            } else {
+                value
+                        // fallback legacy support
+                        .append("filename=\"")
+                        .append(EncodeUtil.rfc2047Encode(fileName))
+                        // used primarily
+                        .append("\"; filename*=UTF-8''")
+                        .append(EncodeUtil.rfc5987Encode(fileName));
+            }
+            response.setHeader("Content-Disposition", value.toString());
         }
         this.fileName = fileName;
     }
diff --git a/flow-server/src/test/java/com/vaadin/flow/internal/EncodeUtilTest.java b/flow-server/src/test/java/com/vaadin/flow/internal/EncodeUtilTest.java
@@ -0,0 +1,99 @@
+/*
+ * Copyright 2000-2025 Vaadin Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not
+ * use this file except in compliance with the License. You may obtain a copy of
+ * the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations under
+ * the License.
+ */
+
+package com.vaadin.flow.internal;
+
+import org.junit.Assert;
+import org.junit.Test;
+
+public class EncodeUtilTest {
+
+    @Test(expected = NullPointerException.class)
+    public void rfc5987Encode_withNull_nullPointerException() {
+        EncodeUtil.rfc5987Encode(null);
+    }
+
+    @Test(expected = NullPointerException.class)
+    public void rfc2047Encode_withNull_nullPointerException() {
+        EncodeUtil.rfc2047Encode(null);
+    }
+
+    @Test
+    public void rfc5987Encode_asciiCharacters() {
+        String input = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789!#$&'*+-.^_`|~";
+        Assert.assertEquals(
+                "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789!#$&%27%2A+-.^_`|~",
+                EncodeUtil.rfc5987Encode(input));
+    }
+
+    // UTF-8 Basic Latin & Controls
+    @Test
+    public void rfc5987Encode_unicodeCharacters0to126() throws Exception {
+        StringBuilder text = new StringBuilder();
+        for (int codePoint = 0; codePoint <= 126; codePoint++) {
+            text.append(new String(new int[] { codePoint }, 0, 1));
+        }
+        Assert.assertEquals(
+                "%00%01%02%03%04%05%06%07%08%09%0A%0B%0C%0D%0E%0F%10%11%12%13%14%15%16%17%18%19%1A%1B%1C%1D%1E%1F%20!%22#$%25&%27%28%29%2A+%2C-.%2F0123456789%3A%3B%3C%3D%3E%3F%40ABCDEFGHIJKLMNOPQRSTUVWXYZ%5B%5C%5D^_`abcdefghijklmnopqrstuvwxyz%7B|%7D~",
+                EncodeUtil.rfc5987Encode(text.toString()));
+    }
+
+    // UTF-8 Latin-1 Supplement
+    @Test
+    public void rfc5987Encode_unicodeLatin1SupplementCharacters()
+            throws Exception {
+        Assert.assertEquals("%E2%82%AC%20%C3%BF",
+                EncodeUtil.rfc5987Encode("€ ÿ"));
+    }
+
+    // UTF-8 Latin Extended A
+    @Test
+    public void rfc5987Encode_unicodeLatinExtendACharacters() throws Exception {
+        Assert.assertEquals("%C4%80%C4%81", EncodeUtil.rfc5987Encode("Āā"));
+    }
+
+    @Test
+    public void rfc2047Encode_asciiCharacters() {
+        String input = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789!#$&'*+-.^_`|~ ?=\"";
+        Assert.assertEquals(
+                "=?UTF-8?Q?abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789!#$&'*+-.^=5F`|~_=3F=3D=22?=",
+                EncodeUtil.rfc2047Encode(input));
+    }
+
+    @Test
+    public void rfc2047Encode_nonAsciiCharacters() {
+        String input = "Řřüñîçødë 1中文 € ÿĀā";
+        Assert.assertEquals(
+                "=?UTF-8?Q?=C5=98=C5=99=C3=BC=C3=B1=C3=AE=C3=A7=C3=B8d=C3=AB_1=E4=B8=AD=E6=96=87_=E2=82=AC_=C3=BF=C4=80=C4=81?=",
+                EncodeUtil.rfc2047Encode(input));
+    }
+
+    @Test
+    public void isPureUSASCII_withAsciiOnly_returnTrue() {
+        String input = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789!#$&'*+-.^_`|~ ?=\"";
+        Assert.assertTrue(EncodeUtil.isPureUSASCII(input));
+    }
+
+    @Test
+    public void isPureUSASCII_withNonAscii_returnFalse() {
+        String input = "Řřüñîçøë中文€ÿĀā";
+        input.chars().forEach(c -> {
+            Assert.assertFalse(
+                    "Character " + (char) c + " should not be US-ASCII",
+                    EncodeUtil.isPureUSASCII(Character.toString((char) c)));
+        });
+    }
+}
diff --git a/flow-server/src/test/java/com/vaadin/flow/server/streams/DownloadEventTest.java b/flow-server/src/test/java/com/vaadin/flow/server/streams/DownloadEventTest.java
@@ -6,6 +6,7 @@
 import org.junit.Test;
 import org.mockito.Mockito;
 
+import com.vaadin.flow.internal.EncodeUtil;
 import com.vaadin.flow.server.VaadinRequest;
 import com.vaadin.flow.server.VaadinResponse;
 import com.vaadin.flow.server.VaadinService;
@@ -34,7 +35,18 @@ public void setFileName_nonEmptyFileName_setsContentDispositionFilenameQuotedToR
         String fileName = "test.txt";
         downloadEvent.setFileName(fileName);
         Mockito.verify(response).setHeader("Content-Disposition",
-                "attachment; filename=\"" + fileName + "\"");
+                "attachment;" + " filename=\"" + fileName + "\"");
+    }
+
+    @Test
+    public void setFileName_nonEmptyFileName_setsContentDispositionEncodedFilenameQuotedToResponse() {
+        DownloadEvent downloadEvent = new DownloadEvent(request, response,
+                session, null);
+        String fileName = "test üñîçødë.txt";
+        downloadEvent.setFileName(fileName);
+        Mockito.verify(response).setHeader("Content-Disposition", "attachment;"
+                + " filename=\"" + EncodeUtil.rfc2047Encode(fileName) + "\";"
+                + " filename*=UTF-8''" + EncodeUtil.rfc5987Encode(fileName));
     }
 
     @Test
diff --git a/flow-tests/test-root-context/src/main/java/com/vaadin/flow/uitest/ui/DownloadHandlerView.java b/flow-tests/test-root-context/src/main/java/com/vaadin/flow/uitest/ui/DownloadHandlerView.java
@@ -58,6 +58,19 @@ public String getUrlPostfix() {
         fileDownload.setHref(DownloadHandler.forFile(jsonFile).inline());
         fileDownload.setId("download-handler-file");
 
+        Anchor fileDownloadUnicodeName = new Anchor("",
+                "File (unicode name) DownloadHandler shorthand");
+        fileDownloadUnicodeName.setHref(DownloadHandler.forFile(jsonFile,
+                "download-Řřüñîçødë 1中文.json"));
+        fileDownloadUnicodeName.setId("download-handler-file-unicode");
+
+        Anchor fileDownloadUnicodeNameWithQuote = new Anchor("",
+                "File (unicode name with quote) DownloadHandler shorthand");
+        fileDownloadUnicodeNameWithQuote
+                .setHref(DownloadHandler.forFile(jsonFile, "download-\".json"));
+        fileDownloadUnicodeNameWithQuote
+                .setId("download-handler-file-unicode-quote");
+
         Anchor classDownload = new Anchor("",
                 "Class resource DownloadHandler shorthand");
         classDownload.setHref(DownloadHandler
@@ -117,8 +130,9 @@ public String getUrlPostfix() {
         inputStreamCallbackError
                 .setId("download-handler-input-stream-callback-error");
 
-        add(handlerDownload, fileDownload, classDownload, servletDownload,
-                inputStreamDownload, inputStreamErrorDownload,
+        add(handlerDownload, fileDownload, fileDownloadUnicodeName,
+                fileDownloadUnicodeNameWithQuote, classDownload,
+                servletDownload, inputStreamDownload, inputStreamErrorDownload,
                 inputStreamExceptionDownload, inputStreamCallbackError);
 
         NativeButton reattach = new NativeButton("Remove and add back",
diff --git a/flow-tests/test-root-context/src/test/java/com/vaadin/flow/uitest/ui/DownloadHandlerIT.java b/flow-tests/test-root-context/src/test/java/com/vaadin/flow/uitest/ui/DownloadHandlerIT.java
@@ -65,6 +65,63 @@ public void getDynamicDownloadHandlerFileResource() throws IOException {
         Assert.assertEquals("download.json", FilenameUtils.getName(url));
     }
 
+    @Test
+    public void getDynamicDownloadHandlerFileResourceUnicodeName()
+            throws IOException {
+        open();
+
+        WebElement link = findElement(By.id("download-handler-file-unicode"));
+        Assert.assertEquals(
+                "Anchor element should have router-ignore " + "attribute", "",
+                link.getAttribute("router-ignore"));
+        String url = link.getAttribute("href");
+
+        getDriver().manage().timeouts()
+                .scriptTimeout(Duration.of(15, ChronoUnit.SECONDS));
+
+        try (InputStream stream = download(url)) {
+            List<String> lines = IOUtils.readLines(stream,
+                    StandardCharsets.UTF_8);
+            Assert.assertEquals("""
+                    {
+                      "download": true
+                    }""", String.join("\n", lines));
+        }
+        // Special characters in the file name in URL are encoded.
+        Assert.assertEquals(
+                "download-%C5%98%C5%99%C3%BC%C3%B1%C3%AE%C3%A7%C3%B8d%C3%AB%201%E4%B8%AD%E6%96%87.json",
+                FilenameUtils.getName(url));
+    }
+
+    // jetty 12 may throw MalformedURLException which Flow logs as a warning
+    // when checking for static resource before handling the download request.
+    @Test
+    public void getDynamicDownloadHandlerFileResourceUnicodeNameWithQuote()
+            throws IOException {
+        open();
+
+        WebElement link = findElement(
+                By.id("download-handler-file-unicode-quote"));
+        Assert.assertEquals(
+                "Anchor element should have router-ignore " + "attribute", "",
+                link.getAttribute("router-ignore"));
+        String url = link.getAttribute("href");
+
+        getDriver().manage().timeouts()
+                .scriptTimeout(Duration.of(15, ChronoUnit.SECONDS));
+
+        try (InputStream stream = download(url)) {
+            List<String> lines = IOUtils.readLines(stream,
+                    StandardCharsets.UTF_8);
+            Assert.assertEquals("""
+                    {
+                      "download": true
+                    }""", String.join("\n", lines));
+        }
+        // Special characters in the file name in URL are encoded.
+        Assert.assertEquals("download-%22.json", FilenameUtils.getName(url));
+    }
+
     @Test
     public void getDynamicDownloadHandlerClassResource() throws IOException {
         open();
