@huynle/hub 0.8.7 → 0.9.0

package/src/central/media-remote.ts

@@ -0,0 +1,248 @@
+// GET /api/media/remote?url=… (design §4): web images for the console, fetched by the hub through the safe fetcher
+// (./fetcher.ts) for signed-in users only. Only PNG, JPEG, WebP and GIF are served (sniffed from the bytes, never
+// SVG), within REMOTE_MEDIA_LIMITS, with the §1 media headers. A tenant-scoped in-memory cache (per pod in cluster
+// mode) keyed by the normalised URL keeps images for the site's lifetime clamped to 1-24 h and failures for 5 min.
+// Per user: 30 fetches a minute and 4 at once (429), one budget shared with /api/media/unfurl (./fetch-budget.ts);
+// cache hits are free. Each fetch is audited with the user, the
+// host and the outcome; the full URL never is (it may carry leaked data). HUB_REMOTE_FETCH=off turns it off.
+import { createHash } from "node:crypto"
+import { MEDIA_LIMITS } from "../protocol"
+import { createFetchBudget, type FetchBudget } from "./fetch-budget"
+import { checkURL, FetchError, type Fetcher } from "./fetcher"
+
+/** Remote image caps: those of timeline images (MEDIA_LIMITS: 8 MiB, 40 MP, 16,384 px per side). */
+export const REMOTE_MEDIA_LIMITS = { maxBytes: MEDIA_LIMITS.maxBytes, maxPixels: MEDIA_LIMITS.maxPixels, maxSide: MEDIA_LIMITS.maxSide } as const
+
+const MIN_TTL_MS = 3_600_000
+const MAX_TTL_MS = 24 * 3_600_000
+const FAILURE_TTL_MS = 5 * 60_000
+const DEFAULT_CACHE_BYTES = 64 * 1024 * 1024
+const MAX_CACHE_ENTRIES = 4096
+/** What a cached failure counts as against the byte bound. */
+const FAILURE_COST = 256
+const ACCEPT = "image/png,image/jpeg,image/webp,image/gif;q=0.9,*/*;q=0.1"
+
+/** The §1 media headers, shared by remote and timeline images (./media-timeline.ts). */
+export const MEDIA_HEADERS = {
+  "x-content-type-options": "nosniff",
+  "content-security-policy": "default-src 'none'; sandbox",
+  "cache-control": "private, no-cache",
+  "cross-origin-resource-policy": "same-origin",
+  "referrer-policy": "no-referrer",
+} as const
+
+export interface SniffedImage {
+  readonly mime: "image/png" | "image/jpeg" | "image/webp" | "image/gif"
+  readonly width: number
+  readonly height: number
+}
+
+const u16be = (b: Uint8Array, at: number) => (b[at]! << 8) | b[at + 1]!
+const u16le = (b: Uint8Array, at: number) => b[at]! | (b[at + 1]! << 8)
+const u24le = (b: Uint8Array, at: number) => b[at]! | (b[at + 1]! << 8) | (b[at + 2]! << 16)
+const u32be = (b: Uint8Array, at: number) => ((b[at]! << 24) >>> 0) + ((b[at + 1]! << 16) | (b[at + 2]! << 8) | b[at + 3]!)
+const u32le = (b: Uint8Array, at: number) => (b[at]! | (b[at + 1]! << 8) | (b[at + 2]! << 16) | (b[at + 3]! << 24)) >>> 0
+const text = (b: Uint8Array, at: number, s: string) => b.length >= at + s.length && [...s].every((c, i) => b[at + i] === c.charCodeAt(0))
+
+/** The type (from magic bytes) and dimensions (from the header) of a PNG, JPEG, WebP or GIF; undefined otherwise. */
+export function sniffImage(b: Uint8Array): SniffedImage | undefined {
+  const found = sniff(b)
+  return found && found.width > 0 && found.height > 0 ? found : undefined
+}
+
+function sniff(b: Uint8Array): SniffedImage | undefined {
+  if (b.length >= 24 && b[0] === 0x89 && text(b, 1, "PNG\r\n\x1a\n") && text(b, 12, "IHDR")) {
+    return { mime: "image/png", width: u32be(b, 16), height: u32be(b, 20) }
+  }
+  if (b.length >= 10 && (text(b, 0, "GIF87a") || text(b, 0, "GIF89a"))) return { mime: "image/gif", width: u16le(b, 6), height: u16le(b, 8) }
+  if (b.length >= 4 && b[0] === 0xff && b[1] === 0xd8) return jpegSize(b)
+  if (b.length >= 30 && text(b, 0, "RIFF") && text(b, 8, "WEBP")) {
+    if (text(b, 12, "VP8X")) return { mime: "image/webp", width: u24le(b, 24) + 1, height: u24le(b, 27) + 1 }
+    if (text(b, 12, "VP8L") && b[20] === 0x2f) {
+      const bits = u32le(b, 21)
+      return { mime: "image/webp", width: (bits & 0x3fff) + 1, height: ((bits >>> 14) & 0x3fff) + 1 }
+    }
+    if (text(b, 12, "VP8 ") && b[23] === 0x9d && b[24] === 0x01 && b[25] === 0x2a) {
+      return { mime: "image/webp", width: u16le(b, 26) & 0x3fff, height: u16le(b, 28) & 0x3fff }
+    }
+  }
+  return undefined
+}
+
+/** Walks the JPEG markers to the first frame header (SOFn). */
+function jpegSize(b: Uint8Array): SniffedImage | undefined {
+  let i = 2
+  while (i + 3 < b.length) {
+    if (b[i] !== 0xff) return undefined
+    const marker = b[i + 1]!
+    if (marker === 0xff) {
+      i++ // fill byte
+      continue
+    }
+    if (marker === 0x01 || (marker >= 0xd0 && marker <= 0xd8)) {
+      i += 2 // standalone markers
+      continue
+    }
+    if (marker === 0xd9 || marker === 0xda) return undefined // end of image, or scan data before any frame header
+    const length = u16be(b, i + 2)
+    if (length < 2) return undefined
+    if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
+      if (i + 9 > b.length) return undefined
+      return { mime: "image/jpeg", width: u16be(b, i + 7), height: u16be(b, i + 5) }
+    }
+    i += 2 + length
+  }
+  return undefined
+}
+
+export interface RemoteMediaAudit {
+  readonly actor: string
+  readonly action: string
+  readonly target?: string
+  readonly detail?: string
+}
+
+export interface RemoteMediaOptions {
+  readonly fetcher: Fetcher
+  /** False: HUB_REMOTE_FETCH=off; every request is refused and nothing is fetched. */
+  readonly enabled: boolean
+  readonly now?: () => number
+  /** The hub's audit log (store.audit). */
+  readonly audit: (entry: RemoteMediaAudit) => unknown
+  /** The cache's byte bound (default 64 MiB). */
+  readonly cacheBytes?: number
+  /** The per-user fetch budget (http.ts shares one with /api/media/unfurl); default: its own, 30 a minute and 4 at once. */
+  readonly budget?: FetchBudget
+}
+
+export interface RemoteMedia {
+  /** Answers GET /api/media/remote for `userID` (already authenticated as a signed-in user). */
+  handle(userID: string, request: Request, url: URL): Promise<Response>
+}
+
+type Entry =
+  | { readonly expires: number; readonly cost: number; readonly ok: true; readonly bytes: Uint8Array<ArrayBuffer>; readonly mime: string; readonly etag: string }
+  | { readonly expires: number; readonly cost: number; readonly ok: false; readonly status: number; readonly code: string; readonly message: string }
+
+/** The 429 text of a refused budget take (shared with ./media-unfurl.ts). */
+export const budgetMessage = (refused: { reason: "minute" | "concurrent"; limit: number }) =>
+  refused.reason === "minute" ? `At most ${refused.limit} web fetches (images and link previews) a minute` : `At most ${refused.limit} web fetches (images and link previews) at once`
+
+export const failure = (status: number, code: string, message: string, headers: Record<string, string> = {}) =>
+  Response.json({ error: message, code }, { status, headers: { "x-content-type-options": "nosniff", "cache-control": "no-store", ...headers } })
+
+/** How long the site says a response may be cached, clamped to 1-24 h (shared with ./media-unfurl.ts). */
+export function lifetime(headers: Headers, now: number): number {
+  const control = headers.get("cache-control") ?? ""
+  const maxAge = /(?:^|[,\s])max-age\s*=\s*"?(\d+)/i.exec(control)
+  let ms = 0
+  if (maxAge) ms = Number(maxAge[1]) * 1000
+  else {
+    const expires = Date.parse(headers.get("expires") ?? "")
+    const date = Date.parse(headers.get("date") ?? "")
+    if (Number.isFinite(expires)) ms = expires - (Number.isFinite(date) ? date : now)
+  }
+  return Math.min(MAX_TTL_MS, Math.max(MIN_TTL_MS, Number.isFinite(ms) ? ms : 0))
+}
+
+const etagMatches = (header: string | null, etag: string) =>
+  !!header && header.split(",").some((tag) => {
+    const t = tag.trim()
+    return t === "*" || t === etag || t === `W/${etag}`
+  })
+
+export function createRemoteMedia(options: RemoteMediaOptions): RemoteMedia {
+  const now = options.now ?? Date.now
+  const cacheBytes = options.cacheBytes ?? DEFAULT_CACHE_BYTES
+  const budget = options.budget ?? createFetchBudget({ now })
+  const cache = new Map<string, Entry>()
+  let cached = 0
+
+  function remember(key: string, entry: Entry): void {
+    forget(key)
+    if (entry.cost > cacheBytes) return
+    cache.set(key, entry)
+    cached += entry.cost
+    for (const [oldest, old] of cache) {
+      if (cached <= cacheBytes && cache.size <= MAX_CACHE_ENTRIES) break
+      cache.delete(oldest)
+      cached -= old.cost
+    }
+  }
+  function forget(key: string): void {
+    const old = cache.get(key)
+    if (!old) return
+    cache.delete(key)
+    cached -= old.cost
+  }
+  function lookup(key: string): Entry | undefined {
+    const entry = cache.get(key)
+    if (!entry) return undefined
+    if (entry.expires <= now()) {
+      forget(key)
+      return undefined
+    }
+    cache.delete(key) // most recently used last
+    cache.set(key, entry)
+    return entry
+  }
+
+  function answer(entry: Entry, request: Request): Response {
+    if (!entry.ok) return failure(entry.status, entry.code, entry.message)
+    if (etagMatches(request.headers.get("if-none-match"), entry.etag)) return new Response(null, { status: 304, headers: { ...MEDIA_HEADERS, etag: entry.etag } })
+    return new Response(entry.bytes, { headers: { ...MEDIA_HEADERS, "content-type": entry.mime, "content-length": String(entry.bytes.length), etag: entry.etag } })
+  }
+
+  /** The fetch outcome to cache: the image, or why not. */
+  async function load(target: URL): Promise<{ entry: Entry; host: string; outcome: string }> {
+    const at = now()
+    const fail = (status: number, code: string, message: string) => ({ expires: at + FAILURE_TTL_MS, cost: FAILURE_COST, ok: false as const, status, code, message })
+    try {
+      const got = await options.fetcher.fetch(target, { maxBytes: REMOTE_MEDIA_LIMITS.maxBytes, accept: ACCEPT })
+      const host = got.url.hostname
+      const image = sniffImage(got.body)
+      if (!image) return { entry: fail(415, "not_image", "Not a PNG, JPEG, WebP or GIF image"), host, outcome: "not_image" }
+      const { maxSide, maxPixels } = REMOTE_MEDIA_LIMITS
+      if (image.width > maxSide || image.height > maxSide || image.width * image.height > maxPixels) {
+        return { entry: fail(413, "too_large", `The image is larger than ${maxSide} px per side or ${maxPixels / 1_000_000} MP`), host, outcome: "too_large" }
+      }
+      const etag = `"sha256-${createHash("sha256").update(got.body).digest("base64url")}"`
+      const entry: Entry = { expires: at + lifetime(got.headers, at), cost: got.body.length, ok: true, bytes: got.body, mime: image.mime, etag }
+      return { entry, host, outcome: "ok" }
+    } catch (cause) {
+      if (!(cause instanceof FetchError)) throw cause
+      const code = cause.kind === "too_large" ? "too_large" : cause.kind
+      const message = cause.kind === "too_large" ? `The image is larger than ${REMOTE_MEDIA_LIMITS.maxBytes / 1024 / 1024} MiB` : cause.message
+      return { entry: fail(cause.status, code, message), host: cause.host ?? target.hostname, outcome: cause.kind }
+    }
+  }
+
+  async function handle(userID: string, request: Request, url: URL): Promise<Response> {
+    if (!options.enabled) return failure(403, "disabled", "Remote media is turned off on this hub (HUB_REMOTE_FETCH=off)")
+    const raw = url.searchParams.get("url")
+    if (!raw) return failure(400, "bad_url", "Expected a url query parameter")
+    let target: URL
+    try {
+      target = checkURL(raw)
+    } catch (cause) {
+      if (cause instanceof FetchError) return failure(cause.status, cause.kind, cause.message)
+      throw cause
+    }
+    const key = `${userID}\n${target.href}`
+    const hit = lookup(key)
+    if (hit) return answer(hit, request)
+
+    const slot = budget.take(userID)
+    if (!slot.ok) return failure(429, "rate_limited", budgetMessage(slot), { "retry-after": String(slot.retryAfter) })
+    try {
+      const { entry, host, outcome } = await load(target)
+      await Promise.resolve(options.audit({ actor: userID, action: "media.remote", target: host, detail: outcome })).catch(() => undefined)
+      remember(key, entry)
+      return answer(entry, request)
+    } finally {
+      slot.release()
+    }
+  }
+
+  return { handle }
+}

