@remit/ui 0.0.98 → 0.0.100

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/ui",
-  "version": "0.0.98",
+  "version": "0.0.100",
   "type": "module",
   "files": [
     "src"

package/src/components/attachment-list.render.test.ts

@@ -0,0 +1,120 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { createElement } from "react";
+import { renderToString } from "react-dom/server";
+import { AttachmentList, type AttachmentListProps } from "./attachment-list.js";
+
+const render = (props: AttachmentListProps): string =>
+	renderToString(createElement(AttachmentList, props));
+
+const item = (
+	overrides: Partial<AttachmentListProps["attachments"][number]>,
+) => ({
+	attachmentId: "part-1",
+	filename: "Quarterly report.pdf",
+	typeLabel: "PDF",
+	sizeOctets: 1024 * 512,
+	download: { status: "idle" } as const,
+	...overrides,
+});
+
+describe("AttachmentList", () => {
+	it("renders nothing when the message has no attachments", () => {
+		assert.equal(render({ attachments: [], onDownload: () => undefined }), "");
+	});
+
+	it("names the file, its type and its size", () => {
+		const html = render({
+			attachments: [item({})],
+			onDownload: () => undefined,
+		});
+		assert.match(html, /Quarterly report\.pdf/);
+		assert.match(html, /PDF/);
+		assert.match(html, /512 KB/);
+	});
+
+	it("gives every attachment a labelled download control", () => {
+		const html = render({
+			attachments: [
+				item({}),
+				item({ attachmentId: "part-2", filename: "photo.png" }),
+			],
+			onDownload: () => undefined,
+		});
+		assert.match(html, /aria-label="Download Quarterly report\.pdf"/);
+		assert.match(html, /aria-label="Download photo\.png"/);
+		assert.match(html, /2 attachments/);
+	});
+
+	it("counts a single attachment in the singular", () => {
+		const html = render({
+			attachments: [item({})],
+			onDownload: () => undefined,
+		});
+		assert.match(html, /1 attachment</);
+	});
+
+	it("isolates the filename's text direction", () => {
+		const html = render({
+			attachments: [item({})],
+			onDownload: () => undefined,
+		});
+		assert.match(html, /<bdi/);
+	});
+
+	it("disables the control while a download is in flight", () => {
+		const html = render({
+			attachments: [item({ download: { status: "downloading" } })],
+			onDownload: () => undefined,
+		});
+		assert.match(html, /disabled=""/);
+	});
+
+	it("states what failed, the likely fix, and offers a retry", () => {
+		const html = render({
+			attachments: [
+				item({
+					download: {
+						status: "failed",
+						title: "Your session expired",
+						detail: "Sign in again, then download it once more.",
+					},
+				}),
+			],
+			onDownload: () => undefined,
+		});
+		assert.match(html, /role="alert"/);
+		assert.match(html, /Your session expired/);
+		assert.match(html, /Sign in again, then download it once more\./);
+		assert.match(html, /Try again/);
+	});
+
+	it("offers a report link when the failure came with one", () => {
+		const html = render({
+			attachments: [
+				item({
+					download: {
+						status: "failed",
+						title: "Couldn't download this attachment",
+						detail: "The server refused the request.",
+						reportUrl:
+							"https://github.com/remit-mail/reader/issues/new?title=x",
+					},
+				}),
+			],
+			onDownload: () => undefined,
+		});
+		assert.match(html, /Report this/);
+		assert.match(html, /issues\/new\?title=x/);
+	});
+
+	it("says so when the server promised an attachment no part describes", () => {
+		const html = render({
+			attachments: [],
+			onDownload: () => undefined,
+			hasUnlistedAttachment: true,
+		});
+		assert.match(html, /carries an attachment, but none of/);
+		assert.match(html, /Attachment</);
+	});
+});

package/src/components/attachment-list.stories.tsx

@@ -0,0 +1,159 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { type AttachmentItem, AttachmentList } from "./attachment-list.js";
+
+/**
+ * The attachment list on an open message (#683). Every row saves a file, so
+ * every row is a button; the paperclip in the heading is the only glyph and it
+ * is decoration. Nothing here fetches — the app owns the download and hands
+ * back per-row state, which is what makes the failure story below the same
+ * component the app renders.
+ */
+const meta: Meta<typeof AttachmentList> = {
+	title: "Mail/AttachmentList",
+	component: AttachmentList,
+	parameters: { layout: "padded" },
+};
+export default meta;
+
+type Story = StoryObj<typeof AttachmentList>;
+
+const report: AttachmentItem = {
+	attachmentId: "part-2",
+	filename: "Q3 board pack.pdf",
+	typeLabel: "PDF",
+	sizeOctets: 2_411_724,
+	download: { status: "idle" },
+};
+
+export const OneAttachment: Story = {
+	args: {
+		attachments: [report],
+		onDownload: (id) => alert(`Download ${id}`),
+	},
+};
+
+export const SeveralAttachments: Story = {
+	args: {
+		attachments: [
+			report,
+			{
+				attachmentId: "part-3",
+				filename: "site-plan.png",
+				typeLabel: "PNG",
+				sizeOctets: 486_120,
+				download: { status: "idle" },
+			},
+			{
+				attachmentId: "part-4",
+				filename: "notes.txt",
+				typeLabel: "PLAIN",
+				sizeOctets: 812,
+				download: { status: "idle" },
+			},
+			{
+				attachmentId: "part-5",
+				filename: "archive",
+				typeLabel: "FILE",
+				sizeOctets: 1024 ** 3 + 1024 ** 2 * 200,
+				download: { status: "idle" },
+			},
+		],
+		onDownload: (id) => alert(`Download ${id}`),
+	},
+};
+
+export const Downloading: Story = {
+	args: {
+		attachments: [
+			{ ...report, download: { status: "downloading" } },
+			{
+				attachmentId: "part-3",
+				filename: "site-plan.png",
+				typeLabel: "PNG",
+				sizeOctets: 486_120,
+				download: { status: "idle" },
+			},
+		],
+		onDownload: (id) => alert(`Download ${id}`),
+	},
+};
+
+/**
+ * A fetch that failed. The row keeps its control, and the alert underneath
+ * names what broke and what to do about it — a dead click that leaves the user
+ * guessing whether the app, the server or they themselves are at fault is the
+ * outcome this list exists to make impossible.
+ */
+export const DownloadFailed: Story = {
+	args: {
+		attachments: [
+			{
+				...report,
+				download: {
+					status: "failed",
+					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.",
+					reportUrl: "https://github.com/remit-mail/reader/issues/new",
+				},
+			},
+			{
+				attachmentId: "part-3",
+				filename: "site-plan.png",
+				typeLabel: "PNG",
+				sizeOctets: 486_120,
+				download: { status: "idle" },
+			},
+		],
+		onDownload: (id) => alert(`Download ${id}`),
+	},
+};
+
+/**
+ * Names written to deceive, as `sanitizeAttachmentFilename` leaves them. The
+ * senders wrote `../../../etc/passwd`, `invoice<RLO>gnp.exe` — which renders as
+ * `invoiceexe.png` with the override intact — and 400 characters of padding.
+ * The list shows exactly the name the file is saved under, so what is read is
+ * what lands.
+ */
+export const HostileFilename: Story = {
+	args: {
+		attachments: [
+			{
+				attachmentId: "part-6",
+				filename: "passwd",
+				typeLabel: "FILE",
+				sizeOctets: 3_120,
+				download: { status: "idle" },
+			},
+			{
+				attachmentId: "part-7",
+				filename: "invoicegnp.exe",
+				typeLabel: "FILE",
+				sizeOctets: 118_400,
+				download: { status: "idle" },
+			},
+			{
+				attachmentId: "part-8",
+				filename: `${"long-name-".repeat(11)}report.pdf`,
+				typeLabel: "PDF",
+				sizeOctets: 44_000,
+				download: { status: "idle" },
+			},
+		],
+		onDownload: (id) => alert(`Download ${id}`),
+	},
+};
+
+/**
+ * The mail server flagged the message as carrying an attachment, but no body
+ * part describes one. Saying nothing here is what made the original paperclip
+ * read as broken.
+ */
+export const UnlistedAttachment: Story = {
+	args: {
+		attachments: [],
+		onDownload: () => undefined,
+		hasUnlistedAttachment: true,
+	},
+};

package/src/components/attachment-list.tsx

@@ -0,0 +1,182 @@
+import { AlertCircle, Download, Loader2, Paperclip } from "lucide-react";
+import { formatByteSize } from "../lib/attachment-file.js";
+import { cn } from "../lib/cn.js";
+
+export type AttachmentDownloadState =
+	| { status: "idle" }
+	| { status: "downloading" }
+	| { status: "failed"; title: string; detail: string; reportUrl?: string };
+
+export interface AttachmentItem {
+	attachmentId: string;
+	/**
+	 * The name shown and the name saved — one string for both, already reduced
+	 * by `sanitizeAttachmentFilename`. Anything that displays a different name
+	 * than it writes to disk is the bug this field exists to prevent.
+	 */
+	filename: string;
+	/** Short type label derived from the MIME subtype, e.g. `PDF`. */
+	typeLabel: string;
+	sizeOctets: number;
+	download: AttachmentDownloadState;
+}
+
+export interface AttachmentListProps {
+	attachments: readonly AttachmentItem[];
+	onDownload: (attachmentId: string) => void;
+	/**
+	 * The message is flagged on the server as carrying an attachment that none
+	 * of its body parts describe. Says so rather than rendering nothing, which
+	 * is indistinguishable from a broken app to someone who saw the paperclip
+	 * in the list.
+	 */
+	hasUnlistedAttachment?: boolean;
+	className?: string;
+}
+
+function DownloadFailure({
+	state,
+	onRetry,
+}: {
+	state: Extract<AttachmentDownloadState, { status: "failed" }>;
+	onRetry: () => void;
+}) {
+	return (
+		<div
+			role="alert"
+			data-testid="attachment-error"
+			className="flex items-start gap-2 border-t border-danger/30 bg-danger-soft px-2 py-2 text-xs"
+		>
+			<AlertCircle
+				className="mt-0.5 size-3.5 shrink-0 text-danger"
+				aria-hidden
+			/>
+			<div className="min-w-0 flex-1">
+				<p className="font-medium text-danger">{state.title}</p>
+				<p className="mt-0.5 text-fg-muted">{state.detail}</p>
+			</div>
+			<div className="flex shrink-0 items-center gap-3">
+				<button
+					type="button"
+					onClick={onRetry}
+					className="font-medium text-accent hover:underline"
+				>
+					Try again
+				</button>
+				{state.reportUrl && (
+					<a
+						href={state.reportUrl}
+						target="_blank"
+						rel="noreferrer"
+						className="font-medium text-accent hover:underline"
+					>
+						Report this
+					</a>
+				)}
+			</div>
+		</div>
+	);
+}
+
+/**
+ * The attachments carried by an open message: what each one is, how big it is,
+ * and a control that saves it.
+ *
+ * Every row is a real button. The paperclip in the section heading is the only
+ * glyph here and it is labelled as decoration — a paperclip that looks
+ * pressable and is not reads as a broken download, which is the failure this
+ * list replaces (#683).
+ */
+export function AttachmentList({
+	attachments,
+	onDownload,
+	hasUnlistedAttachment = false,
+	className,
+}: AttachmentListProps) {
+	if (attachments.length === 0 && !hasUnlistedAttachment) return null;
+
+	return (
+		<section
+			aria-label="Attachments"
+			data-testid="attachment-list"
+			className={cn("space-y-1.5", className)}
+		>
+			<h3 className="flex items-center gap-1.5 text-2xs font-semibold uppercase tracking-wider text-fg-subtle">
+				<Paperclip className="size-3" aria-hidden />
+				{attachments.length === 0
+					? "Attachment"
+					: attachments.length === 1
+						? "1 attachment"
+						: `${attachments.length} attachments`}
+			</h3>
+
+			{attachments.length > 0 && (
+				<ul className="overflow-hidden rounded-sm border border-line bg-surface">
+					{attachments.map((attachment) => {
+						const isDownloading = attachment.download.status === "downloading";
+						return (
+							<li
+								key={attachment.attachmentId}
+								className="border-t border-line first:border-t-0"
+							>
+								<button
+									type="button"
+									onClick={() => onDownload(attachment.attachmentId)}
+									disabled={isDownloading}
+									data-testid="attachment-download"
+									aria-label={`Download ${attachment.filename}`}
+									className="flex w-full items-center gap-2 px-2 py-2 text-left transition-colors hover:bg-surface-sunken disabled:cursor-progress disabled:opacity-60"
+								>
+									<span className="min-w-0 flex-1">
+										{/* <bdi> isolates the name's own direction so a
+										    right-to-left filename cannot reorder the label
+										    around it. */}
+										<bdi
+											className="block truncate text-sm text-fg"
+											title={attachment.filename}
+										>
+											{attachment.filename}
+										</bdi>
+										<span className="block truncate text-2xs text-fg-subtle">
+											{attachment.typeLabel} ·{" "}
+											{formatByteSize(attachment.sizeOctets)}
+										</span>
+									</span>
+									{isDownloading ? (
+										<Loader2
+											className="size-4 shrink-0 animate-spin text-fg-subtle"
+											aria-hidden
+										/>
+									) : (
+										<Download
+											className="size-4 shrink-0 text-fg-subtle"
+											aria-hidden
+										/>
+									)}
+								</button>
+								{attachment.download.status === "failed" && (
+									<DownloadFailure
+										state={attachment.download}
+										onRetry={() => onDownload(attachment.attachmentId)}
+									/>
+								)}
+							</li>
+						);
+					})}
+				</ul>
+			)}
+
+			{hasUnlistedAttachment && (
+				<p
+					role="alert"
+					data-testid="attachment-unlisted"
+					className="rounded-sm border border-line bg-surface px-2 py-2 text-xs text-fg-muted"
+				>
+					The mail server says this message carries an attachment, but none of
+					its parts describe one. Re-sync the account from Settings; if the
+					attachment still does not appear, the message is worth reporting.
+				</p>
+			)}
+		</section>
+	);
+}

package/src/components/compose-action-bar.stories.tsx

@@ -23,7 +23,12 @@ export const Saving: Story = { args: { saveStatus: "saving" } };
 
 export const Saved: Story = { args: { saveStatus: "saved" } };
 
-export const Sending: Story = { args: { sending: true } };
+export const SaveFailed: Story = { args: { saveStatus: "error" } };
+
+export const Sending: Story = {
+	name: "Sending — also while the pending draft is written",
+	args: { sending: true },
+};
 
 export const CannotSend: Story = {
 	name: "Cannot send — stays pressable",

package/src/components/message-row.render.test.ts

@@ -138,3 +138,34 @@ describe("CompactRow", () => {
 		assert.match(html, /Q3 planning notes/);
 	});
 });
