Skip to content

Email for professionals and teams

fix: proxy consented remote email images on Workers (#148)

Tarun76b9937cc512
diff --git a/src/app/api/remote-images/route.ts b/src/app/api/remote-images/route.ts
new file mode 100644
index 0000000..26b6dc5
--- /dev/null
+++ b/src/app/api/remote-images/route.ts
@@ -0,0 +1,40 @@
+import { requireSessionUser } from "@/lib/api/auth";
+import { getEnv } from "@/lib/cloudflare";
+import { fetchRemoteImage, RemoteImageError } from "@/lib/remote-images/fetch";
+import { isNodeRuntime } from "@/lib/runtime";
+
+const IMAGE_HEADERS = {
+ "Cache-Control": "private, no-store",
+ "Content-Security-Policy": "default-src 'none'; sandbox",
+ "Cross-Origin-Resource-Policy": "same-origin",
+ "X-Content-Type-Options": "nosniff",
+};
+
+export async function GET(request: Request) {
+ const env = getEnv();
+ const auth = await requireSessionUser(env, request);
+ if (auth.error) return auth.error;
+
+ if (isNodeRuntime(env)) {
+ return Response.json(
+ { error: "Remote images are unavailable in the self-hosted runtime" },
+ { status: 503, headers: { "Cache-Control": "no-store" } },
+ );
+ }
+
+ const requestUrl = new URL(request.url);
+ const remoteUrl = requestUrl.searchParams.get("url") ?? "";
+ try {
+ const image = await fetchRemoteImage(remoteUrl, { blockedOrigins: [requestUrl.origin] });
+ const body = new ArrayBuffer(image.body.byteLength);
+ new Uint8Array(body).set(image.body);
+ return new Response(body, {
+ headers: { ...IMAGE_HEADERS, "Content-Type": image.contentType },
+ });
+ } catch (error) {
+ if (error instanceof RemoteImageError) {
+ return Response.json({ error: error.message }, { status: error.status, headers: { "Cache-Control": "no-store" } });
+ }
+ return Response.json({ error: "Could not fetch remote image" }, { status: 502, headers: { "Cache-Control": "no-store" } });
+ }
+}
diff --git a/src/app/layout.tsx b/src/app/layout.tsx
index ac23892..56c06f9 100644
--- a/src/app/layout.tsx
+++ b/src/app/layout.tsx
@@ -1,6 +1,7 @@
import type { Metadata } from "next";
import { Geist, Geist_Mono } from "next/font/google";
import { Providers } from "@/components/providers";
+import { isNodeRuntime } from "@/lib/runtime";
import { LanguageProvider } from "@/components/language-provider";
import { DEFAULT_LOCALE, getDirection } from "@/lib/i18n/utils";
import { getRequestLocale, loadServerMessages } from "@/lib/i18n/server";
@@ -52,7 +53,7 @@ export default async function RootLayout({ children }: Readonly<{ children: Reac
const messages = locale === DEFAULT_LOCALE ? undefined : await loadServerMessages(locale);
const branding = await getHomeBranding();
return (
- <html lang={locale} dir={getDirection(locale)} suppressHydrationWarning>
+ <html lang={locale} dir={getDirection(locale)} data-remote-image-proxy={isNodeRuntime() ? "disabled" : "enabled"} suppressHydrationWarning>
<head>
<script dangerouslySetInnerHTML={{ __html: sidebarBootstrapScript }} />
<script dangerouslySetInnerHTML={{ __html: themeBootstrapScript }} />
diff --git a/src/components/messages/email-html-renderer.tsx b/src/components/messages/email-html-renderer.tsx
index cb485f3..036da4e 100644
--- a/src/components/messages/email-html-renderer.tsx
+++ b/src/components/messages/email-html-renderer.tsx
@@ -2,7 +2,7 @@
import { useLanguage } from "@/components/language-provider";
import { useEffect, useRef, useState } from "react";
-import { prepareEmailHtml } from "@/lib/email/html";
+import { prepareReaderEmailHtml } from "@/lib/remote-images/reader";
import { collapseQuotedEmailHtml } from "@/app/(dashboard)/inbox/[messageId]/quote-collapse-utils";
const BASE_STYLE = `
@@ -43,7 +43,11 @@ export function EmailHtmlRenderer({ html, className, preserveLeadingQuote = fals
if (!host.current) return;
host.current.dir = document.documentElement.dir || "ltr";
const root = host.current.shadowRoot ?? host.current.attachShadow({ mode: "open" });
- const prepared = prepareEmailHtml(html, { reader: true, allowRemote });
+ const prepared = prepareReaderEmailHtml(html, {
+ reader: true,
+ allowRemote,
+ proxyRemote: document.documentElement.dataset.remoteImageProxy !== "disabled",
+ });
setHasRemote(prepared.hasRemote);
const base = document.createElement("style");
base.textContent = `${BASE_STYLE}\n${prepared.rootTag} { display:block; font:14px/1.5 Arial,sans-serif; color:#202124; background:#fff; color-scheme:light; }\n${prepared.bodyTag} { display:block; }\n:host(.mf-dark) ${prepared.rootTag} { background:transparent; }`;
diff --git a/src/lib/remote-images/fetch.ts b/src/lib/remote-images/fetch.ts
new file mode 100644
index 0000000..794cdc6
--- /dev/null
+++ b/src/lib/remote-images/fetch.ts
@@ -0,0 +1,223 @@
+export const REMOTE_IMAGE_MAX_URL_LENGTH = 4096;
+export const REMOTE_IMAGE_MAX_BYTES = 5 * 1024 * 1024;
+export const REMOTE_IMAGE_MAX_REDIRECTS = 3;
+export const REMOTE_IMAGE_TIMEOUT_MS = 10_000;
+
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+const ALLOWED_CONTENT_TYPES = new Set([
+ "image/png",
+ "image/jpeg",
+ "image/gif",
+ "image/webp",
+ "image/avif",
+]);
+
+export type RemoteImageFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+
+export class RemoteImageError extends Error {
+ constructor(
+ message: string,
+ readonly status: number,
+ readonly code: string,
+ ) {
+ super(message);
+ this.name = "RemoteImageError";
+ }
+}
+
+export type RemoteImageResult = {
+ body: Uint8Array;
+ contentType: string;
+};
+
+export type RemoteImageFetchOptions = {
+ fetch?: RemoteImageFetch;
+ blockedOrigins?: Iterable<string>;
+ timeoutMs?: number;
+ maxBytes?: number;
+ maxRedirects?: number;
+};
+
+function invalidUrl(message = "Invalid remote image URL"): never {
+ throw new RemoteImageError(message, 400, "invalid_url");
+}
+
+function isIpLiteral(hostname: string): boolean {
+ return hostname.startsWith("[") || /^\d{1,3}(?:\.\d{1,3}){3}$/.test(hostname);
+}
+
+function isForbiddenHostname(hostname: string): boolean {
+ const host = hostname.toLowerCase().replace(/\.$/, "");
+ return host === "localhost"
+ || host === "local"
+ || host === "internal"
+ || host === "test"
+ || host.endsWith(".localhost")
+ || host.endsWith(".local")
+ || host.endsWith(".internal")
+ || host === "home.arpa"
+ || host.endsWith(".home.arpa")
+ || host.endsWith(".test");
+}
+
+export function parseRemoteImageUrl(value: string, blockedOrigins: Iterable<string> = []): URL {
+ if (!value || value.length > REMOTE_IMAGE_MAX_URL_LENGTH) invalidUrl();
+
+ let url: URL;
+ try {
+ url = new URL(value);
+ } catch {
+ invalidUrl();
+ }
+
+ if (url.protocol !== "http:" && url.protocol !== "https:") invalidUrl();
+ if (url.username || url.password || url.port) invalidUrl();
+ if (!url.hostname || isIpLiteral(url.hostname) || isForbiddenHostname(url.hostname)) invalidUrl();
+
+ for (const origin of blockedOrigins) {
+ if (url.origin === origin) invalidUrl("Remote image URL cannot target this application");
+ }
+
+ return url;
+}
+
+function contentTypeEssence(value: string | null): string | null {
+ if (!value) return null;
+ const essence = value.split(";", 1)[0]?.trim().toLowerCase() ?? "";
+ return ALLOWED_CONTENT_TYPES.has(essence) ? essence : null;
+}
+
+function ascii(bytes: Uint8Array, start: number, length: number): string {
+ return String.fromCharCode(...bytes.subarray(start, start + length));
+}
+
+function hasAvifSignature(bytes: Uint8Array): boolean {
+ if (bytes.length < 16 || ascii(bytes, 4, 4) !== "ftyp") return false;
+ const boxSize = Math.min(bytes.length, new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).getUint32(0));
+ if (boxSize < 16) return false;
+ for (let offset = 8; offset + 4 <= boxSize; offset += 4) {
+ const brand = ascii(bytes, offset, 4);
+ if (brand === "avif" || brand === "avis") return true;
+ }
+ return false;
+}
+
+function signatureMatches(contentType: string, bytes: Uint8Array): boolean {
+ switch (contentType) {
+ case "image/png":
+ return bytes.length >= 8 && [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a].every((value, index) => bytes[index] === value);
+ case "image/jpeg":
+ return bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff;
+ case "image/gif":
+ return bytes.length >= 6 && (ascii(bytes, 0, 6) === "GIF87a" || ascii(bytes, 0, 6) === "GIF89a");
+ case "image/webp":
+ return bytes.length >= 12 && ascii(bytes, 0, 4) === "RIFF" && ascii(bytes, 8, 4) === "WEBP";
+ case "image/avif":
+ return hasAvifSignature(bytes);
+ default:
+ return false;
+ }
+}
+
+async function readLimitedBody(response: Response, maxBytes: number): Promise<Uint8Array> {
+ const declaredLength = Number(response.headers.get("content-length"));
+ if (Number.isFinite(declaredLength) && declaredLength > maxBytes) {
+ await response.body?.cancel().catch(() => undefined);
+ throw new RemoteImageError("Remote image is too large", 413, "too_large");
+ }
+ if (!response.body) throw new RemoteImageError("Remote image has no body", 502, "empty_body");
+
+ const reader = response.body.getReader();
+ const chunks: Uint8Array[] = [];
+ let size = 0;
+ try {
+ while (true) {
+ const { done, value } = await reader.read();
+ if (done) break;
+ size += value.byteLength;
+ if (size > maxBytes) {
+ await reader.cancel().catch(() => undefined);
+ throw new RemoteImageError("Remote image is too large", 413, "too_large");
+ }
+ chunks.push(value);
+ }
+ } catch (error) {
+ await reader.cancel().catch(() => undefined);
+ throw error;
+ }
+
+ const body = new Uint8Array(size);
+ let offset = 0;
+ for (const chunk of chunks) {
+ body.set(chunk, offset);
+ offset += chunk.byteLength;
+ }
+ return body;
+}
+
+export async function fetchRemoteImage(value: string, options: RemoteImageFetchOptions = {}): Promise<RemoteImageResult> {
+ const fetchImpl = options.fetch ?? fetch;
+ const blockedOrigins = [...(options.blockedOrigins ?? [])];
+ const maxBytes = options.maxBytes ?? REMOTE_IMAGE_MAX_BYTES;
+ const maxRedirects = options.maxRedirects ?? REMOTE_IMAGE_MAX_REDIRECTS;
+ let current = parseRemoteImageUrl(value, blockedOrigins);
+ const controller = new AbortController();
+ const timeout = setTimeout(() => controller.abort(), options.timeoutMs ?? REMOTE_IMAGE_TIMEOUT_MS);
+
+ try {
+ for (let redirects = 0; ; redirects += 1) {
+ let response: Response;
+ try {
+ response = await fetchImpl(current.href, {
+ method: "GET",
+ headers: { Accept: "image/png,image/jpeg,image/gif,image/webp,image/avif", "User-Agent": "Mailflare-Remote-Images/1.0" },
+ cache: "no-store",
+ redirect: "manual",
+ signal: controller.signal,
+ });
+ } catch {
+ if (controller.signal.aborted) throw new RemoteImageError("Remote image request timed out", 504, "timeout");
+ throw new RemoteImageError("Could not fetch remote image", 502, "upstream_error");
+ }
+
+ if (REDIRECT_STATUSES.has(response.status)) {
+ await response.body?.cancel().catch(() => undefined);
+ if (redirects >= maxRedirects) throw new RemoteImageError("Too many remote image redirects", 502, "too_many_redirects");
+ const location = response.headers.get("location");
+ if (!location) throw new RemoteImageError("Remote image redirect has no location", 502, "invalid_redirect");
+ let redirected: URL;
+ try {
+ redirected = new URL(location, current);
+ } catch {
+ throw new RemoteImageError("Remote image redirect is invalid", 502, "invalid_redirect");
+ }
+ current = parseRemoteImageUrl(redirected.href, blockedOrigins);
+ continue;
+ }
+
+ if (!response.ok) {
+ await response.body?.cancel().catch(() => undefined);
+ throw new RemoteImageError("Remote image server returned an error", 502, "upstream_status");
+ }
+ const contentType = contentTypeEssence(response.headers.get("content-type"));
+ if (!contentType) {
+ await response.body?.cancel().catch(() => undefined);
+ const receivedType = (response.headers.get("content-type") ?? "missing content type").split(";", 1)[0].slice(0, 100);
+ throw new RemoteImageError(`Remote resource is not a supported image (${receivedType})`, 415, "unsupported_type");
+ }
+ let body: Uint8Array;
+ try {
+ body = await readLimitedBody(response, maxBytes);
+ } catch (error) {
+ if (controller.signal.aborted && !(error instanceof RemoteImageError)) {
+ throw new RemoteImageError("Remote image request timed out", 504, "timeout");
+ }
+ throw error;
+ }
+ if (!signatureMatches(contentType, body)) throw new RemoteImageError("Remote image signature is invalid", 415, "invalid_signature");
+ return { body, contentType };
+ }
+ } finally {
+ clearTimeout(timeout);
+ }
+}
diff --git a/src/lib/remote-images/reader.ts b/src/lib/remote-images/reader.ts
new file mode 100644
index 0000000..c097648
--- /dev/null
+++ b/src/lib/remote-images/reader.ts
@@ -0,0 +1,149 @@
+import * as css from "css-tree";
+import parseSrcset from "parse-srcset";
+import { prepareEmailHtml } from "@/lib/email/html";
+
+export function remoteImageUrl(value: string): string {
+ try {
+ const url = new URL(value);
+ if (url.protocol !== "https:" && url.protocol !== "http:") return value;
+ return `/api/remote-images?url=${encodeURIComponent(url.href)}`;
+ } catch {
+ return value;
+ }
+}
+
+const IMAGE_FUNCTIONS = new Set(["image", "image-set", "-webkit-image-set", "src"]);
+const IMAGE_PROPERTIES = new Set([
+ "background", "background-image", "border-image", "border-image-source",
+ "list-style", "list-style-image", "mask", "mask-image", "-webkit-mask",
+ "-webkit-mask-image", "cursor", "shape-outside",
+]);
+
+/** Collect custom-property references, including nested var() fallbacks. */
+function variableReferences(node: css.CssNode, references: Set<string>) {
+ css.walk(node, child => {
+ if (child.type !== "Function" || css.ident.decode(child.name).toLowerCase() !== "var") return;
+ const name = child.children.first;
+ if (name?.type === "Identifier") references.add(css.ident.decode(name.name));
+ });
+}
+
+function renameVariables(node: css.CssNode, proxyNames: Map<string, string>) {
+ css.walk(node, child => {
+ if (child.type !== "Function" || css.ident.decode(child.name).toLowerCase() !== "var") return;
+ const name = child.children.first;
+ if (name?.type !== "Identifier") return;
+ const proxyName = proxyNames.get(css.ident.decode(name.name));
+ if (proxyName) name.name = css.ident.encode(proxyName);
+ });
+}
+
+function proxyStrings(node: css.CssNode) {
+ css.walk(node, child => {
+ if (child.type === "String") child.value = remoteImageUrl(child.value);
+ });
+}
+
+/** Give image uses their own variable chain so text and font uses keep the original value. */
+function proxyCss(ast: css.CssNode, proxyNames: Map<string, string>): string {
+ css.walk(ast, {
+ enter(node, item, list) {
+ if (node.type === "Declaration" && css.ident.decode(node.property).toLowerCase() === "src") return css.walk.skip;
+ if (node.type !== "Declaration") return;
+ const property = css.ident.decode(node.property);
+ if (property.startsWith("--")) {
+ const proxyName = proxyNames.get(property);
+ if (proxyName && item && list) {
+ const copy = css.clone(node) as typeof node;
+ copy.property = css.ident.encode(proxyName);
+ renameVariables(copy.value, proxyNames);
+ proxyStrings(copy.value);
+ list.insertData(copy, item.next);
+ }
+ // Preserve direct image-function strings in the original declaration.
+ css.walk(node.value, child => {
+ if (child.type === "Function" && IMAGE_FUNCTIONS.has(css.ident.decode(child.name).toLowerCase())) proxyStrings(child);
+ });
+ } else {
+ if (IMAGE_PROPERTIES.has(property.toLowerCase())) renameVariables(node.value, proxyNames);
+ css.walk(node.value, child => {
+ if (child.type === "Function" && IMAGE_FUNCTIONS.has(css.ident.decode(child.name).toLowerCase())) {
+ renameVariables(child, proxyNames);
+ proxyStrings(child);
+ }
+ });
+ }
+ return css.walk.skip;
+ },
+ });
+ css.walk(ast, node => {
+ if (node.type === "Declaration" && css.ident.decode(node.property).toLowerCase() === "src") return css.walk.skip;
+ if (node.type === "Url") node.value = remoteImageUrl(node.value);
+ });
+ return css.generate(ast);
+}
+
+export function prepareReaderEmailHtml(source: string, options: { reader: true; allowRemote: boolean; proxyRemote?: boolean }) {
+ const prepared = prepareEmailHtml(source, options);
+ if (!options.allowRemote || !prepared.hasRemote || options.proxyRemote === false) return prepared;
+
+ // Only transform the upstream sanitizer's inert output, never raw email HTML.
+ const template = document.createElement("template");
+ template.innerHTML = prepared.html;
+ const cssEntries: Array<{ element: Element; inline: boolean; ast: css.CssNode }> = [];
+ const definitions = new Map<string, css.CssNode[]>();
+ const imageVariables = new Set<string>();
+ for (const element of template.content.querySelectorAll("*")) {
+ for (const [value, inline] of [[element.getAttribute("style"), true], [element.tagName === "STYLE" ? element.textContent : null, false]] as const) {
+ if (!value) continue;
+ try {
+ const ast = css.parse(value, { context: inline ? "declarationList" : "stylesheet", parseCustomProperty: true });
+ css.walk(ast, node => {
+ if (node.type !== "Declaration") return;
+ const property = css.ident.decode(node.property);
+ if (property.startsWith("--")) {
+ const values = definitions.get(property) ?? [];
+ values.push(node.value);
+ definitions.set(property, values);
+ } else if (property.toLowerCase() !== "src") {
+ if (IMAGE_PROPERTIES.has(property.toLowerCase())) variableReferences(node.value, imageVariables);
+ css.walk(node.value, child => {
+ if (child.type === "Function" && IMAGE_FUNCTIONS.has(css.ident.decode(child.name).toLowerCase())) {
+ variableReferences(child, imageVariables);
+ }
+ });
+ }
+ return css.walk.skip;
+ });
+ cssEntries.push({ element, inline, ast });
+ } catch {
+ // Preserve CSS the parser cannot handle.
+ }
+ }
+ }
+ for (const name of imageVariables) {
+ for (const value of definitions.get(name) ?? []) variableReferences(value, imageVariables);
+ }
+ const proxyNames = new Map([...imageVariables].map((name, index) => [name, "--mailflare-image-" + prepared.rootTag + "-" + index]));
+ for (const { element, inline, ast } of cssEntries) {
+ try {
+ if (inline) element.setAttribute("style", proxyCss(ast, proxyNames));
+ else element.textContent = proxyCss(ast, proxyNames);
+ } catch {
+ // Keep the sanitizer's CSS if proxy generation fails.
+ }
+ }
+ for (const element of template.content.querySelectorAll("*")) {
+ for (const attribute of ["src", "background", "poster"]) {
+ const value = element.getAttribute(attribute);
+ if (value) element.setAttribute(attribute, remoteImageUrl(value));
+ }
+ const srcset = element.getAttribute("srcset");
+ if (srcset) {
+ element.setAttribute("srcset", parseSrcset(srcset).map(candidate =>
+ `${remoteImageUrl(candidate.url)}${candidate.w ? ` ${candidate.w}w` : candidate.d !== undefined ? ` ${candidate.d}x` : ""}`,
+ ).join(", "));
+ }
+ }
+ return { ...prepared, html: template.innerHTML };
+}
diff --git a/tests/remote-images-fetch.test.mjs b/tests/remote-images-fetch.test.mjs
new file mode 100644
index 0000000..4e3f940
--- /dev/null
+++ b/tests/remote-images-fetch.test.mjs
@@ -0,0 +1,229 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import test, { after } from "node:test";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { build } from "esbuild";
+
+const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+const outDir = mkdtempSync(join(tmpdir(), "mailflare-remote-images-"));
+after(() => rmSync(outDir, { recursive: true, force: true }));
+
+await build({
+ entryPoints: [join(root, "src/lib/remote-images/fetch.ts")],
+ outfile: join(outDir, "fetch.mjs"),
+ bundle: true,
+ platform: "node",
+ format: "esm",
+ target: "node22",
+ logLevel: "silent",
+});
+
+await build({
+ entryPoints: [join(root, "src/app/api/remote-images/route.ts")],
+ outfile: join(outDir, "route.mjs"),
+ bundle: true,
+ platform: "node",
+ format: "esm",
+ target: "node22",
+ logLevel: "silent",
+ alias: { "@": join(root, "src") },
+ plugins: [{
+ name: "remote-image-route-stubs",
+ setup(esbuild) {
+ const stubs = new Map([
+ ["@/lib/api/auth", "export async function requireSessionUser() { return globalThis.remoteImageTestAuthenticated === false ? { user: null, error: Response.json({ error: 'Unauthorized' }, { status: 401 }) } : { user: { id: 'u' }, error: null }; }"],
+ ["@/lib/cloudflare", "export function getEnv() { return {}; }"],
+ ["@/lib/runtime", "export function isNodeRuntime() { return false; }"],
+ ]);
+ esbuild.onResolve({ filter: /^@\/lib\/(?:api\/auth|cloudflare|runtime)$/ }, (args) => ({ path: args.path, namespace: "route-stub" }));
+ esbuild.onLoad({ filter: /.*/, namespace: "route-stub" }, (args) => ({ contents: stubs.get(args.path), loader: "js" }));
+ },
+ }],
+});
+
+const {
+ fetchRemoteImage,
+ parseRemoteImageUrl,
+ RemoteImageError,
+} = await import(pathToFileURL(join(outDir, "fetch.mjs")).href);
+const { GET } = await import(pathToFileURL(join(outDir, "route.mjs")).href);
+
+const png = Uint8Array.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 1, 2, 3]);
+
+test("the route requires a session before any outbound fetch", async (t) => {
+ globalThis.remoteImageTestAuthenticated = false;
+ t.after(() => { delete globalThis.remoteImageTestAuthenticated; });
+ let calls = 0;
+ t.mock.method(globalThis, "fetch", async () => {
+ calls += 1;
+ return new Response(png, { headers: { "Content-Type": "image/png" } });
+ });
+ const response = await GET(new Request("https://mail.example/api/remote-images?url=https%3A%2F%2Fimages.example%2Fphoto.png"));
+ assert.equal(response.status, 401);
+ assert.equal(calls, 0);
+});
+
+test("a valid image ignores restrictive upstream response headers", async () => {
+ const calls = [];
+ const result = await fetchRemoteImage("https://images.example/photo.png", {
+ fetch: async (url, init) => {
+ calls.push({ url: url.href, init });
+ return new Response(png, { headers: { "Content-Type": "image/png", "Cross-Origin-Resource-Policy": "same-origin" } });
+ },
+ });
+ assert.equal(result.contentType, "image/png");
+ assert.deepEqual(result.body, png);
+ assert.equal("headers" in result, false);
+ assert.equal(calls[0].init.redirect, "manual");
+ assert.equal(new Headers(calls[0].init.headers).has("cookie"), false);
+ assert.equal(new Headers(calls[0].init.headers).has("authorization"), false);
+});
+
+test("the authenticated route replaces upstream CORP with locally usable safe headers", async (t) => {
+ t.mock.method(globalThis, "fetch", async () => new Response(png, {
+ headers: {
+ "Content-Type": "image/png",
+ "Cross-Origin-Resource-Policy": "same-origin",
+ "Set-Cookie": "upstream=secret",
+ },
+ }));
+ const response = await GET(new Request("https://mail.example/api/remote-images?url=https%3A%2F%2Fimages.example%2Fphoto.png"));
+ assert.equal(response.status, 200);
+ assert.deepEqual(new Uint8Array(await response.arrayBuffer()), png);
+ assert.equal(response.headers.get("Content-Type"), "image/png");
+ assert.equal(response.headers.get("Cache-Control"), "private, no-store");
+ assert.equal(response.headers.get("Cross-Origin-Resource-Policy"), "same-origin");
+ assert.equal(response.headers.get("Content-Security-Policy"), "default-src 'none'; sandbox");
+ assert.equal(response.headers.get("X-Content-Type-Options"), "nosniff");
+ assert.equal(response.headers.has("Set-Cookie"), false);
+});
+
+test("the route rejects a missing or invalid url query before outbound fetch", async (t) => {
+ let calls = 0;
+ t.mock.method(globalThis, "fetch", async () => {
+ calls += 1;
+ return new Response(png, { headers: { "Content-Type": "image/png" } });
+ });
+ for (const requestUrl of [
+ "https://mail.example/api/remote-images",
+ "https://mail.example/api/remote-images?url=file%3A%2F%2F%2Fetc%2Fpasswd",
+ ]) {
+ const response = await GET(new Request(requestUrl));
+ assert.equal(response.status, 400);
+ }
+ assert.equal(calls, 0);
+});
+
+test("every redirect is validated and private redirect loops stop before another fetch", async () => {
+ let calls = 0;
+ await assert.rejects(
+ fetchRemoteImage("https://images.example/start", {
+ fetch: async () => {
+ calls += 1;
+ return new Response(null, { status: 302, headers: { Location: "http://127.0.0.1/private.png" } });
+ },
+ }),
+ (error) => error instanceof RemoteImageError && error.code === "invalid_url" && error.status === 400,
+ );
+ assert.equal(calls, 1);
+});
+
+test("redirect count is capped", async () => {
+ let calls = 0;
+ await assert.rejects(
+ fetchRemoteImage("https://images.example/loop", {
+ maxRedirects: 3,
+ fetch: async (url) => {
+ calls += 1;
+ return new Response(null, { status: 302, headers: { Location: url.href } });
+ },
+ }),
+ (error) => error.code === "too_many_redirects",
+ );
+ assert.equal(calls, 4);
+});
+
+test("streaming size cap cancels a body that exceeds the limit", async () => {
+ let cancelled = false;
+ const body = new ReadableStream({
+ start(controller) {
+ controller.enqueue(png);
+ controller.enqueue(new Uint8Array(8));
+ },
+ cancel() { cancelled = true; },
+ });
+ await assert.rejects(
+ fetchRemoteImage("https://images.example/large.png", {
+ maxBytes: png.byteLength,
+ fetch: async () => new Response(body, { headers: { "Content-Type": "image/png" } }),
+ }),
+ (error) => error.code === "too_large" && error.status === 413,
+ );
+ assert.equal(cancelled, true);
+});
+
+test("non-image MIME and spoofed image signatures are rejected", async () => {
+ await assert.rejects(
+ fetchRemoteImage("https://images.example/page", {
+ fetch: async () => new Response("<html></html>", { headers: { "Content-Type": "text/html" } }),
+ }),
+ (error) => error.code === "unsupported_type" && error.status === 415,
+ );
+ await assert.rejects(
+ fetchRemoteImage("https://images.example/fake.png", {
+ fetch: async () => new Response("<html></html>", { headers: { "Content-Type": "image/png" } }),
+ }),
+ (error) => error.code === "invalid_signature" && error.status === 415,
+ );
+});
+
+test("the total request timeout aborts an in-flight fetch", async () => {
+ await assert.rejects(
+ fetchRemoteImage("https://images.example/slow.png", {
+ timeoutMs: 10,
+ fetch: async (_url, init) => new Promise((_resolve, reject) => {
+ init.signal.addEventListener("abort", () => reject(init.signal.reason), { once: true });
+ }),
+ }),
+ (error) => error.code === "timeout" && error.status === 504,
+ );
+});
+
+test("the total request timeout also covers a body that stalls after headers", async () => {
+ await assert.rejects(
+ fetchRemoteImage("https://images.example/slow-body.png", {
+ timeoutMs: 10,
+ fetch: async (_url, init) => new Response(new ReadableStream({
+ start(controller) {
+ init.signal.addEventListener("abort", () => controller.error(init.signal.reason), { once: true });
+ },
+ }), { headers: { "Content-Type": "image/png" } }),
+ }),
+ (error) => error.code === "timeout" && error.status === 504,
+ );
+});
+
+test("invalid query targets are rejected before fetch", () => {
+ for (const value of [
+ "",
+ "not a url",
+ "file:///etc/passwd",
+ "https://user:[email protected]/a.png",
+ "https://example.com:8443/a.png",
+ "http://localhost/a.png",
+ "http://service.internal/a.png",
+ "http://router.home.arpa/a.png",
+ "http://127.1/a.png",
+ "http://[::1]/a.png",
+ "https://mail.example/api/remote-images?url=x",
+ ]) {
+ assert.throws(
+ () => parseRemoteImageUrl(value, ["https://mail.example"]),
+ (error) => error.code === "invalid_url" && error.status === 400,
+ value,
+ );
+ }
+ assert.throws(() => parseRemoteImageUrl(`https://example.com/${"a".repeat(4096)}`), /Invalid remote image URL/);
+});
diff --git a/tests/remote-images-reader.test.mjs b/tests/remote-images-reader.test.mjs
new file mode 100644
index 0000000..f2a9bc7
--- /dev/null
+++ b/tests/remote-images-reader.test.mjs
@@ -0,0 +1,92 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { build } from "esbuild";
+import { JSDOM } from "jsdom";
+
+const dom = new JSDOM("", { url: "https://mail.example/" });
+globalThis.window = dom.window;
+globalThis.document = dom.window.document;
+globalThis.HTMLElement = dom.window.HTMLElement;
+const bundle = await build({ entryPoints: ["src/lib/remote-images/reader.ts"], bundle: true, write: false, platform: "browser", format: "esm" });
+const { prepareReaderEmailHtml } = await import(`data:text/javascript;base64,${Buffer.from(bundle.outputFiles[0].text).toString("base64")}`);
+const endpoint = url => `/api/remote-images?url=${encodeURIComponent(url)}`;
+
+const source = `<style>.hero{background:url(https://cdn.example/bg.png)}.retina{background:image-set("https://cdn.example/retina.png" 2x)}</style>
+<img src="https://cdn.example/logo.gif" srcset="https://cdn.example/small.png 1x, https://cdn.example/large.png 2x">
+<div background="https://cdn.example/background.png" style="background-image:url(https://cdn.example/inline.png)">Mail</div>
+<img src="/api/messages/m/attachments/a?preview=1"><img src="data:image/gif;base64,R0lGODlhAQABAAD/ACwAAAAAAQABAAACADs=">
+<a href="https://example.com/help">Help</a><script>alert(1)</script>`;
+
+test("blocked remote content never creates proxy requests", () => {
+ const result = prepareReaderEmailHtml(source, { reader: true, allowRemote: false });
+ assert.equal(result.hasRemote, true);
+ assert.doesNotMatch(result.html, /\/api\/remote-images/);
+ assert.doesNotMatch(result.html, /https:\/\/cdn\.example/);
+});
+
+test("allowed raster resources, srcset and CSS image URLs use the authenticated proxy", () => {
+ const result = prepareReaderEmailHtml(source, { reader: true, allowRemote: true });
+ for (const file of ["logo.gif", "small.png", "large.png", "bg.png", "retina.png", "inline.png"]) {
+ assert.ok(result.html.includes(endpoint(`https://cdn.example/${file}`)), file);
+ }
+ assert.ok(result.html.includes("/api/messages/m/attachments/a?preview=1"));
+ assert.ok(result.html.includes("data:image/gif;base64,"));
+ assert.ok(result.html.includes('href="https://example.com/help"'));
+ assert.doesNotMatch(result.html, /<script/);
+});
+
+test("blocking the same message again removes proxy resources", () => {
+ const allowed = prepareReaderEmailHtml(source, { reader: true, allowRemote: true });
+ assert.match(allowed.html, /\/api\/remote-images/);
+ const blocked = prepareReaderEmailHtml(source, { reader: true, allowRemote: false });
+ assert.doesNotMatch(blocked.html, /\/api\/remote-images/);
+});
+
+test("shared CSS variables keep their original text value for non-image uses", () => {
+ const html = '<style>:root{--shared:"https://cdn.example/shared.png"}.image{background:image-set(var(--shared) 1x)}.text{content:var(--shared)}</style>';
+ const result = prepareReaderEmailHtml(html, { reader: true, allowRemote: true });
+ assert.ok(result.html.includes(endpoint("https://cdn.example/shared.png")));
+ assert.match(result.html, /--shared:"https:\/\/cdn\.example\/shared\.png"/);
+ assert.match(result.html, /content:var\(--shared\)/);
+ assert.match(result.html, /image-set\(var\(--mailflare-image-/);
+});
+
+test("image-valued properties proxy strings through nested custom properties", () => {
+ const html = '<style>:root{--src:"https://cdn.example/chain.png";--img:image-set(var(--src) 1x);--text:"https://cdn.example/text.png"}.hero{background-image:var(--img);content:var(--text)}</style><div class="hero">Mail</div>';
+ const result = prepareReaderEmailHtml(html, { reader: true, allowRemote: true });
+ assert.ok(result.html.includes(endpoint("https://cdn.example/chain.png")));
+ assert.match(result.html, /background-image:var\(--mailflare-image-/);
+ assert.match(result.html, /--img:image-set\(var\(--src\) 1x\)/);
+ assert.match(result.html, /content:var\(--text\)/);
+ assert.ok(!result.html.includes(endpoint("https://cdn.example/text.png")));
+});
+
+test("CSS custom-property image strings and fallbacks use the authenticated proxy", () => {
+ const html = `<style>:root{--image:"https://cdn.example/variable.png";--chain:var(--image);--unrelated:"https://cdn.example/text.png"}
+ .hero{background:image-set(var(--chain) 1x,var(--missing,"https://cdn.example/fallback.png") 2x);content:var(--unrelated)}
+ .cross{background:image-set(var(--cross) 1x)}</style>
+ <div class="hero cross" style="--cross:'https://cdn.example/cross.png';--inline:'https://cdn.example/inline-variable.png';background-image:image-set(var(--inline) 1x)">Mail</div>`;
+ const result = prepareReaderEmailHtml(html, { reader: true, allowRemote: true });
+ for (const file of ["variable.png", "fallback.png", "cross.png", "inline-variable.png"]) {
+ assert.ok(result.html.includes(endpoint(`https://cdn.example/${file}`)), file);
+ }
+ assert.match(result.html, /https:\/\/cdn\.example\/text\.png/);
+ assert.ok(!result.html.includes(endpoint("https://cdn.example/text.png")));
+ assert.match(result.html, /image-set\(var\(--mailflare-image-/);
+ assert.doesNotMatch(result.html, /image-set\(var\(--chain\)/);
+});
+
+test("self-hosted rendering preserves permitted direct URLs without an unsupported proxy", () => {
+ const result = prepareReaderEmailHtml(source, { reader: true, allowRemote: true, proxyRemote: false });
+ assert.doesNotMatch(result.html, /\/api\/remote-images/);
+ assert.match(result.html, /https:\/\/cdn\.example\/logo.gif/);
+ assert.doesNotMatch(result.html, /<script/);
+});
+
+test("permitted font sources remain direct while CSS raster images use the image proxy", () => {
+ const html = '<style>@font-face{font-family:mail;src:url(https://cdn.example/font.woff2) format("woff2")}.hero{background-image:url(https://cdn.example/bg.png)}</style><div class="hero">Mail</div>';
+ const result = prepareReaderEmailHtml(html, { reader: true, allowRemote: true });
+ assert.match(result.html, /https:\/\/cdn\.example\/font\.woff2/);
+ assert.ok(result.html.includes(endpoint("https://cdn.example/bg.png")));
+ assert.ok(!result.html.includes(endpoint("https://cdn.example/font.woff2")));
+});
diff --git a/tests/remote-images-route.test.mjs b/tests/remote-images-route.test.mjs
new file mode 100644
index 0000000..9e1790b
--- /dev/null
+++ b/tests/remote-images-route.test.mjs
@@ -0,0 +1,48 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import test, { after } from "node:test";
+import { build } from "esbuild";
+
+const project = join(dirname(fileURLToPath(import.meta.url)), "..");
+const temporary = mkdtempSync(join(project, "node_modules", "remote-route-test-"));
+after(() => { rmSync(temporary, { recursive: true, force: true }); delete globalThis.proxyAuth; delete globalThis.proxyEnv; delete globalThis.proxyFetch; });
+const mocks = {
+ "@/lib/cloudflare": "export function getEnv(){return globalThis.proxyEnv}",
+ "@/lib/api/auth": "export async function requireSessionUser(){return globalThis.proxyAuth}",
+ "@/lib/remote-images/fetch": "export class RemoteImageError extends Error { constructor(message,status){super(message);this.status=status} } export function fetchRemoteImage(...args){return globalThis.proxyFetch(...args)}",
+};
+await build({ entryPoints: [join(project, "src/app/api/remote-images/route.ts")], outfile: join(temporary, "route.mjs"), bundle: true, platform: "node", format: "esm", packages: "external", alias: { "@": join(project, "src") }, logLevel: "silent", plugins: [{ name: "route-fixtures", setup(builder) {
+ builder.onResolve({ filter: /^@\/lib\/(cloudflare|api\/auth|remote-images\/fetch)$/ }, args => ({ path: args.path, namespace: "mock" }));
+ builder.onLoad({ filter: /.*/, namespace: "mock" }, args => ({ contents: mocks[args.path], loader: "js" }));
+} }] });
+const { GET } = await import(pathToFileURL(join(temporary, "route.mjs")).href);
+const request = () => new Request("https://mail.example/api/remote-images?url=https%3A%2F%2Fcdn.example%2Flogo.png");
+
+test("unauthenticated and self-hosted requests never make outbound proxy requests", async () => {
+ globalThis.proxyEnv = {};
+ globalThis.proxyFetch = () => { throw new Error("Unexpected outbound request"); };
+ globalThis.proxyAuth = { error: Response.json({ error: "Unauthorized" }, { status: 401 }) };
+ assert.equal((await GET(request())).status, 401);
+ globalThis.proxyAuth = { user: { id: "user" }, error: null };
+ globalThis.proxyEnv = { MAILFLARE_RUNTIME: "node" };
+ assert.equal((await GET(request())).status, 503);
+});
+
+test("authenticated Worker responses use private image headers and block the app origin", async () => {
+ globalThis.proxyAuth = { user: { id: "user" }, error: null };
+ globalThis.proxyEnv = {};
+ globalThis.proxyFetch = async (url, options) => {
+ assert.equal(url, "https://cdn.example/logo.png");
+ assert.deepEqual(options.blockedOrigins, ["https://mail.example"]);
+ return { body: new Uint8Array([1, 2, 3]), contentType: "image/png" };
+ };
+ const response = await GET(request());
+ assert.equal(response.status, 200);
+ assert.equal(response.headers.get("Cache-Control"), "private, no-store");
+ assert.equal(response.headers.get("Cross-Origin-Resource-Policy"), "same-origin");
+ assert.equal(response.headers.get("X-Content-Type-Options"), "nosniff");
+ assert.equal(response.headers.get("Content-Type"), "image/png");
+ assert.deepEqual([...new Uint8Array(await response.arrayBuffer())], [1, 2, 3]);
+});