package/src/central/media-timeline.ts

@@ -0,0 +1,317 @@
+// (S4 M3, session media design §1) GET /api/sessions/:session/timeline/messages/:message/media/:ref: an image of a
+// session's timeline, pulled from the owning spoke on demand (op timelineMedia, feature "timelineMedia") chunk by
+// chunk and answered to the console. The hub trusts nothing the spoke says about the bytes:
+//
+// - the first chunk's magic bytes must be the type the spoke claims, and one of MEDIA_MIMES (else 415);
+// - the claimed dimensions must fit MEDIA_LIMITS (else 413), the length MEDIA_LIMITS.maxBytes;
+// - every chunk must follow the previous one, and the length and SHA-256 of the whole must be the claimed ones.
+//
+// The whole image (≤ MEDIA_LIMITS.maxBytes) is collected and verified before anything is answered: a mismatch is 502
+// integrity, never a partial 200 (Bun ends an errored chunked body cleanly, so a stream cannot signal it) and never a
+// 304 for an unverified hash; it is not cached. One image gets 60 s in all (504 timeout), past each chunk's timeout.
+//
+// Answers carry the media headers (nosniff, sandbox CSP, CORP same-origin, no referrer, private no-cache) and an ETag
+// of the SHA-256. SVG is always an attachment (never a document on the hub's origin); `?download=1` makes any type one.
+//
+// Cache: per pod, in memory, keyed by (user, session, message, ref), LRU within 64 MiB; never shared between users.
+// Attachments (`f`) and tool items (`t`) of a message do not change, so a cached one is served (or answered 304 for a
+// matching If-None-Match) without contacting the spoke, once the route's access check passed. A path (`p:`) names a
+// file on the agent's machine that may change, so it is revalidated with one first-chunk call (which also re-checks
+// the spoke's path policy); the later chunks come from the cache when the SHA-256 is unchanged. The caller bypasses the
+// cache while a revert is staged (the spoke decides whether the message is hidden) and forgets a session when it is
+// deleted or a revert is committed in it. Every hit also checks the session's current committed revert as the owning
+// connection reports it (seen from any pod, so another pod's cache never outlives a revert) and a 10 min TTL. Limits: 4 spoke fetches in flight per user, 2 per spoke connection (429).
+import { createHash } from "node:crypto"
+import { MEDIA_LIMITS, MEDIA_MIMES, type MediaMime, type MediaRef, type TimelineMediaResult } from "../protocol"
+import { MEDIA_HEADERS } from "./media-remote"
+
+const DEFAULT_CACHE_BYTES = 64 * 1024 * 1024
+const DEFAULT_PER_USER = 4
+const DEFAULT_PER_CONNECTION = 2
+const DEFAULT_DEADLINE_MS = 60_000
+/** Backstop: a cached image is fetched again after this long, whatever else happened. */
+const CACHE_TTL_MS = 10 * 60_000
+const SHA256 = /^[0-9a-f]{64}$/
+const EXTENSIONS: Record<MediaMime, string> = { "image/png": "png", "image/jpeg": "jpg", "image/webp": "webp", "image/gif": "gif", "image/svg+xml": "svg" }
+
+const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]
+/** An SVG document: optional BOM, XML declaration, comments and doctype, then the root `<svg` (as the spoke sniffs). */
+const SVG_START = /^\uFEFF?\s*(?:<\?xml[^>]*\?>\s*)?(?:<!--[\s\S]*?-->\s*)*(?:<!DOCTYPE\s+svg[^>]*>\s*)?(?:<!--[\s\S]*?-->\s*)*<svg[\s>/]/i
+const SVG_SNIFF_BYTES = 4096
+const ascii = (b: Uint8Array, at: number, text: string) => b.length >= at + text.length && [...text].every((c, i) => b[at + i] === c.charCodeAt(0))
+
+/** The image type of `bytes` by their magic bytes (one of MEDIA_MIMES), else undefined. */
+export function sniffMediaMime(bytes: Uint8Array): MediaMime | undefined {
+  if (bytes.length >= 8 && PNG_SIGNATURE.every((v, i) => bytes[i] === v)) return "image/png"
+  if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) return "image/jpeg"
+  if (ascii(bytes, 0, "GIF87a") || ascii(bytes, 0, "GIF89a")) return "image/gif"
+  if (ascii(bytes, 0, "RIFF") && ascii(bytes, 8, "WEBP")) return "image/webp"
+  if (SVG_START.test(new TextDecoder("utf-8", { fatal: false }).decode(bytes.subarray(0, SVG_SNIFF_BYTES)))) return "image/svg+xml"
+  return undefined
+}
+
+export type TimelineMediaRequest = { readonly op: "timelineMedia"; readonly sessionID: string; readonly messageID: string; readonly ref: string; readonly offset: number }
+
+export interface TimelineMediaOptions {
+  /** One timelineMedia op on the owning connection (spokes.request: routed to the owning pod in cluster mode). */
+  readonly request: (connID: string, req: TimelineMediaRequest) => Promise<TimelineMediaResult>
+  readonly cacheBytes?: number
+  readonly perUser?: number
+  readonly perConnection?: number
+  /** The longest one image may take, all chunks together (default 60 s). */
+  readonly deadlineMs?: number
+  /** The clock of the cache TTL. */
+  readonly now?: () => number
+}
+
+export interface TimelineMediaInput {
+  /** The signed-in user the route's access check admitted. */
+  readonly userID: string
+  /** The session's owning connection (feature "timelineMedia" checked by the caller). */
+  readonly connID: string
+  readonly sessionID: string
+  readonly messageID: string
+  readonly ref: string
+  readonly parsed: MediaRef
+  readonly ifNoneMatch: string | null
+  readonly download: boolean
+  /** Neither read nor fill the cache (a revert is staged in the session). */
+  readonly bypassCache: boolean
+  /**
+   * The session's latest committed revert (`revertCommitted.at`) as the owning connection reports it, seen from any
+   * pod: a cached entry filled under another one is stale (its message may be gone).
+   */
+  readonly revertAt: number | undefined
+}
+
+export interface TimelineMedia {
+  serve(input: TimelineMediaInput): Promise<Response>
+  /** Forgets a session's cached images (it was deleted, or a revert was committed in it). */
+  forgetSession(sessionID: string): void
+  /** Bytes cached now (tests, metrics). */
+  cachedBytes(): number
+}
+
+interface Entry {
+  readonly sessionID: string
+  readonly sha256: string
+  readonly mime: MediaMime
+  readonly data: Uint8Array<ArrayBuffer>
+  /** When it was cached (options.now). */
+  readonly filled: number
+  /** The session's committed revert (`at`) when it was cached. */
+  readonly revertAt: number | undefined
+}
+
+const failure = (status: number, code: string, message: string, extra: Record<string, unknown> = {}, headers: Record<string, string> = {}) =>
+  Response.json({ error: message, code, ...extra }, { status, headers: { "x-content-type-options": "nosniff", "cache-control": "no-store", ...headers } })
+
+/** An answer the spoke should never give (a bug or a hostile spoke): 502, nothing served. */
+class BadAnswer extends Error {
+  constructor(message: string, readonly code = "bad_answer") {
+    super(message)
+  }
+}
+
+class DeadlineError extends Error {
+  constructor() {
+    super("The image took too long to load from the session's machine")
+  }
+}
+
+/** `promise`, or a DeadlineError once `deadline` (performance.now()) passes. */
+function withDeadline<T>(promise: Promise<T>, deadline: number): Promise<T> {
+  const left = deadline - performance.now()
+  if (left <= 0) return Promise.reject(new DeadlineError())
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const expired = new Promise<never>((_, reject) => (timer = setTimeout(() => reject(new DeadlineError()), left)))
+  return Promise.race([promise, expired]).finally(() => clearTimeout(timer))
+}
+
+const etagOf = (sha256: string) => `"sha256-${sha256}"`
+const etagMatches = (header: string | null, etag: string) =>
+  !!header && header.split(",").some((tag) => {
+    const t = tag.trim()
+    return t === "*" || t === etag || t === `W/${etag}`
+  })
+
+/** `inline`/`attachment` with an RFC 5987 file name: the path's base name or `<message>-<ref>`, with the type's extension. */
+function disposition(input: TimelineMediaInput, mime: MediaMime): string {
+  const kind = input.download || mime === "image/svg+xml" ? "attachment" : "inline"
+  const ext = EXTENSIONS[mime]
+  const raw = input.parsed.kind === "path" ? input.parsed.path.split(/[\\/]/).pop()! : `${input.messageID}-${input.ref}`
+  let name = raw.normalize("NFC").replace(/[^\p{L}\p{N}._-]+/gu, "_").replace(/^[._]+/, "").slice(0, 120) || "image"
+  if (!name.toLowerCase().endsWith(`.${ext}`) && !(ext === "jpg" && /\.jpeg$/i.test(name))) name += `.${ext}`
+  const encoded = encodeURIComponent(name).replace(/['()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`)
+  return `${kind}; filename*=UTF-8''${encoded}`
+}
+
+function decodeChunk(data: unknown): Uint8Array<ArrayBuffer> {
+  if (typeof data !== "string" || data.length > Math.ceil(MEDIA_LIMITS.chunkBytes / 3) * 4 + 4 || !/^[A-Za-z0-9+/]*={0,2}$/.test(data)) throw new BadAnswer("The spoke sent a malformed chunk")
+  const bytes = new Uint8Array(Buffer.from(data, "base64"))
+  if (bytes.length === 0 || bytes.length > MEDIA_LIMITS.chunkBytes) throw new BadAnswer("The spoke sent a malformed chunk")
+  return bytes
+}
+
+/** The checked metadata of a served answer. */
+function checkInfo(media: TimelineMediaResult["media"]): { mime: MediaMime; bytes: number; sha256: string } | Response {
+  if (media && typeof media.mime === "string" && !MEDIA_MIMES.includes(media.mime)) return failure(415, "type", "This file is not an image the hub shows")
+  if (!media || !Number.isInteger(media.bytes) || media.bytes < 1 || typeof media.sha256 !== "string" || !SHA256.test(media.sha256)) {
+    throw new BadAnswer("The spoke described the image incompletely")
+  }
+  if (media.bytes > MEDIA_LIMITS.maxBytes) return failure(413, "too_large", "This image is too large to show here", { bytes: media.bytes, max: MEDIA_LIMITS.maxBytes })
+  const { width, height } = media
+  if (width !== undefined || height !== undefined) {
+    const { maxSide, maxPixels } = MEDIA_LIMITS
+    if (!Number.isInteger(width) || !Number.isInteger(height) || width! < 0 || height! < 0) throw new BadAnswer("The spoke sent invalid dimensions")
+    if (width! > maxSide || height! > maxSide || width! * height! > maxPixels) return failure(413, "dimensions", `This image is larger than ${maxSide} px per side or ${maxPixels / 1_000_000} MP`)
+  }
+  return { mime: media.mime, bytes: media.bytes, sha256: media.sha256 }
+}
+
+/** The answer for a spoke result that serves no image (or undefined when it serves one). */
+function refusal(result: TimelineMediaResult): Response | undefined {
+  if (result.tooLarge) return failure(413, "too_large", "This image is too large to show here", { bytes: result.tooLarge.bytes, max: result.tooLarge.max })
+  switch (result.refused) {
+    case "type":
+      return failure(415, "type", "This file is not an image the hub shows")
+    case "dimensions":
+      return failure(413, "dimensions", "This image has too many pixels to show here")
+    case "path":
+      return failure(404, "path", "This file is not in this session's files")
+    case "hidden":
+      return failure(404, "hidden", "This message is hidden by a revert")
+    case undefined:
+      break
+    default:
+      throw new BadAnswer("The spoke refused the image for an unknown reason")
+  }
+  if (!result.media && !result.chunk) return failure(404, "not_found", "No such image")
+  return undefined
+}
+
+export function createTimelineMedia(options: TimelineMediaOptions): TimelineMedia {
+  const cacheBytes = options.cacheBytes ?? DEFAULT_CACHE_BYTES
+  const perUser = options.perUser ?? DEFAULT_PER_USER
+  const perConnection = options.perConnection ?? DEFAULT_PER_CONNECTION
+  const deadlineMs = options.deadlineMs ?? DEFAULT_DEADLINE_MS
+  const now = options.now ?? Date.now
+  const cache = new Map<string, Entry>()
+  let cached = 0
+  const users = new Map<string, number>()
+  const conns = new Map<string, number>()
+
+  function remember(key: string, entry: Entry): void {
+    forget(key)
+    if (entry.data.length > Math.min(cacheBytes, MEDIA_LIMITS.maxBytes)) return
+    cache.set(key, entry)
+    cached += entry.data.length
+    for (const [oldest, old] of cache) {
+      if (cached <= cacheBytes) break
+      cache.delete(oldest)
+      cached -= old.data.length
+    }
+  }
+  function forget(key: string): void {
+    const old = cache.get(key)
+    if (!old) return
+    cache.delete(key)
+    cached -= old.data.length
+  }
+  /** A fresh entry: within the TTL, and filled under the session's current committed revert (any pod's spoke). */
+  function lookup(key: string, input: TimelineMediaInput): Entry | undefined {
+    const entry = cache.get(key)
+    if (!entry) return undefined
+    if (now() - entry.filled >= CACHE_TTL_MS || entry.revertAt !== input.revertAt) {
+      forget(key)
+      return undefined
+    }
+    cache.delete(key) // most recently used last
+    cache.set(key, entry)
+    return entry
+  }
+
+  const bump = (counts: Map<string, number>, id: string, by: number) => {
+    const n = (counts.get(id) ?? 0) + by
+    if (n > 0) counts.set(id, n)
+    else counts.delete(id)
+  }
+
+  function headers(input: TimelineMediaInput, mime: MediaMime, sha256: string, bytes: number): Record<string, string> {
+    return { ...MEDIA_HEADERS, "content-type": mime, "content-length": String(bytes), etag: etagOf(sha256), "content-disposition": disposition(input, mime) }
+  }
+  const notModified = (sha256: string) => new Response(null, { status: 304, headers: { ...MEDIA_HEADERS, etag: etagOf(sha256) } })
+  const fromCache = (input: TimelineMediaInput, entry: Entry) =>
+    etagMatches(input.ifNoneMatch, etagOf(entry.sha256)) ? notModified(entry.sha256) : new Response(entry.data, { headers: headers(input, entry.mime, entry.sha256, entry.data.length) })
+
+  async function serve(input: TimelineMediaInput): Promise<Response> {
+    const key = [input.userID, input.sessionID, input.messageID, input.ref].join("\n")
+    const cacheable = !input.bypassCache
+    if (!cacheable) forget(key)
+    const hit = cacheable ? lookup(key, input) : undefined
+    if (hit && input.parsed.kind !== "path") return fromCache(input, hit)
+    const pathHit = hit
+    if ((users.get(input.userID) ?? 0) >= perUser) return failure(429, "rate_limited", `At most ${perUser} images load at once`, {}, { "retry-after": "1" })
+    if ((conns.get(input.connID) ?? 0) >= perConnection) return failure(429, "rate_limited", `At most ${perConnection} images load at once from one machine`, {}, { "retry-after": "1" })
+    bump(users, input.userID, 1)
+    bump(conns, input.connID, 1)
+    let held = true
+    const release = () => {
+      if (!held) return
+      held = false
+      bump(users, input.userID, -1)
+      bump(conns, input.connID, -1)
+    }
+    const deadline = performance.now() + deadlineMs
+    const fetchChunk = (offset: number) =>
+      withDeadline(options.request(input.connID, { op: "timelineMedia", sessionID: input.sessionID, messageID: input.messageID, ref: input.ref, offset }), deadline)
+
+    try {
+      const first = await fetchChunk(0)
+      const refused = refusal(first)
+      if (refused) return refused
+      const info = checkInfo(first.media)
+      if (info instanceof Response) return info
+      if (!first.chunk || first.chunk.offset !== 0 || typeof first.chunk.last !== "boolean") throw new BadAnswer("The spoke sent no first chunk")
+      const head = decodeChunk(first.chunk.data)
+      if (sniffMediaMime(head) !== info.mime) return failure(415, "type", "This file is not the image type it claims to be")
+      if (head.length > info.bytes || (first.chunk.last && head.length !== info.bytes)) throw new BadAnswer("The image's length does not match", "integrity")
+      // A path's cached bytes were verified; the spoke's SHA-256 is over the file's whole current bytes, so the same
+      // one means the same image (answered from the cache, 304 included, without the later chunks).
+      if (pathHit && pathHit.sha256 === info.sha256) return fromCache(input, pathHit)
+
+      // The whole image is collected and verified before any byte (or a 304) is sent: ≤ MEDIA_LIMITS.maxBytes.
+      const whole = new Uint8Array(info.bytes)
+      whole.set(head)
+      let received = head.length
+      let last = first.chunk.last
+      while (!last) {
+        const next = await fetchChunk(received)
+        if (refusal(next) || !next.chunk || next.chunk.offset !== received || typeof next.chunk.last !== "boolean") throw new BadAnswer("The spoke stopped serving the image")
+        if (next.media && (next.media.sha256 !== info.sha256 || next.media.bytes !== info.bytes || next.media.mime !== info.mime)) throw new BadAnswer("The image changed while it was sent", "integrity")
+        const bytes = decodeChunk(next.chunk.data)
+        const end = received + bytes.length
+        if (end > info.bytes || (next.chunk.last ? end !== info.bytes : end >= info.bytes)) throw new BadAnswer("The image's length does not match", "integrity")
+        whole.set(bytes, received)
+        received = end
+        last = next.chunk.last
+      }
+      if (createHash("sha256").update(whole).digest("hex") !== info.sha256) throw new BadAnswer("The image's SHA-256 does not match", "integrity")
+      const entry: Entry = { sessionID: input.sessionID, sha256: info.sha256, mime: info.mime, data: whole, filled: now(), revertAt: input.revertAt }
+      if (cacheable) remember(key, entry)
+      return fromCache(input, entry)
+    } catch (cause) {
+      if (cause instanceof BadAnswer) return failure(502, cause.code, cause.message)
+      if (cause instanceof DeadlineError) return failure(504, "timeout", cause.message)
+      throw cause
+    } finally {
+      release()
+    }
+  }
+
+  function forgetSession(sessionID: string): void {
+    for (const [key, entry] of cache) if (entry.sessionID === sessionID) forget(key)
+  }
+
+  return { serve, forgetSession, cachedBytes: () => cached }
+}