@remit/web-client 0.0.135 → 0.0.137

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,
+		}));