Render and download generic file attachments - #120

Fixes BOT-1929 (parent: BOT-1830 Files & media).

Problem

Received attachments were classified only as video vs. non-video (Attachment.video: boolean), so every non-video, non-image file — PDFs, zips, documents, audio — entered the image render path, mounting a broken <img> ("Image unavailable") with no name, type, or retrieval path. Generic files also leaked into the media review viewer's image grid.

Change

• Contract: Attachment.video: boolean → kind: "image" | "video" | "file", plus optional mime, size (validated positive safe-integer from imeta size), and name (decoded URL basename, rejected when it matches the 64-hex relay hash shape). "audio" is reserved for BOT-1934 and slots into one classification switch plus one render branch — no rework.

• Classification (fold.ts): case-insensitive mime-driven; legacy no-mime extension fallback; markdown-projected ![…](url) URLs remain image/video only (unrecognized extensions keep the image default — never dropped, never file).

• New FileAttachment card: Phosphor FileTextIcon/DownloadIcon via the design-system gateway, filename (or mime-derived label), formatted size, and an authenticated download anchor using the same resolved media() proxy source and <a download> pattern as ImageReviewStage. Nameless files render a bare download attribute so they download rather than navigate. Unresolved source → "File unavailable" card with no anchor.

• Navigation policy: relay-proxied sources (same-origin /api/relay…/media) keep the in-app download anchor; sender-supplied external https: sources instead route through the existing onOpenLink opener capability with target="_blank" rel="noreferrer" and no download affordance — the same pattern AttachmentImage uses — so a click can never replace the app webview with sender-controlled content. Anything else falls back to the unavailable card.

• Untrusted name hardening: sender-controlled names (markdown label or decoded URL basename) are rejected if they contain C0/C1 controls, LRM/RLM, bidi overrides (U+202A–202E) or isolates (U+2066–2069), closing right-to-left-override extension spoofing in both the rendered label and the download filename. The check runs after percent-decoding, so encoded overrides can't slip through; ordinary accented/CJK/emoji filenames are unaffected.

• Migration: MessageRow, MediaAttachment (image branch now explicitly kind === "image"; residual kinds show unavailable status, never an <img>), MediaReviewViewer (image grid excludes files), ThreadPanel, fixtures.

• Attachment title links projected from message text: old Buzz sends file messages with a markdown link in the text labeled with the real filename, plus the matching imeta tag — previously this rendered as a broken anchor to the raw (auth-required) relay URL next to the card. Links whose safeMessageUrl-normalized URL exactly matches a parsed imeta attachment URL are now stripped from the rendered text (same bounded-parse/range-strip mechanism as image projection, with overlapping/nested ranges merged), and the link's plain-text label (trimmed, ≤256 chars, URL-shaped and relay-hash-shaped labels rejected) becomes the attachment name, taking precedence over URL-basename derivation. Non-matching links render exactly as before; a mismatch degrades to a visible duplicate link, never a wrong strip. This also applies to image/video attachments whose imeta URL appears as a text link — intended, matches the old-client format. Long filenames ellipsize in the card; the full name stays in aria-label and download.

Filename fallback: when no text link supplies a name and the URL basename is relay-hash-shaped, the card degrades to a mime-derived label ("PDF file") or "File".

Test plan

Colocated Vitest only; no new browser journey (no browser-only behavior beyond RTL coverage — see deferred checks).

• fold.test.ts: mime classification incl. uppercase mime, audio/mpeg → file (BOT-1934 interim), size validation incl. overflow (Number.isSafeInteger guard), hash-basename name rejection, decodeURIComponent failure fallback, legacy extension fallback, extensionless markdown-image projection regression; link projection: direct/reference/autolink forms, non-matching links untouched, empty/hash-shaped/URL-shaped/over-length labels, duplicate links, mid-sentence stripping, link-only messages, nested image-in-link prose preservation.
• FileAttachment.test.tsx / MessageRow.test.tsx: named+available, nameless+available (bare download, proxy href), unavailable (no anchor), label fallbacks (octet-stream/vnd.ms-excel → "File"), no image markup for file attachments.
• MediaReviewViewer.test.tsx: files excluded from image grid. icon-labels.test.tsx: stray file kind in MediaAttachment renders no <img>.

