fix(download): use server-provided filename for cross-origin downloads (#417)

When the Download plugin fetched a cross-origin file over CORS, the
`Content-Disposition` response header was discarded, and the file was saved
under a generated blob name unless an explicit filename was configured.

The filename from the `Content-Disposition` header (including the RFC 5987
`filename*` form) is now used as a fallback when no explicit filename is
provided. The header must be exposed through `Access-Control-Expose-Headers`.

Author: igordanchenko

src/plugins/download/FileSaver.ts

@@ -3,12 +3,40 @@
  * https://github.com/eligrey/FileSaver.js/blob/master/src/FileSaver.js
  */
 
+export function parseContentDispositionFilename(disposition: string | null) {
+  if (!disposition) {
+    return undefined;
+  }
+
+  // RFC 5987 `filename*` takes precedence over `filename` (RFC 6266)
+  const extended = /filename\*\s*=\s*UTF-8''([^;]+)/i.exec(disposition);
+  if (extended) {
+    try {
+      const decoded = decodeURIComponent(extended[1].trim());
+      if (decoded) {
+        return decoded;
+      }
+    } catch (_) {
+      //
+    }
+  }
+
+  const plain = /filename\s*=\s*("[^"]*"|[^;]+)/i.exec(disposition);
+  return plain?.[1].trim().replace(/^"(.*)"$/, "$1") || undefined;
+}
+
+function getContentDisposition(xhr: XMLHttpRequest) {
+  // unlike `getResponseHeader()`, `getAllResponseHeaders()` doesn't produce console errors
+  // when the header is not exposed through `Access-Control-Expose-Headers`
+  return /^content-disposition:(.*)$/im.exec(xhr.getAllResponseHeaders())?.[1] ?? null;
+}
+
 function download(url: string, name?: string) {
   const xhr = new XMLHttpRequest();
   xhr.open("GET", url);
   xhr.responseType = "blob";
   xhr.onload = () => {
-    saveAs(xhr.response, name);
+    saveAs(xhr.response, name || parseContentDispositionFilename(getContentDisposition(xhr)));
   };
   xhr.onerror = () => {
     // eslint-disable-next-line no-console

test/unit/plugins/Download.spec.ts

@@ -4,6 +4,7 @@ import { vi } from "vitest";
 import { clickButton, lightbox, expectLightboxToBeOpen } from "../test-utils.js";
 import { Download } from "../../../src/plugins/index.js";
 import { LightboxExternalProps } from "../../../src/index.js";
+import { parseContentDispositionFilename } from "../../../src/plugins/download/FileSaver.js";
 
 function renderLightbox(props?: LightboxExternalProps) {
   return render(lightbox({ plugins: [Download], ...props }));
@@ -45,4 +46,31 @@ describe("Download", () => {
 
     expect(download).toHaveBeenCalled();
   });
+
+  it("parses Content-Disposition filename", () => {
+    expect(parseContentDispositionFilename(null)).toBeUndefined();
+    expect(parseContentDispositionFilename("")).toBeUndefined();
+    expect(parseContentDispositionFilename("inline")).toBeUndefined();
+    expect(parseContentDispositionFilename('inline; filename=""')).toBeUndefined();
+
+    expect(parseContentDispositionFilename('inline; filename="photo.jpg"')).toBe("photo.jpg");
+    expect(parseContentDispositionFilename("attachment; filename=photo.jpg")).toBe("photo.jpg");
+    expect(parseContentDispositionFilename("attachment; filename = photo.jpg ; size=1024")).toBe("photo.jpg");
+
+    // RFC 5987 encoded filename takes precedence
+    expect(parseContentDispositionFilename("attachment; filename*=UTF-8''na%C3%AFve.jpg")).toBe("naïve.jpg");
+    expect(
+      parseContentDispositionFilename("attachment; filename=\"fallback.jpg\"; filename*=UTF-8''f%C3%B8t%C3%B8.jpg"),
+    ).toBe("føtø.jpg");
+
+    // malformed percent-encoding falls back to the plain filename
+    expect(parseContentDispositionFilename("attachment; filename*=UTF-8''%E0%A4%A; filename=\"fallback.jpg\"")).toBe(
+      "fallback.jpg",
+    );
+
+    // empty encoded filename falls back to the plain filename
+    expect(parseContentDispositionFilename("attachment; filename*=UTF-8'' ; filename=\"fallback.jpg\"")).toBe(
+      "fallback.jpg",
+    );
+  });
 });