@remit/web-client 0.0.134 → 0.0.136

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