@remit/web-client 0.0.135 → 0.0.136

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/web-client",
-  "version": "0.0.135",
+  "version": "0.0.136",
   "type": "module",
   "description": "Remit web client, published as composable primitives — the app shell, auth shells, and runtime config. A distributor imports what it composes and bundles it.",
   "exports": {

package/src/components/mail/MessageAttachments.interaction.test.ts

@@ -0,0 +1,245 @@
+/**
+ * The attachment list wired to the real download (#683): a click fetches the
+ * part's `contentUrl` and hands the bytes to the browser under the sanitized
+ * name, and a fetch that fails says what failed instead of doing nothing.
+ */
+
+import assert from "node:assert/strict";
+import { afterEach, describe, it } from "node:test";
+import { messageOperationsDescribeMessageQueryKey } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import type { RemitImapBodyPartResponse } from "@remit/api-http-client/types.gen.ts";
+import { createElement } from "react";
+import { createDomHarness, type DomHarness } from "../../test-support/dom";
+import { MessageAttachments } from "./MessageAttachments";
+
+let harness: DomHarness | undefined;
+const originalFetch = globalThis.fetch;
+const originalCreateElement = document.createElement.bind(document);
+const objectUrls = globalThis.URL as unknown as {
+	createObjectURL?: (blob: Blob) => string;
+	revokeObjectURL?: (value: string) => void;
+};
+const originalCreateObjectURL = objectUrls.createObjectURL;
+const originalRevokeObjectURL = objectUrls.revokeObjectURL;
+
+afterEach(() => {
+	harness?.close();
+	harness = undefined;
+	globalThis.fetch = originalFetch;
+	document.createElement = originalCreateElement;
+	objectUrls.createObjectURL = originalCreateObjectURL;
+	objectUrls.revokeObjectURL = originalRevokeObjectURL;
+});
+
+const bodyParts = (
+	...overrides: Partial<RemitImapBodyPartResponse>[]
+): RemitImapBodyPartResponse[] =>
+	overrides.map(
+		(override, index) =>
+			({
+				bodyPartId: `part-${index + 1}`,
+				mediaType: "APPLICATION",
+				mediaSubtype: "PDF",
+				sizeOctets: 4096,
+				disposition: "attachment",
+				dispositionFilename: "report.pdf",
+				contentUrl: `https://cdn.test/content/parts/${index + 2}`,
+				isMultipart: false,
+				...override,
+			}) as RemitImapBodyPartResponse,
+	);
+
+interface SavedFile {
+	filename: string;
+	url: string;
+}
+
+const captureSaves = (): SavedFile[] => {
+	const saved: SavedFile[] = [];
+	objectUrls.createObjectURL = () => "blob:test";
+	objectUrls.revokeObjectURL = () => undefined;
+
+	document.createElement = ((tag: string) => {
+		const element = originalCreateElement(tag);
+		if (tag === "a") {
+			const anchor = element as HTMLAnchorElement;
+			anchor.click = () =>
+				saved.push({ filename: anchor.download, url: anchor.href });
+		}
+		return element;
+	}) as typeof document.createElement;
+	return saved;
+};
+
+const MESSAGE_ID = "msg-1";
+
+const mount = (parts?: RemitImapBodyPartResponse[], hasAttachment = true) => {
+	harness = createDomHarness();
+	harness.renderApp(
+		createElement(MessageAttachments, {
+			messageId: MESSAGE_ID,
+			bodyParts: parts,
+			hasAttachment,
+		}),
+	);
+	return harness;
+};
+
+describe("MessageAttachments", () => {
+	it("lists each attachment part with a download control", () => {
+		const dom = mount(
+			bodyParts(
+				{ dispositionFilename: "board-pack.pdf" },
+				{
+					dispositionFilename: "site-plan.png",
+					mediaType: "IMAGE",
+					mediaSubtype: "PNG",
+					sizeOctets: 1024,
+				},
+			),
+		);
+
+		assert.match(dom.text(), /2 attachments/);
+		assert.ok(dom.byLabel("Download board-pack.pdf"));
+		assert.ok(dom.byLabel("Download site-plan.png"));
+		assert.match(dom.text(), /PNG · 1 KB/);
+	});
+
+	it("renders nothing for a message with no attachments", () => {
+		const dom = mount(
+			bodyParts({ disposition: "inline", mediaSubtype: "HTML" }),
+			false,
+		);
+		assert.equal(dom.html(), "");
+	});
+
+	it("downloads the part's content URL and saves it under the sanitized name", async () => {
+		const requested: string[] = [];
+		globalThis.fetch = (async (url: string) => {
+			requested.push(String(url));
+			return new Response("payload", { status: 200 });
+		}) as unknown as typeof fetch;
+		const saved = captureSaves();
+
+		const dom = mount(
+			bodyParts({
+				dispositionFilename: "../../../etc/passwd",
+				contentUrl: "https://cdn.test/content/parts/2",
+			}),
+		);
+		dom.click(dom.byLabel("Download passwd"));
+		await dom.flush();
+
+		assert.deepEqual(requested, ["https://cdn.test/content/parts/2"]);
+		assert.deepEqual(saved, [{ filename: "passwd", url: "blob:test" }]);
+	});
+
+	it("states what failed and offers a retry instead of doing nothing", async () => {
+		globalThis.fetch = (async () =>
+			new Response("gone", {
+				status: 404,
+				statusText: "Not Found",
+			})) as unknown as typeof fetch;
+
+		const dom = mount(bodyParts({ dispositionFilename: "board-pack.pdf" }));
+		dom.click(dom.byLabel("Download board-pack.pdf"));
+		await dom.flush();
+
+		const alert = dom.query('[data-testid="attachment-error"]');
+		assert.ok(alert, "a failed download must render an alert");
+		assert.match(alert.textContent ?? "", /missing from storage/);
+		assert.match(alert.textContent ?? "", /Re-sync the account/);
+		assert.match(alert.textContent ?? "", /Try again/);
+		assert.match(alert.innerHTML, /issues\/new/);
+	});
+
+	it("retries the same part when the failure's retry is taken", async () => {
+		let attempts = 0;
+		globalThis.fetch = (async () => {
+			attempts += 1;
+			return attempts === 1
+				? new Response("gone", { status: 404, statusText: "Not Found" })
+				: new Response("payload", { status: 200 });
+		}) as unknown as typeof fetch;
+		const saved = captureSaves();
+
+		const dom = mount(bodyParts({ dispositionFilename: "board-pack.pdf" }));
+		dom.click(dom.byLabel("Download board-pack.pdf"));
+		await dom.flush();
+
+		dom.click(dom.byText("button", "Try again"));
+		await dom.flush();
+
+		assert.equal(attempts, 2);
+		assert.deepEqual(saved, [{ filename: "board-pack.pdf", url: "blob:test" }]);
+		assert.equal(dom.query('[data-testid="attachment-error"]'), null);
+	});
+
+	// The signed content URL outlives neither an hour nor a re-signing, and a
+	// deferred part is materialized by the describe read itself. Re-hitting the
+	// same URL cannot fix either, so the retry goes back through describeMessage
+	// and uses the URL that read minted.
+	it("renews the content URL through describeMessage when the link expired", async () => {
+		const requested: string[] = [];
+		globalThis.fetch = (async (url: string) => {
+			requested.push(String(url));
+			return requested.length === 1
+				? new Response("expired", {
+						status: 403,
+						headers: { "x-remit-403-reason": "expired" },
+					})
+				: new Response("payload", { status: 200 });
+		}) as unknown as typeof fetch;
+		const saved = captureSaves();
+
+		const dom = mount(
+			bodyParts({ contentUrl: "https://cdn.test/parts/2?exp=1&sig=old" }),
+		);
+		dom.queryClient.setQueryData(
+			messageOperationsDescribeMessageQueryKey({
+				path: { messageId: MESSAGE_ID },
+			}),
+			{
+				bodyParts: bodyParts({
+					contentUrl: "https://cdn.test/parts/2?exp=2&sig=new",
+				}),
+			},
+		);
+
+		dom.click(dom.byLabel("Download report.pdf"));
+		await dom.flush();
+		await dom.flush();
+
+		assert.deepEqual(requested, [
+			"https://cdn.test/parts/2?exp=1&sig=old",
+			"https://cdn.test/parts/2?exp=2&sig=new",
+		]);
+		assert.equal(saved.length, 1);
+		assert.equal(dom.query('[data-testid="attachment-error"]'), null);
+	});
+
+	it("does not re-read the message for a failure a re-read cannot fix", async () => {
+		let attempts = 0;
+		globalThis.fetch = (async () => {
+			attempts += 1;
+			return new Response("gone", { status: 404, statusText: "Not Found" });
+		}) as unknown as typeof fetch;
+
+		const dom = mount(bodyParts({}));
+		dom.click(dom.byLabel("Download report.pdf"));
+		await dom.flush();
+
+		assert.equal(attempts, 1);
+		assert.ok(dom.query('[data-testid="attachment-error"]'));
+	});
+
+	it("says so when the server flags an attachment no part describes", () => {
+		const dom = mount([], true);
+		assert.match(dom.text(), /none of its parts describe one/);
+	});
+
+	it("claims nothing while the message is still loading", () => {
+		const dom = mount(undefined, true);
+		assert.equal(dom.html(), "");
+	});
+});

package/src/components/mail/MessageAttachments.tsx

@@ -0,0 +1,153 @@
+import { messageOperationsDescribeMessageQueryKey } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import type {
+	RemitImapBodyPartResponse,
+	RemitImapDescribeMessageResponse,
+} from "@remit/api-http-client/types.gen.ts";
+import { type AttachmentDownloadState, AttachmentList } from "@remit/ui";
+import { useQueryClient } from "@tanstack/react-query";
+import { useMemo, useState } from "react";
+import { useAuthProvider } from "@/auth/provider";
+import {
+	attachmentFailureContent,
+	attachmentReportUrl,
+	extractAttachmentFailureDetail,
+	extractAttachmentFailureReason,
+	fetchAttachment,
+	isRepairableByRefetch,
+	saveBlob,
+} from "@/lib/attachment-download";
+import {
+	type MessageAttachment,
+	selectMessageAttachments,
+} from "@/lib/message-attachments";
+
+interface MessageAttachmentsProps {
+	messageId: string;
+	/** Body parts from `describeMessage`; absent while the message is loading. */
+	bodyParts?: readonly RemitImapBodyPartResponse[];
+	/** The thread row's server-side attachment flag. */
+	hasAttachment?: boolean;
+	className?: string;
+}
+
+const IDLE: AttachmentDownloadState = { status: "idle" };
+
+/**
+ * The attachments carried by an open message, and the download behind each row.
+ *
+ * Download state is per row and lives here rather than in a query: a download is
+ * a one-shot user action with no cached result to hold, and the bytes are handed
+ * to the browser rather than rendered.
+ */
+export const MessageAttachments = ({
+	messageId,
+	bodyParts,
+	hasAttachment = false,
+	className,
+}: MessageAttachmentsProps) => {
+	const { getToken } = useAuthProvider();
+	const queryClient = useQueryClient();
+	const [downloads, setDownloads] = useState<
+		Record<string, AttachmentDownloadState>
+	>({});
+
+	const attachments = useMemo(
+		() => selectMessageAttachments(bodyParts ?? []),
+		[bodyParts],
+	);
+
+	const describeKey = messageOperationsDescribeMessageQueryKey({
+		path: { messageId },
+	});
+
+	/**
+	 * A stale signature and an unmaterialized part are both repaired by re-reading
+	 * the message: `describeMessage` re-signs every `contentUrl`, and it
+	 * materializes the deferred per-part objects on its way through. Re-hitting
+	 * the same URL alone cannot fix either (remit-mail/remit#1240), so the retry
+	 * goes through the read path and then uses the URL it just minted.
+	 */
+	const fetchThroughRefreshedDescribe = (
+		attachment: MessageAttachment,
+	): Promise<Blob> =>
+		fetchAttachment(attachment.contentUrl, getToken).catch(
+			(error: unknown): Promise<Blob> => {
+				if (!isRepairableByRefetch(extractAttachmentFailureReason(error))) {
+					throw error;
+				}
+				return queryClient
+					.refetchQueries({ queryKey: describeKey })
+					.then(() => {
+						const refreshed =
+							queryClient.getQueryData<RemitImapDescribeMessageResponse>(
+								describeKey,
+							);
+						const renewed = refreshed
+							? selectMessageAttachments(refreshed.bodyParts).find(
+									(candidate) => candidate.bodyPartId === attachment.bodyPartId,
+								)
+							: undefined;
+						return fetchAttachment(
+							renewed?.contentUrl ?? attachment.contentUrl,
+							getToken,
+						);
+					});
+			},
+		);
+
+	const setState = (id: string, state: AttachmentDownloadState) =>
+		setDownloads((current) => ({ ...current, [id]: state }));
+
+	const download = (bodyPartId: string) => {
+		const attachment = attachments.find(
+			(candidate) => candidate.bodyPartId === bodyPartId,
+		);
+		if (!attachment) {
+			throw new Error(
+				`No attachment part ${bodyPartId} on message ${messageId}`,
+			);
+		}
+
+		setState(bodyPartId, { status: "downloading" });
+		fetchThroughRefreshedDescribe(attachment)
+			.then((blob) => {
+				saveBlob(blob, attachment.filename);
+				setState(bodyPartId, IDLE);
+			})
+			.catch((error: unknown) => {
+				const reason = extractAttachmentFailureReason(error);
+				const fallback = extractAttachmentFailureDetail(error);
+				const { title, detail } = attachmentFailureContent(
+					reason,
+					attachment.filename,
+					fallback,
+				);
+				setState(bodyPartId, {
+					status: "failed",
+					title,
+					detail,
+					reportUrl: attachmentReportUrl(reason, attachment.filename, fallback),
+				});
+			});
+	};
+
+	// Only claim an attachment is unaccounted for once the parts have arrived;
+	// while `describeMessage` is in flight there is nothing to contradict.
+	const hasUnlistedAttachment =
+		hasAttachment && bodyParts !== undefined && attachments.length === 0;
+
+	return (
+		<AttachmentList
+			className={className}
+			attachments={attachments.map((attachment) => ({
+				attachmentId: attachment.bodyPartId,
+				filename: attachment.filename,
+				typeLabel: attachment.typeLabel,
+				sizeOctets: attachment.sizeOctets,
+				download: downloads[attachment.bodyPartId] ?? IDLE,
+			}))}
+			onDownload={download}
+			hasUnlistedAttachment={hasUnlistedAttachment}
+		/>
+	);
+};

package/src/components/mail/MessageCard.tsx

@@ -16,6 +16,7 @@ import { formatDatePreset } from "@/lib/format";
 import { cn } from "@/lib/utils";
 import { AutoMovedIndicator } from "./AutoMovedIndicator";
 import { MessageActionMenu } from "./MessageActionMenu";
+import { MessageAttachments } from "./MessageAttachments";
 import { MessageBody } from "./MessageBody";
 import { MobileMessageBar } from "./MobileMessageBar";
 import { RawMessageView } from "./RawMessageView";
@@ -134,7 +135,11 @@ const CollapsedCard = ({
 			trailing={
 				<>
 					{threadMessage.hasAttachment && (
-						<Paperclip className="size-3 shrink-0 text-fg-subtle" />
+						<Paperclip
+							className="size-3 shrink-0 text-fg-subtle"
+							role="img"
+							aria-label="Has an attachment"
+						/>
 					)}
 					<StarButton
 						isStarred={threadMessage.hasStars}
@@ -238,11 +243,6 @@ const ExpandedCard = ({
 										onToggleStar={onToggleStar}
 										isStarPending={isStarPending}
 									/>
-									{threadMessage.hasAttachment && (
-										<span className="text-fg-subtle p-0.5">
-											<Paperclip className="size-3.5" />
-										</span>
-									)}
 								</div>
 								{isUnread && (
 									// biome-ignore lint/a11y/useAriaPropsSupportedByRole: aria-label on decorative indicator provides useful context for assistive tech
@@ -324,6 +324,15 @@ const ExpandedCard = ({
 							isTrusted={isTrusted}
 							category={toDisplayCategory(threadMessage.category)}
 						/>
+						{/* The body slot runs edge to edge on a phone; the attachment
+						    list is app chrome, not part of the email, so it takes the
+						    gutter back. */}
+						<MessageAttachments
+							messageId={threadMessage.messageId}
+							bodyParts={messageData?.bodyParts}
+							hasAttachment={threadMessage.hasAttachment}
+							className="mt-4 px-2 lg:px-0"
+						/>
 					</div>
 				)
 			}

package/src/lib/attachment-download.test.ts

@@ -0,0 +1,207 @@
+import assert from "node:assert/strict";
+import { afterEach, describe, it } from "node:test";
+import {
+	AttachmentFetchError,
+	attachmentFailureContent,
+	attachmentReportUrl,
+	classifyAttachmentFailure,
+	extractAttachmentFailureDetail,
+	extractAttachmentFailureReason,
+	fetchAttachment,
+	isRepairableByRefetch,
+	saveBlob,
+} from "./attachment-download";
+
+const originalFetch = globalThis.fetch;
+
+const respondWith = (
+	init: {
+		status: number;
+		statusText?: string;
+		headers?: Record<string, string>;
+	},
+	body: string = "bytes",
+) => {
+	globalThis.fetch = (async () =>
+		new Response(init.status === 204 ? null : body, {
+			status: init.status,
+			statusText: init.statusText ?? "",
+			headers: init.headers,
+		})) as typeof fetch;
+};
+
+afterEach(() => {
+	globalThis.fetch = originalFetch;
+});
+
+describe("classifyAttachmentFailure", () => {
+	it("reads an edge denial as an expired session", () => {
+		assert.equal(classifyAttachmentFailure(401, null), "auth");
+		assert.equal(classifyAttachmentFailure(403, "tenant-mismatch"), "auth");
+	});
+
+	it("reads an origin 403/404 as a missing object", () => {
+		assert.equal(classifyAttachmentFailure(403, null), "missing");
+		assert.equal(classifyAttachmentFailure(404, null), "missing");
+	});
+
+	// A stale signature is not a stale session — telling the user to sign in
+	// again would send them somewhere that cannot help.
+	it("separates an aged-out content signature from an expired session", () => {
+		assert.equal(classifyAttachmentFailure(403, "expired"), "link-expired");
+		assert.equal(isRepairableByRefetch("link-expired"), true);
+		assert.equal(isRepairableByRefetch("not-ready"), true);
+		assert.equal(isRepairableByRefetch("auth"), false);
+		assert.equal(isRepairableByRefetch("missing"), false);
+	});
+
+	it("reads anything else as generic", () => {
+		assert.equal(classifyAttachmentFailure(500, null), "generic");
+	});
+});
+
+describe("fetchAttachment", () => {
+	it("returns the bytes on a 200", async () => {
+		respondWith({ status: 200 }, "payload");
+		const blob = await fetchAttachment("https://cdn.test/x", async () => null);
+		assert.equal(await blob.text(), "payload");
+	});
+
+	it("sends the session token when there is one", async () => {
+		let seen: string | null = null;
+		globalThis.fetch = (async (_url: string, init?: RequestInit) => {
+			seen = new Headers(init?.headers).get("Authorization") ?? null;
+			return new Response("payload", { status: 200 });
+		}) as unknown as typeof fetch;
+		await fetchAttachment("https://cdn.test/x", async () => "tok");
+		assert.equal(seen, "Bearer tok");
+	});
+
+	it("treats a 202 as not-ready rather than as an empty file", async () => {
+		respondWith({ status: 202 });
+		await assert.rejects(
+			fetchAttachment("https://cdn.test/x", async () => null),
+			(error: unknown) =>
+				error instanceof AttachmentFetchError && error.reason === "not-ready",
+		);
+	});
+
+	it("throws with the classified reason on a failure status", async () => {
+		respondWith({ status: 404, statusText: "Not Found" });
+		await assert.rejects(
+			fetchAttachment("https://cdn.test/x", async () => null),
+			(error: unknown) =>
+				error instanceof AttachmentFetchError &&
+				error.reason === "missing" &&
+				error.status === 404,
+		);
+	});
+});
+
+describe("attachmentFailureContent", () => {
+	it("tells an expired session what to do, and names the file", () => {
+		const content = attachmentFailureContent(
+			"auth",
+			"report.pdf",
+			"irrelevant",
+		);
+		assert.match(content.title, /session expired/i);
+		assert.match(content.detail, /report\.pdf/);
+	});
+
+	it("distinguishes a missing object from a slow one", () => {
+		assert.notEqual(
+			attachmentFailureContent("missing", "x", "f").title,
+			attachmentFailureContent("not-ready", "x", "f").title,
+		);
+	});
+
+	it("surfaces the underlying error for an unclassified failure", () => {
+		const content = attachmentFailureContent(
+			"generic",
+			"x",
+			"Failed to download attachment (500 )",
+		);
+		assert.equal(content.detail, "Failed to download attachment (500 )");
+	});
+});
+
+describe("failure extraction", () => {
+	it("reads the reason off an AttachmentFetchError", () => {
+		assert.equal(
+			extractAttachmentFailureReason(
+				new AttachmentFetchError("missing", "gone", 404),
+			),
+			"missing",
+		);
+	});
+
+	it("treats an unrecognised throw as generic", () => {
+		assert.equal(extractAttachmentFailureReason("boom"), "generic");
+		assert.equal(extractAttachmentFailureDetail("boom"), "boom");
+		assert.equal(
+			extractAttachmentFailureDetail(new Error("transport lost")),
+			"transport lost",
+		);
+		assert.match(extractAttachmentFailureDetail({}), /unexpected error/);
+	});
+});
+
+describe("attachmentReportUrl", () => {
+	it("offers a prefilled issue for a failure the user cannot fix", () => {
+		const url = attachmentReportUrl("missing", "report.pdf", "gone");
+		assert.ok(url, "a reportable failure must carry an issue URL");
+		assert.ok(
+			url.startsWith("https://github.com/remit-mail/reader/issues/new?"),
+		);
+		assert.match(decodeURIComponent(url), /report\.pdf/);
+	});
+
+	it("offers none for an expired session, which is not a bug", () => {
+		assert.equal(
+			attachmentReportUrl("auth", "report.pdf", "denied"),
+			undefined,
+		);
+	});
+});
+
+describe("saveBlob", () => {
+	it("saves under the name it was given and cleans up the anchor", async () => {
+		const created: string[] = [];
+		const revoked: string[] = [];
+		const url = globalThis.URL as unknown as {
+			createObjectURL?: (blob: Blob) => string;
+			revokeObjectURL?: (value: string) => void;
+		};
+		url.createObjectURL = () => {
+			created.push("blob:test");
+			return "blob:test";
+		};
+		url.revokeObjectURL = (value) => revoked.push(value);
+
+		let clickedName: string | null = null;
+		const anchor = document.createElement("a");
+		anchor.click = () => {
+			clickedName = anchor.download;
+		};
+		const originalCreateElement = document.createElement.bind(document);
+		document.createElement = ((tag: string) =>
+			tag === "a"
+				? anchor
+				: originalCreateElement(tag)) as typeof document.createElement;
+
+		try {
+			saveBlob(new Blob(["x"]), "report.pdf");
+		} finally {
+			document.createElement = originalCreateElement;
+		}
+
+		assert.equal(clickedName, "report.pdf");
+		assert.deepEqual(created, ["blob:test"]);
+		assert.equal(document.body.contains(anchor), false);
+		assert.deepEqual(revoked, [], "revoking in the click's task cancels it");
+
+		await new Promise((resolve) => setTimeout(resolve, 5));
+		assert.deepEqual(revoked, ["blob:test"]);
+	});
+});

package/src/lib/attachment-download.ts

@@ -0,0 +1,195 @@
+import { classifyBodyFetchFailure } from "@/hooks/useMessageBodyContent";
+import { buildBugReportContext, buildGitHubIssueUrl } from "./bug-report";
+import { taggedFetch } from "./network-error";
+
+/**
+ * Why an attachment download failed. Same edge/origin discrimination the body
+ * fetch performs (`classifyBodyFetchFailure`) — the bytes travel the same
+ * `/content/*` route — narrowed to the outcomes a download can act on.
+ *
+ * - `auth` — the edge denied the request; the session has to be renewed.
+ * - `link-expired` — the self-host signature on the URL aged out (1 hour, and
+ *   `describeMessage` is cached for 30 minutes, so an open message outlives it).
+ *   Fixed by re-reading the message, which mints a fresh signature.
+ * - `missing` — the request passed auth and storage had no object at the key.
+ * - `not-ready` — 202: the part has not been stored yet and a cue was re-armed.
+ * - `generic` — anything else, including a transport failure.
+ */
+export type AttachmentFetchReason =
+	| "auth"
+	| "link-expired"
+	| "missing"
+	| "not-ready"
+	| "generic";
+
+/**
+ * The failures a fresh `describeMessage` read repairs on its own: it re-signs
+ * every `contentUrl`, and materializing the deferred per-part objects is a side
+ * effect of that same read.
+ */
+export const isRepairableByRefetch = (reason: AttachmentFetchReason): boolean =>
+	reason === "link-expired" || reason === "not-ready";
+
+export class AttachmentFetchError extends Error {
+	readonly reason: AttachmentFetchReason;
+	readonly status?: number;
+
+	constructor(reason: AttachmentFetchReason, message: string, status?: number) {
+		super(message);
+		this.name = "AttachmentFetchError";
+		this.reason = reason;
+		this.status = status;
+	}
+}
+
+const REASON_HEADER = "x-remit-403-reason";
+
+/** The `verifyContentSignature` failure the self-host `/content` route reports. */
+const EXPIRED_SIGNATURE_REASON = "expired";
+
+export const classifyAttachmentFailure = (
+	status: number,
+	reasonHeader: string | null,
+): AttachmentFetchReason => {
+	if (reasonHeader?.trim() === EXPIRED_SIGNATURE_REASON) return "link-expired";
+	const bodyReason = classifyBodyFetchFailure(status, reasonHeader);
+	if (bodyReason === "auth") return "auth";
+	if (bodyReason === "body-missing") return "missing";
+	return "generic";
+};
+
+/**
+ * Fetch one attachment's bytes from its `contentUrl`.
+ *
+ * The self-host stack authorizes `/content/*` with the signature already in the
+ * URL; AWS authorizes it with the session bearer token at the edge. Sending the
+ * token when there is one covers both, and matches `fetchBodyContent`.
+ *
+ * Throws on anything that is not a 200 so the caller renders the failure. A
+ * download that silently produces no file is the bug this whole change exists
+ * to remove — including the silence of a transfer that stalls, which the
+ * timeout converts into a stated failure.
+ */
+export const ATTACHMENT_FETCH_TIMEOUT_MS = 5 * 60 * 1000;
+
+export const fetchAttachment = async (
+	url: string,
+	getToken: () => Promise<string | null>,
+): Promise<Blob> => {
+	const headers: Record<string, string> = {};
+	const token = await getToken();
+	if (token) headers.Authorization = `Bearer ${token}`;
+
+	const response = await taggedFetch(url, {
+		headers,
+		signal: AbortSignal.timeout(ATTACHMENT_FETCH_TIMEOUT_MS),
+	});
+	if (response.status === 202) {
+		throw new AttachmentFetchError(
+			"not-ready",
+			"Attachment is still being fetched from the mail server",
+			202,
+		);
+	}
+	if (!response.ok) {
+		throw new AttachmentFetchError(
+			classifyAttachmentFailure(
+				response.status,
+				response.headers.get(REASON_HEADER),
+			),
+			`Failed to download attachment (${response.status} ${response.statusText})`,
+			response.status,
+		);
+	}
+	return response.blob();
+};
+
+export interface AttachmentFailureContent {
+	title: string;
+	detail: string;
+}
+
+export const attachmentFailureContent = (
+	reason: AttachmentFetchReason,
+	filename: string,
+	fallback: string,
+): AttachmentFailureContent => {
+	switch (reason) {
+		case "auth":
+			return {
+				title: "Your session expired",
+				detail: `Sign in again, then download ${filename} once more. Other parts of the app may also stop responding until you do.`,
+			};
+		case "link-expired":
+			return {
+				title: "This download link expired and could not be renewed",
+				detail: `Reload the page, then download ${filename} again. If that keeps failing, this is worth reporting.`,
+			};
+		case "missing":
+			return {
+				title: "This attachment is missing from storage",
+				detail:
+					"Remit has the message but not the file. Re-sync the account from Settings, then try again.",
+			};
+		case "not-ready":
+			return {
+				title: "Still fetching this attachment",
+				detail:
+					"Remit is downloading it from the mail server now. Try again in a few seconds.",
+			};
+		default:
+			return { title: "Couldn't download this attachment", detail: fallback };
+	}
+};
+
+export const extractAttachmentFailureReason = (
+	error: unknown,
+): AttachmentFetchReason =>
+	error instanceof AttachmentFetchError ? error.reason : "generic";
+
+export const extractAttachmentFailureDetail = (error: unknown): string => {
+	if (error instanceof Error) return error.message;
+	if (typeof error === "string") return error;
+	return "An unexpected error occurred while downloading this attachment.";
+};
+
+/**
+ * A prefilled issue URL for a download failure, so the user has somewhere to go
+ * that is not "try again forever". Not offered for an expired session, which is
+ * the user's to fix and not a bug.
+ */
+export const attachmentReportUrl = (
+	reason: AttachmentFetchReason,
+	filename: string,
+	detail: string,
+): string | undefined => {
+	if (reason === "auth") return undefined;
+	return buildGitHubIssueUrl(
+		buildBugReportContext({
+			title: `Bug: attachment download failed (${reason})`,
+			errorMessage: `Downloading "${filename}" failed: ${detail}`,
+		}),
+	);
+};
+
+/**
+ * Hand the fetched bytes to the browser's download machinery under the
+ * sanitized name.
+ *
+ * A plain `<a href={contentUrl} download>` cannot do this job: on AWS the
+ * content URL is a different origin, where the `download` attribute is ignored
+ * and the browser navigates instead. The object URL is same-origin, so the
+ * attribute holds and the filename we chose is the filename that lands.
+ */
+export const saveBlob = (blob: Blob, filename: string): void => {
+	const objectUrl = URL.createObjectURL(blob);
+	const anchor = document.createElement("a");
+	anchor.href = objectUrl;
+	anchor.download = filename;
+	anchor.rel = "noopener";
+	document.body.append(anchor);
+	anchor.click();
+	anchor.remove();
+	// Revoking in the same task as the click cancels the download in WebKit.
+	setTimeout(() => URL.revokeObjectURL(objectUrl), 0);
+};

package/src/lib/message-attachments.test.ts

@@ -0,0 +1,86 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { RemitImapBodyPartResponse } from "@remit/api-http-client/types.gen.ts";
+import { selectMessageAttachments } from "./message-attachments";
+
+const part = (
+	overrides: Partial<RemitImapBodyPartResponse>,
+): RemitImapBodyPartResponse =>
+	({
+		bodyPartId: "part-1",
+		mediaType: "APPLICATION",
+		mediaSubtype: "PDF",
+		sizeOctets: 2048,
+		disposition: "attachment",
+		dispositionFilename: "report.pdf",
+		contentUrl: "https://cdn.test/content/parts/2",
+		isMultipart: false,
+		...overrides,
+	}) as RemitImapBodyPartResponse;
+
+describe("selectMessageAttachments", () => {
+	it("keeps only attachment-disposition leaves", () => {
+		const parts = [
+			part({ bodyPartId: "body", disposition: "inline", mediaSubtype: "HTML" }),
+			part({ bodyPartId: "container", isMultipart: true }),
+			part({ bodyPartId: "file" }),
+		];
+		assert.deepEqual(
+			selectMessageAttachments(parts).map((a) => a.bodyPartId),
+			["file"],
+		);
+	});
+
+	it("drops a part with no content URL to fetch", () => {
+		assert.deepEqual(selectMessageAttachments([part({ contentUrl: "" })]), []);
+	});
+
+	it("preserves the order the message declares", () => {
+		const parts = [
+			part({ bodyPartId: "a", dispositionFilename: "a.pdf" }),
+			part({ bodyPartId: "b", dispositionFilename: "b.pdf" }),
+		];
+		assert.deepEqual(
+			selectMessageAttachments(parts).map((a) => a.filename),
+			["a.pdf", "b.pdf"],
+		);
+	});
+
+	it("carries filename, size and content URL through", () => {
+		const [attachment] = selectMessageAttachments([
+			part({ sizeOctets: 4096, contentUrl: "https://cdn.test/x" }),
+		]);
+		assert.equal(attachment.filename, "report.pdf");
+		assert.equal(attachment.typeLabel, "PDF");
+		assert.equal(attachment.sizeOctets, 4096);
+		assert.equal(attachment.contentUrl, "https://cdn.test/x");
+	});
+
+	it("sanitizes a filename that tries to escape the download directory", () => {
+		const [attachment] = selectMessageAttachments([
+			part({ dispositionFilename: "../../../etc/passwd" }),
+		]);
+		assert.equal(attachment.filename, "passwd");
+	});
+
+	it("names an unnamed attachment after its subtype", () => {
+		const [attachment] = selectMessageAttachments([
+			part({ dispositionFilename: undefined }),
+		]);
+		assert.equal(attachment.filename, "attachment.pdf");
+	});
+
+	it("falls back to a bare name when the subtype yields no extension", () => {
+		const [attachment] = selectMessageAttachments([
+			part({ dispositionFilename: undefined, mediaSubtype: "-" }),
+		]);
+		assert.equal(attachment.filename, "attachment");
+	});
+
+	it("labels an undifferentiated binary as a file rather than as its subtype", () => {
+		const [attachment] = selectMessageAttachments([
+			part({ mediaSubtype: "OCTET-STREAM" }),
+		]);
+		assert.equal(attachment.typeLabel, "FILE");
+	});
+});

package/src/lib/message-attachments.ts

@@ -0,0 +1,54 @@
+import type { RemitImapBodyPartResponse } from "@remit/api-http-client/types.gen.ts";
+import { ContentDisposition } from "@remit/domain-enums";
+import { sanitizeAttachmentFilename } from "@remit/ui";
+
+/**
+ * The attachment-disposition body parts of a message, in the order the message
+ * declares them. `pickRenderablePart` (message-body-source.ts) drops exactly
+ * these parts so the renderer never treats a PDF as a body; this is the other
+ * half of that split.
+ */
+export interface MessageAttachment {
+	bodyPartId: string;
+	/** Display and save name — sanitized once, used for both. */
+	filename: string;
+	typeLabel: string;
+	sizeOctets: number;
+	contentUrl: string;
+}
+
+const typeLabelFor = (mediaSubtype: string): string => {
+	const label = mediaSubtype.toUpperCase();
+	return label === "OCTET-STREAM" ? "FILE" : label;
+};
+
+/**
+ * `application/pdf` → `attachment.pdf`. Only used when the sender declared no
+ * filename; a subtype with nothing alphanumeric in it yields a bare
+ * `attachment`.
+ */
+const fallbackFilenameFor = (mediaSubtype: string): string => {
+	const extension = mediaSubtype.toLowerCase().replace(/[^a-z0-9]/g, "");
+	return extension.length > 0 ? `attachment.${extension}` : "attachment";
+};
+
+export const selectMessageAttachments = (
+	parts: readonly RemitImapBodyPartResponse[],
+): MessageAttachment[] =>
+	parts
+		.filter(
+			(part) =>
+				!part.isMultipart &&
+				part.disposition === ContentDisposition.Attachment &&
+				part.contentUrl.length > 0,
+		)
+		.map((part) => ({
+			bodyPartId: part.bodyPartId,
+			filename: sanitizeAttachmentFilename(
+				part.dispositionFilename ?? "",
+				fallbackFilenameFor(part.mediaSubtype),
+			),
+			typeLabel: typeLabelFor(part.mediaSubtype),
+			sizeOctets: part.sizeOctets,
+			contentUrl: part.contentUrl,
+		}));