+
+describe("attachment indicator", () => {
+	// A list row cannot download anything — the file lives on the message, which
+	// is one pane over. So the paperclip here is metadata and says so, rather
+	// than sitting inertly where a control belongs (#683).
+	it("marks a comfortable row as carrying an attachment, without a control", () => {
+		const html = renderToString(
+			createElement(ComfortableRow, {
+				thread: { ...base, isRead: true, hasAttachment: true },
+			}),
+		);
+		assert.match(html, /role="img"/);
+		assert.match(html, /aria-label="Has an attachment"/);
+	});
+
+	it("marks a compact row as carrying an attachment", () => {
+		const html = renderToString(
+			createElement(CompactRow, {
+				thread: { ...base, isRead: true, hasAttachment: true },
+			}),
+		);
+		assert.match(html, /aria-label="Has an attachment"/);
+	});
+
+	it("renders no indicator when the message carries nothing", () => {
+		const html = renderToString(
+			createElement(ComfortableRow, { thread: { ...base, isRead: true } }),
+		);
+		assert.doesNotMatch(html, /Has an attachment/);
+	});
+});

package/src/components/message-row.tsx

@@ -98,7 +98,11 @@ export function CompactRowBody({ thread }: { thread: ThreadRowData }) {
 				<span className="text-fg-subtle"> — {thread.snippet}</span>
 			</span>
 			{thread.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"
+				/>
 			)}
 			<span className="w-11 shrink-0 text-right text-2xs text-fg-subtle tabular-nums">
 				{thread.timeLabel}