Local validation: tsc --noEmit ✅ · Biome on changed files ✅ · full Vitest suite ✅ (175 files / 1,837 tests) · pre-commit and pre-push hooks ✅.

Design pack consulted

tokens/ registry and DESIGN.md (State, Contrast, Type): card styles reuse existing Messages.module.css sibling patterns and registered ramp tokens only; weight via existing --type-weight-medium; focus styles keyboard-only gated (html[data-keyboard-navigation] / :focus-visible); icons via src/shared/design-system/icons (repo-pinned Phosphor gateway). No new tokens, sizes, or components introduced.

Compatibility

No migration is needed. persistence.ts stores signed wire events only (re-verified and refolded by the owner after fresh roster authorization), so cached records carry imeta tags rather than Attachment objects — no persisted layer ever held the old video: boolean shape. outbox-storage.ts, read-state-storage.ts, view-state.ts and plugins/storage.ts carry no attachments.

Authenticated retrieval

The dev broker's /media handler previously rejected any upstream Content-Type that was not image or video with a 415. Because the file card's anchor carries download, the browser saved that error body as a file — an earlier manual check that looked successful had in fact downloaded a 31-byte media.json containing {"error":"Media type rejected"}. Thanks to @wesbillman's review for catching this; the card renders from the imeta tag, which masked the failure.

The handler now classifies into three tiers instead of two, keeping the guard rather than removing it:

• Inline media — raster image/* and video/*: unchanged, including video Range/streaming, Accept-Ranges and the 206 budget exemption.
• Neutralized download — everything else: Content-Type: application/octet-stream, Content-Disposition: attachment (no filename parameter — the client anchor's download already names the file, and omitting it avoids header injection on a sender-controlled string), nosniff retained, buffered under the existing MAX_MEDIA_BYTES, and no Accept-Ranges since the buffered path cannot honour Range.
• image/svg+xml is deliberately routed to the download tier, not the inline image tier — SVG is active content and an XSS vector when served inline on the app origin.

Two smuggling routes were found and closed during review. Inline tiers are now gated on a strict single-token media-type match (so image/png, image/svg+xml cannot claim to be an image — browsers split on commas and honour the last parseable type), and the inline response emits the validated normalized media type rather than echoing the raw upstream header (so image/png;x, image/svg+xml cannot smuggle the tail through parameter position). Parameters are stripped as a consequence, including codecs on video; container-based codec selection is unaffected and the Range/streaming assertions are unchanged.

Origin pinning, the signed kind-24242 auth event, redirect: "error", the upstream timeout, both byte-budget checks and the stream teardown handlers are untouched. The 20 MiB cap is retained for generic files by decision; raising it is a separate call.

Review

Three adversarial review rounds plus one general code review; all findings fixed and re-verified. Notable catches: markdown content-loss for extensionless projected URLs, nameless files navigating instead of downloading, case-sensitive MIME matching, nested-range prose corruption, autolink URLs adopted as filenames, and the two hardening items above.

Deferred follow-ups (out of scope here)

A Range request against a generic file is still forwarded upstream, and a 206 response is then buffered and returned as a 200 with a truncated body (pre-existing shape, also present on the image branch's Content-Range passthrough); narrowing MediaAttachment's prop type to make its invariant compiler-enforced; de-duplicating imeta field parsing between parseAttachments and imetaAttachmentUrls; formatFileSize rounding (1536 → "2 KB"); a mimeLabel allowlist for noisy subtypes ("PLAIN file"); legacy .mov/.m4v/.heic extension classification; a MAX_MARKDOWN_LENGTH gate on the fold parse path; collapsing the two unavailable-card branches in FileAttachment.

Deferred checks

• Light/dark visual check of the card in the running app.
• Real historical-corpus check: legacy no-mime unknown-extension attachments intentionally flip from broken image to file card.