@@ -192,7 +196,11 @@ export function ComfortableRowTextContent({
 					<Star className="size-3 shrink-0 fill-warning text-warning" />
 				)}
 				{thread.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"
+					/>
 				)}
 			</span>
 			<span className="flex items-center gap-1.5">

package/src/components/reading-pane.stories.tsx

@@ -1,6 +1,8 @@
 import type { Meta, StoryObj } from "@storybook/react";
 import { Paperclip, Star } from "lucide-react";
 import type { ThreadData, ThreadMessageData } from "./app-shell-types.js";
+import { AttachmentList } from "./attachment-list.js";
+import { MessageBodyView } from "./message-body-view.js";
 import {
 	CollapsedMessage,
 	ExpandedMessage,
@@ -156,7 +158,11 @@ export const CollapsedRowComposed: StoryObj<typeof CollapsedMessage> = {
 						>
 							<Star className="size-3 fill-current" />
 						</button>
-						<Paperclip className="size-3 text-fg-subtle" />
+						<Paperclip
+							className="size-3 text-fg-subtle"
+							role="img"
+							aria-label="Has an attachment"
+						/>
 						<span className="text-2xs text-fg-subtle tabular-nums">
 							Today, 08:42
 						</span>
@@ -180,7 +186,6 @@ export const ExpandedRowComposed: StoryObj<typeof ExpandedMessage> = {
 				indicators={
 					<div className="mt-0.5 flex items-center gap-1">
 						<Star className="size-3.5 fill-current text-warning" />
-						<Paperclip className="size-3.5 text-fg-subtle" />
 					</div>
 				}
 				actionMenu={
@@ -192,3 +197,54 @@ export const ExpandedRowComposed: StoryObj<typeof ExpandedMessage> = {
 		</div>
 	),
 };
+
+/**
+ * The expanded row as `MessageCard` composes it when the message carries files
+ * (#683): body first, attachment list under it. The indicators row holds no
+ * paperclip — the list below is the affordance, and a second paperclip beside
+ * the live star button only reads as a control that does nothing.
+ */
+export const ExpandedRowWithAttachments: StoryObj<typeof ExpandedMessage> = {
+	render: () => (
+		<div className="max-w-3xl border border-line">
+			<ExpandedMessage
+				message={row}
+				to={<>to Alex Rivera and 2 others</>}
+				indicators={
+					<div className="mt-0.5 flex items-center gap-1">
+						<Star className="size-3.5 fill-current text-warning" />
+					</div>
+				}
+				body={
+					<div className="mt-3">
+						<MessageBodyView
+							html={row.bodyHtml}
+							category="personal"
+							allowImages
+						/>
+						<AttachmentList
+							className="mt-4 px-2 lg:px-0"
+							attachments={[
+								{
+									attachmentId: "part-2",
+									filename: "Q3 board pack.pdf",
+									typeLabel: "PDF",
+									sizeOctets: 2_411_724,
+									download: { status: "idle" },
+								},
+								{
+									attachmentId: "part-3",
+									filename: "headcount.csv",
+									typeLabel: "CSV",
+									sizeOctets: 4_180,
+									download: { status: "idle" },
+								},
+							]}
+							onDownload={(id) => alert(`Download ${id}`)}
+						/>
+					</div>
+				}
+			/>
+		</div>
+	),
+};

package/src/index.ts

@@ -51,6 +51,12 @@ export {
 	useContainerWidth,
 } from "./components/app-shell-types.js";
 export { AppTopBar, type AppTopBarProps } from "./components/app-top-bar.js";
+export {
+	type AttachmentDownloadState,
+	type AttachmentItem,
+	AttachmentList,
+	type AttachmentListProps,
+} from "./components/attachment-list.js";
 export { AuthCard, type AuthCardProps } from "./components/auth-card.js";
 export {
 	AuthFooter,
@@ -641,6 +647,11 @@ export {
 	sanitizeAdoptedHtml,
 	sanitizeQuotedHtml,
 } from "./lib/adopted-html.js";
+export {
+	DEFAULT_ATTACHMENT_FILENAME,
+	formatByteSize,
+	sanitizeAttachmentFilename,
+} from "./lib/attachment-file.js";
 export {
 	buildCidResolver,
 	type CidResolvableBodyPart,

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

@@ -0,0 +1,162 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+	formatByteSize,
+	sanitizeAttachmentFilename,
+} from "./attachment-file.js";
+
+const RLO = "\u202e";
+const LRI = "\u2066";
+const PDI = "\u2069";
+const ZWSP = "\u200b";
+const BOM = "\ufeff";
+
+describe("sanitizeAttachmentFilename", () => {
+	it("leaves an ordinary filename alone", () => {
+		assert.equal(
+			sanitizeAttachmentFilename("Quarterly report.pdf"),
+			"Quarterly report.pdf",
+		);
+	});
+
+	it("keeps only the last segment of a POSIX path", () => {
+		assert.equal(sanitizeAttachmentFilename("../../../etc/passwd"), "passwd");
+	});
+
+	it("keeps only the last segment of a Windows path", () => {
+		assert.equal(
+			sanitizeAttachmentFilename("..\\..\\Windows\\System32\\evil.dll"),
+			"evil.dll",
+		);
+	});
+
+	it("falls back when the name is nothing but traversal", () => {
+		assert.equal(sanitizeAttachmentFilename("../../"), "attachment");
+	});
+
+	it("uses the caller's fallback when nothing usable survives", () => {
+		assert.equal(
+			sanitizeAttachmentFilename("   ", "attachment.pdf"),
+			"attachment.pdf",
+		);
+	});
+
+	it("strips the right-to-left override that disguises an extension", () => {
+		assert.equal(
+			sanitizeAttachmentFilename(`invoice${RLO}gnp.exe`),
+			"invoicegnp.exe",
+		);
+	});
+
+	it("strips bidi isolates, zero-width and BOM characters", () => {
+		assert.equal(
+			sanitizeAttachmentFilename(`${LRI}re${ZWSP}port${PDI}${BOM}.pdf`),
+			"report.pdf",
+		);
+	});
+
+	it("strips control characters that would break a header line", () => {
+		assert.equal(
+			sanitizeAttachmentFilename("note\r\n\tX-Evil 1.txt"),
+			"noteX-Evil 1.txt",
+		);
+	});
+
+	it("replaces characters that are illegal in a path", () => {
+		assert.equal(
+			sanitizeAttachmentFilename('re<po>rt|"?*.txt'),
+			"re_po_rt____.txt",
+		);
+	});
+
+	it("drops a leading dot so the file cannot land hidden", () => {
+		assert.equal(sanitizeAttachmentFilename(".bashrc"), "bashrc");
+	});
+
+	it("drops trailing dots and spaces", () => {
+		assert.equal(sanitizeAttachmentFilename("report.pdf. . "), "report.pdf");
+	});
+
+	it("guards a reserved Windows device name", () => {
+		assert.equal(sanitizeAttachmentFilename("NUL.txt"), "_NUL.txt");
+		assert.equal(sanitizeAttachmentFilename("com1"), "_com1");
+	});
+
+	it("does not guard a name that merely starts with a device name", () => {
+		assert.equal(sanitizeAttachmentFilename("console.log"), "console.log");
+	});
+
+	it("clamps an overlong name and keeps its extension", () => {
+		const result = sanitizeAttachmentFilename(`${"a".repeat(400)}.pdf`);
+		assert.equal(result.length, 120);
+		assert.ok(result.endsWith(".pdf"));
+	});
+
+	it("clamps an overlong name that has no extension", () => {
+		assert.equal(sanitizeAttachmentFilename("b".repeat(400)), "b".repeat(120));
+	});
+
+	it("clamps an overlong trailing segment rather than treating it as an extension", () => {
+		assert.equal(
+			sanitizeAttachmentFilename(`${"c".repeat(200)}.${"d".repeat(40)}`),
+			"c".repeat(120),
+		);
+	});
+
+	it("clamps an overlong fallback too", () => {
+		const result = sanitizeAttachmentFilename(
+			"",
+			`attachment.${"x".repeat(400)}`,
+		);
+		assert.equal(result.length, 120);
+	});
+
+	it("clamps on characters, never splitting a surrogate pair", () => {
+		const result = sanitizeAttachmentFilename(`${"😀".repeat(200)}.pdf`);
+		assert.equal([...result].length, 120);
+		assert.ok(result.endsWith(".pdf"));
+		assert.equal(/[\ud800-\udfff]/.test(result.replaceAll("😀", "")), false);
+	});
+});
+
+describe("formatByteSize", () => {
+	it("counts small payloads in bytes", () => {
+		assert.equal(formatByteSize(0), "0 bytes");
+		assert.equal(formatByteSize(1), "1 byte");
+		assert.equal(formatByteSize(1023), "1023 bytes");
+	});
+
+	it("switches to kilobytes at 1024", () => {
+		assert.equal(formatByteSize(1024), "1 KB");
+		assert.equal(formatByteSize(1536), "1.5 KB");
+		assert.equal(formatByteSize(1024 * 999), "999 KB");
+	});
+
+	it("switches to megabytes, gigabytes and terabytes", () => {
+		assert.equal(formatByteSize(1024 * 1024), "1 MB");
+		assert.equal(formatByteSize(1024 * 1024 * 2.5), "2.5 MB");
+		assert.equal(formatByteSize(1024 ** 3), "1 GB");
+		assert.equal(formatByteSize(1024 ** 4), "1 TB");
+	});
+
+	it("promotes at the point one decimal would round up to 1024", () => {
+		assert.equal(formatByteSize(1024 * 1023), "1023 KB");
+		assert.equal(formatByteSize(1024 * 1024 - 6), "1 MB");
+		assert.equal(formatByteSize(1024 ** 3 - 1), "1 GB");
+		assert.equal(formatByteSize(1024 ** 4 - 1), "1 TB");
+	});
+
+	it("stays in terabytes rather than inventing a larger unit", () => {
+		assert.equal(formatByteSize(1024 ** 5), "1024 TB");
+	});
+
+	it("drops the decimal once the value no longer needs it", () => {
+		assert.equal(formatByteSize(1024 * 1024 * 14.04), "14 MB");
+	});
+
+	it("reads as unknown for a size that was never declared", () => {
+		assert.equal(formatByteSize(Number.NaN), "unknown size");
+		assert.equal(formatByteSize(-1), "unknown size");
+		assert.equal(formatByteSize(Number.POSITIVE_INFINITY), "unknown size");
+	});
+});

package/src/lib/attachment-file.ts

@@ -0,0 +1,94 @@
+/**
+ * Filename and size presentation for a mail attachment.
+ *
+ * An attachment filename is attacker-controlled: it arrives verbatim in a
+ * `Content-Disposition` header written by whoever sent the mail. Two things
+ * downstream trust it — the browser's save dialog (`<a download>`) and the
+ * rendered list — so one sanitizer serves both. What the list shows is exactly
+ * what the file is saved as; a name that reads one way and saves another is the
+ * whole point of the attack.
+ */
+
+/**
+ * Control characters, zero-width joiners, line/paragraph separators and the
+ * bidirectional overrides. A RIGHT-TO-LEFT OVERRIDE placed inside
+ * `report<RLO>gnp.exe` makes it render as `reportexe.png`: the extension a
+ * user reads is not the extension that executes. Stripping rather than
+ * escaping keeps the displayed name and the saved name identical.
+ */
+const INVISIBLE_CHARACTERS =
+	// biome-ignore lint/suspicious/noControlCharactersInRegex: stripping C0/C1 controls out of an attacker-supplied filename is the point
+	/[\u0000-\u001f\u007f-\u009f\u061c\u200b-\u200f\u2028\u2029\u202a-\u202e\u2066-\u2069\ufeff]/g;
+
+/** Illegal in a Windows path, and `:` is a separator on classic macOS. */
+const UNSAFE_CHARACTERS = /[<>:"|?*]/g;
+
+/** Reserved device names on Windows — saving to one has no defined outcome. */
+const RESERVED_DEVICE_NAME = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(\.|$)/i;
+
+const MAX_FILENAME_LENGTH = 120;
+const MAX_EXTENSION_LENGTH = 12;
+
+export const DEFAULT_ATTACHMENT_FILENAME = "attachment";
+
+const clampLength = (name: string): string => {
+	// Code points, not UTF-16 units: slicing units splits a surrogate pair and
+	// leaves a lone half in the saved name.
+	const characters = [...name];
+	if (characters.length <= MAX_FILENAME_LENGTH) return name;
+	const dot = name.lastIndexOf(".");
+	const extension =
+		dot > 0 && [...name.slice(dot)].length <= MAX_EXTENSION_LENGTH
+			? name.slice(dot)
+			: "";
+	const budget = MAX_FILENAME_LENGTH - [...extension].length;
+	return characters.slice(0, budget).join("") + extension;
+};
+
+/**
+ * Reduce an attacker-supplied attachment filename to a name that is safe to
+ * both display and save: the final path segment only, no invisible characters,
+ * no leading dot (a hidden file the user never sees land), and bounded length.
+ * Falls back to `fallback` when nothing usable survives.
+ */
+export const sanitizeAttachmentFilename = (
+	raw: string,
+	fallback: string = DEFAULT_ATTACHMENT_FILENAME,
+): string => {
+	const visible = raw.replace(INVISIBLE_CHARACTERS, "");
+	const segments = visible.split(/[/\\]/);
+	const basename = segments[segments.length - 1] ?? "";
+	const trimmed = basename
+		.replace(UNSAFE_CHARACTERS, "_")
+		.replace(/^[.\s]+/, "")
+		.replace(/[.\s]+$/, "");
+	if (trimmed.length === 0) return clampLength(fallback);
+	const guarded = RESERVED_DEVICE_NAME.test(trimmed) ? `_${trimmed}` : trimmed;
+	return clampLength(guarded);
+};
+
+const SIZE_UNITS = ["KB", "MB", "GB", "TB"] as const;
+
+/**
+ * Human-readable byte size, 1024-based, at most one decimal. A negative or
+ * non-finite size reads as unknown rather than as a number, so a broken
+ * BODYSTRUCTURE never presents itself as a measurement.
+ *
+ * The promotion threshold is the point where one decimal would round up to
+ * `1024`, not `1024` itself — `1048570 B` is `1 MB`, never `1024 KB`.
+ */
+export const formatByteSize = (bytes: number): string => {
+	if (!Number.isFinite(bytes) || bytes < 0) return "unknown size";
+	const octets = Math.round(bytes);
+	if (octets < 1024) return octets === 1 ? "1 byte" : `${octets} bytes`;
+
+	const promoteAt = 1023.95;
+	let value = octets / 1024;
+	let unit = 0;
+	while (value >= promoteAt && unit < SIZE_UNITS.length - 1) {
+		value /= 1024;
+		unit += 1;
+	}
+	const rendered = value.toFixed(1).replace(/\.0$/, "");
+	return `${rendered} ${SIZE_UNITS[unit]}`;
+};