@huynle/hub 0.8.6 → 0.9.0

package/src/spoke/media-bytes.ts

@@ -0,0 +1,171 @@
+// (S4 M2) What an image's bytes are: magic-byte sniffing (PNG, JPEG, WebP, GIF, SVG) and the width and height in
+// a raster image's header, read without decoding it. The spoke serves an image only when its bytes are the type its
+// source claims (an attachment's or tool item's mime, a path's extension) and its dimensions fit MEDIA_LIMITS.
+import { MEDIA_LIMITS, MEDIA_MIMES, type MediaMime } from "../protocol"
+
+export interface Dimensions {
+  readonly width: number
+  readonly height: number
+}
+
+const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]
+const ascii = (b: Uint8Array, at: number, text: string) => b.length >= at + text.length && [...text].every((c, i) => b[at + i] === c.charCodeAt(0))
+const be16 = (b: Uint8Array, at: number) => (b[at]! << 8) | b[at + 1]!
+const be32 = (b: Uint8Array, at: number) => ((b[at]! << 24) | (b[at + 1]! << 16) | (b[at + 2]! << 8) | b[at + 3]!) >>> 0
+const le16 = (b: Uint8Array, at: number) => b[at]! | (b[at + 1]! << 8)
+const le24 = (b: Uint8Array, at: number) => b[at]! | (b[at + 1]! << 8) | (b[at + 2]! << 16)
+const le32 = (b: Uint8Array, at: number) => (b[at]! | (b[at + 1]! << 8) | (b[at + 2]! << 16) | (b[at + 3]! << 24)) >>> 0
+
+/** An SVG document: optional BOM, XML declaration, comments and doctype, then the root `<svg`. */
+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
+
+/** The image type of `bytes` by their magic bytes, else undefined. */
+export function sniffMime(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"
+  const head = new TextDecoder("utf-8", { fatal: false }).decode(bytes.subarray(0, SVG_SNIFF_BYTES))
+  if (SVG_START.test(head)) return "image/svg+xml"
+  return undefined
+}
+
+/** A raster image's width and height from its (complete) header; undefined when it is truncated, malformed or SVG. */
+export function imageDimensions(bytes: Uint8Array, mime: string): Dimensions | undefined {
+  switch (mime) {
+    case "image/png":
+      // Signature, then the IHDR chunk (length, type, 13 bytes of data, CRC).
+      if (bytes.length < 33 || !ascii(bytes, 12, "IHDR")) return undefined
+      return { width: be32(bytes, 16), height: be32(bytes, 20) }
+    case "image/gif":
+      // Header and the whole logical screen descriptor.
+      if (bytes.length < 13) return undefined
+      return { width: le16(bytes, 6), height: le16(bytes, 8) }
+    case "image/webp":
+      return webpDimensions(bytes)
+    case "image/jpeg":
+      return jpegDimensions(bytes)
+    default:
+      return undefined
+  }
+}
+
+function webpDimensions(b: Uint8Array): Dimensions | undefined {
+  if (b.length < 20) return undefined
+  const size = le32(b, 16)
+  if (ascii(b, 12, "VP8 ")) {
+    // Frame tag (3 bytes), start code 9d 01 2a, then 14-bit width and height.
+    if (size < 10 || b.length < 30 || b[23] !== 0x9d || b[24] !== 0x01 || b[25] !== 0x2a) return undefined
+    return { width: le16(b, 26) & 0x3fff, height: le16(b, 28) & 0x3fff }
+  }
+  if (ascii(b, 12, "VP8L")) {
+    if (size < 5 || b.length < 25 || b[20] !== 0x2f) return undefined
+    const bits = le32(b, 21)
+    return { width: (bits & 0x3fff) + 1, height: ((bits >>> 14) & 0x3fff) + 1 }
+  }
+  if (ascii(b, 12, "VP8X")) {
+    if (size < 10 || b.length < 30) return undefined
+    return { width: le24(b, 24) + 1, height: le24(b, 27) + 1 }
+  }
+  return undefined
+}
+
+/** Start-of-frame markers (every SOFn except DHT C4, JPG C8 and DAC CC). */
+const isSOF = (marker: number) => marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc
+
+function jpegDimensions(b: Uint8Array): Dimensions | undefined {
+  if (b.length < 4 || b[0] !== 0xff || b[1] !== 0xd8) return undefined
+  let at = 2
+  while (at < b.length) {
+    if (b[at] !== 0xff) return undefined
+    while (at < b.length && b[at] === 0xff) at++
+    if (at >= b.length) return undefined
+    const marker = b[at]!
+    at++
+    // Markers without a length: TEM, RSTn, SOI. EOI or SOS before a frame: no dimensions.
+    if (marker === 0x01 || (marker >= 0xd0 && marker <= 0xd8)) continue
+    if (marker === 0xd9 || marker === 0xda) return undefined
+    if (at + 2 > b.length) return undefined
+    const length = be16(b, at)
+    if (length < 2) return undefined
+    if (isSOF(marker)) {
+      // Length, precision, height, width.
+      if (length < 7 || at + 7 > b.length) return undefined
+      return { width: be16(b, at + 5), height: be16(b, at + 3) }
+    }
+    at += length
+  }
+  return undefined
+}
+
+const EXTENSIONS: Readonly<Record<string, MediaMime>> = {
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  webp: "image/webp",
+  gif: "image/gif",
+  svg: "image/svg+xml",
+}
+
+/** The image type a path's extension claims, else undefined. */
+export function mimeOfPath(path: string): MediaMime | undefined {
+  const match = /\.([A-Za-z0-9]+)$/.exec(path)
+  return match ? EXTENSIONS[match[1]!.toLowerCase()] : undefined
+}
+
+/** A claimed mime as one of MEDIA_MIMES (image/jpg is image/jpeg), else undefined. */
+export function mediaMime(claim: string | undefined): MediaMime | undefined {
+  const mime = (claim ?? "").trim().toLowerCase().split(";")[0]!.trim()
+  const normal = mime === "image/jpg" ? "image/jpeg" : mime
+  return (MEDIA_MIMES as readonly string[]).includes(normal) ? (normal as MediaMime) : undefined
+}
+
+export type ImageCheck = { readonly ok: { readonly mime: MediaMime } & Partial<Dimensions> } | { readonly refused: "type" | "dimensions" }
+
+/**
+ * Whether `bytes` may be served as `claim`: the claim is an allowed type and the magic bytes match it ("type"
+ * otherwise, also for a raster image whose header has no readable dimensions), and a raster image fits
+ * MEDIA_LIMITS' sides and pixels ("dimensions" otherwise).
+ */
+export function checkImage(bytes: Uint8Array, claim: string): ImageCheck {
+  const mime = mediaMime(claim)
+  if (!mime || sniffMime(bytes) !== mime) return { refused: "type" }
+  if (mime === "image/svg+xml") return { ok: { mime } }
+  const dims = imageDimensions(bytes, mime)
+  if (!dims || dims.width < 1 || dims.height < 1) return { refused: "type" }
+  if (dims.width > MEDIA_LIMITS.maxSide || dims.height > MEDIA_LIMITS.maxSide || dims.width * dims.height > MEDIA_LIMITS.maxPixels) return { refused: "dimensions" }
+  return { ok: { mime, ...dims } }
+}
+
+const DATA_URI = /^data:([^;,]*)((?:;[^;,]*)*);base64,([A-Za-z0-9+/=_-]*)$/i
+
+/** The parts of a base64 `data:` URI, else undefined. */
+export function parseDataURI(uri: string): { mime: string; base64: string } | undefined {
+  const match = DATA_URI.exec(uri)
+  return match ? { mime: match[1]!.toLowerCase(), base64: match[3]! } : undefined
+}
+
+/** The decoded size of base64 text (padding and URL-safe alphabet allowed). */
+export function base64Bytes(base64: string): number {
+  const body = base64.replace(/=+$/, "")
+  return Math.floor((body.length * 3) / 4)
+}
+
+/** The first bytes of base64 text (at most `max`), for header sniffing without decoding all of it. */
+export function base64Head(base64: string, max = HEAD_BYTES): Uint8Array {
+  const chars = Math.ceil(max / 3) * 4
+  return Uint8Array.from(Buffer.from(base64.slice(0, chars), base64.includes("-") || base64.includes("_") ? "base64url" : "base64"))
+}
+
+/** Bytes read to find a header's dimensions (a JPEG's frame may follow large EXIF segments). */
+const HEAD_BYTES = 96 * 1024
+
+/** A raster image's header dimensions from the start of its base64, when the bytes are the claimed type. */
+export function base64Dimensions(base64: string, claim: string): Partial<Dimensions> {
+  const mime = mediaMime(claim)
+  if (!mime || mime === "image/svg+xml") return {}
+  const head = base64Head(base64)
+  if (sniffMime(head) !== mime) return {}
+  return imageDimensions(head, mime) ?? {}
+}

package/src/spoke/media-policy.ts

@@ -0,0 +1,394 @@
+// (S4 M2, design §1) The path policy of `p:` media refs: which local image files an assistant message may show.
+//
+// 1. The path must be the source of a markdown image in that message's own text (re-parsed here, so the console
+//    cannot name an arbitrary path). `~` is never expanded; remote and other URL schemes are not paths.
+// 2. After realpath (symlinks resolved), the file must be under the session's directory (its `.worktrees/` too),
+//    or in the session's touched set: the paths of its own read/write/edit calls and the names of tool file outputs.
+// 3. A path with a segment starting with "." (`.git/`, `.env`, …) below the directory is refused unless the file is
+//    in the touched set. 4. Regular files only, and the open file must be what the checked realpath names
+//    (openChecked: on macOS the real path is opened with no symlink anywhere in it; elsewhere the path is opened first
+//    without following a final symlink, then checked). The bytes are checked in media-bytes.ts.
+import { constants, type Stats } from "node:fs"
+import { lstat, open, readlink, realpath, stat, type FileHandle } from "node:fs/promises"
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path"
+import { fileURLToPath } from "node:url"
+import { parseMarkdown, type Inline, type MdBlock } from "../../packages/protocol/src/markdown.ts"
+import { MEDIA_LIMITS } from "../protocol"
+
+const record = (value: unknown): Record<string, any> => (value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, any>) : {})
+
+/**
+ * Text with indented code blocks (4+ spaces or a tab after a blank line, outside fences) blanked: parseMarkdown keeps
+ * them as paragraphs, but such a line is code to CommonMark and to whoever wrote it, so its images never count.
+ */
+export function withoutIndentedCode(text: string): string {
+  const lines: string[] = []
+  let fence: string | undefined
+  let blank = true
+  let indented = false
+  for (const line of text.split("\n")) {
+    const open = /^ {0,3}(`{3,}|~{3,})/.exec(line)
+    const isBlank = line.trim() === ""
+    if (!fence && !isBlank && /^(?: {4}|\t)/.test(line) && (blank || indented)) {
+      indented = true
+      blank = false
+      lines.push("")
+      continue
+    }
+    if (!isBlank) indented = false
+    blank = isBlank
+    if (fence) {
+      if (open && open[1]![0] === fence[0] && open[1]!.length >= fence.length && line.trim() === open[1]) fence = undefined
+    } else if (open) fence = open[1]
+    lines.push(line)
+  }
+  return lines.join("\n")
+}
+
+/** The sources of the image nodes of a parsed tree (link labels, lists, quotes and tables too), in order. */
+function imagesOf(blocks: readonly MdBlock[], out: string[] = []): string[] {
+  const inline = (nodes: readonly Inline[]) => {
+    for (const node of nodes) {
+      if (node.type === "image") out.push(node.src)
+      else if ("children" in node) inline(node.children)
+    }
+  }
+  for (const block of blocks) {
+    if (block.type === "paragraph" || block.type === "heading") inline(block.children)
+    else if (block.type === "quote") imagesOf(block.blocks, out)
+    else if (block.type === "list") for (const item of block.items) imagesOf(item.blocks, out)
+    else if (block.type === "table") for (const row of [block.head, ...block.rows]) for (const cell of row) inline(cell)
+  }
+  return out
+}
+
+/**
+ * Backstops (the parser is linear, but it runs synchronously in the harness's process on every timeline build): only
+ * the first 64 KiB characters of a text, up to its last blank line there (scannedPart), are read for images, and at
+ * most MEDIA_LIMITS.perRow sources are kept (a row lists no more). An image past either limit is neither listed nor
+ * served.
+ */
+const IMAGE_SCAN_CHARS = 64 * 1024
+
+/** A blank line (only spaces, tabs or a CR on it), as the parser sees one. */
+const BLANK_LINE = /\n[ \t\r]*\n/g
+
+/**
+ * The part of a text read for images: all of it up to IMAGE_SCAN_CHARS, else what comes before its last blank line
+ * within the first IMAGE_SCAN_CHARS (nothing when there is none), so the cut never splits a paragraph and the code
+ * spans in it. A fence still open at the cut makes the rest code: fewer images, never more.
+ */
+export function scannedPart(text: string): string {
+  if (text.length <= IMAGE_SCAN_CHARS) return text
+  const head = text.slice(0, IMAGE_SCAN_CHARS)
+  let cut = 0
+  BLANK_LINE.lastIndex = 0
+  for (let m = BLANK_LINE.exec(head); m; m = BLANK_LINE.exec(head)) {
+    cut = m.index
+    BLANK_LINE.lastIndex = m.index + 1
+  }
+  return head.slice(0, cut)
+}
+
+/**
+ * The image sources (`![alt](src)`) of markdown text, in order, without duplicates, as the console's parser
+ * (parseMarkdown, packages/protocol) reads them: never in fenced code, code spans or after a backslash escape. The
+ * console does not render reference images (`![alt][ref]`), so they are not sources either. Indented code is left
+ * out as well: a source counts only when the text without indented code (withoutIndentedCode) still has it.
+ */
+export function markdownImageSources(markdown: string): string[] {
+  const text = scannedPart(markdown)
+  if (!text.includes("![")) return []
+  const outsideIndented = new Set(imagesOf(parseMarkdown(withoutIndentedCode(text))))
+  const out: string[] = []
+  for (const src of imagesOf(parseMarkdown(text))) {
+    if (src && outsideIndented.has(src) && !out.includes(src)) out.push(src)
+    if (out.length >= MEDIA_LIMITS.perRow) break
+  }
+  return out
+}
+
+const SCHEME = /^[A-Za-z][A-Za-z0-9+.-]*:/
+
+/**
+ * The absolute (not yet realpath'd) path an image source names, relative ones against `directory`: plain paths and
+ * local `file:` URLs. Undefined for `~` paths (never expanded), remote and other URLs, and empty or NUL sources.
+ */
+export function sourcePath(src: string, directory: string): string | undefined {
+  if (!src || src.includes("\u0000") || src.startsWith("~")) return undefined
+  if (SCHEME.test(src)) {
+    if (!/^file:/i.test(src)) return undefined
+    try {
+      const url = new URL(src)
+      if (url.hostname !== "" && url.hostname !== "localhost") return undefined
+      const path = fileURLToPath(url)
+      return path.includes("\u0000") ? undefined : path
+    } catch {
+      return undefined
+    }
+  }
+  return resolve(directory, src)
+}
+
+const TOUCHING_TOOLS = new Set(["read", "write", "edit"])
+const PATH_KEYS = ["filePath", "path", "file_path"] as const
+
+/**
+ * The session's touched set: the paths of its own completed read/write/edit calls and the names of those calls' file
+ * outputs (the file actually read). A denied, failed or unfinished call touches nothing; other tools (bash, MCP)
+ * never widen disk access (their own file outputs are served by their t<part>.<item> refs).
+ */
+export function touchedPaths(messages: readonly unknown[], directory: string): string[] {
+  const out = new Set<string>()
+  const add = (value: unknown) => {
+    const path = typeof value === "string" ? sourcePath(value, directory) : undefined
+    if (path) out.add(path)
+  }
+  for (const raw of messages) {
+    const message = record(raw)
+    if (message.type !== "assistant" || !Array.isArray(message.content)) continue
+    for (const part of message.content) {
+      const state = record(record(part).state)
+      if (part.type !== "tool" || state.status !== "completed" || !TOUCHING_TOOLS.has(String(part.name ?? "").toLowerCase())) continue
+      const input = record(state.input)
+      for (const key of PATH_KEYS) add(input[key])
+      if (Array.isArray(state.content)) for (const item of state.content) if (record(item).type === "file") add(record(item).name)
+    }
+  }
+  return [...out]
+}
+
+/** A served path: its real path and the open file's device and inode. */
+export type PathCheck = { readonly path: string; readonly dev: number; readonly ino: number } | { readonly refused: "path" }
+
+const REFUSED = { refused: "path" } as const
+
+/** Never follow a final symlink, never block (a FIFO opens at once and is refused as not a regular file). */
+const OPEN_FLAGS = constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0)
+
+/**
+ * macOS 11+ (<sys/fcntl.h>): open(2) fails with ELOOP when any component of the path is a symlink, not only the last.
+ * Node does not export it. Older macOS refuses it with EINVAL (then the Linux order below is used, without /proc).
+ */
+const O_NOFOLLOW_ANY = 0x20000000
+
+/** The file system calls and platform openChecked uses; tests replace them to change the tree between lookups. */
+export interface MediaFs {
+  readonly realpath?: typeof realpath
+  readonly open?: (path: string, flags: number) => Promise<FileHandle>
+  readonly readlink?: (path: string) => Promise<string>
+  readonly platform?: NodeJS.Platform
+}
+
+type Fs = Required<MediaFs>
+
+export interface MediaPathInput {
+  readonly src: string
+  readonly text: string
+  readonly directory: string
+  readonly touched: readonly string[]
+  /** For tests: the file system calls and platform to use (defaults: node:fs/promises, process.platform). */
+  readonly fs?: MediaFs
+}
+
+/** Whether a real path is under the real directory with no dot segment (but a leading .worktrees). */
+function insideClean(real: string, realDir: string): boolean {
+  const rel = relative(realDir, real)
+  const inside = rel !== "" && rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel)
+  return inside && !rel.split(sep).some((segment, index) => segment.startsWith(".") && !(index === 0 && segment === ".worktrees"))
+}
+
+/** Whether a real path may be served: under the directory (no dot segment but a leading .worktrees), or touched. */
+async function allowed(real: string, input: PolicyContext, resolveReal: typeof realpath): Promise<boolean> {
+  const realDir = await resolveReal(input.directory).catch(() => undefined)
+  if (!realDir) return false
+  if (insideClean(real, realDir)) return true
+  if (input.touchedReal) return input.touchedReal.has(real)
+  const reals = await Promise.all(input.touched.map((p) => resolveReal(resolve(input.directory, p)).catch(() => undefined)))
+  return reals.includes(real)
+}
+
+/**
+ * The context with the touched set's real paths resolved once (and the directory's), for callers that check many
+ * paths (a preview bundle walk): allowed() then looks them up instead of resolving every touched path per check.
+ */
+export async function resolvedPolicy(input: PolicyContext): Promise<PolicyContext> {
+  const resolveReal = input.fs?.realpath ?? realpath
+  const reals = await Promise.all(input.touched.map((p) => resolveReal(resolve(input.directory, p)).catch(() => undefined)))
+  const realDir = await resolveReal(input.directory).catch(() => undefined)
+  return { ...input, touchedReal: new Set(reals.filter((r): r is string => r !== undefined)), ...(realDir ? { realDir } : {}) }
+}
+
+/**
+ * Whether an absolute path that cannot be opened is missing where the policy would allow it: nothing is at `path`,
+ * and its nearest existing ancestor's real path plus the rest of `path` lies under the directory with no dot segment.
+ * Anything else (outside, a dot segment, a symlinked directory leaving the workspace, a missing touched file) is not
+ * told apart from a refusal, so a preview never reveals whether a file outside the policy exists. At most `maxSteps`
+ * ancestors are looked up.
+ */
+export async function missingAllowed(path: string, input: PolicyContext, maxSteps = 64): Promise<boolean> {
+  const resolveReal = input.fs?.realpath ?? realpath
+  const realDir = input.realDir ?? (await resolveReal(input.directory).catch(() => undefined))
+  if (!realDir) return false
+  const gone = (e: NodeJS.ErrnoException) => e?.code === "ENOENT"
+  if (!(await lstat(path).then(() => false, gone))) return false
+  let ancestor = dirname(path)
+  for (let step = 0; step < maxSteps; step++) {
+    const info = await lstat(ancestor).catch((e: NodeJS.ErrnoException) => (gone(e) ? undefined : null))
+    if (info === null) return false
+    if (info) {
+      if (!info.isDirectory() && !info.isSymbolicLink()) return false
+      const real = await resolveReal(ancestor).catch(() => undefined)
+      return real !== undefined && insideClean(join(real, relative(ancestor, path)), realDir)
+    }
+    const up = dirname(ancestor)
+    if (up === ancestor) return false
+    ancestor = up
+  }
+  return false
+}
+
+type Opened = { path: string; handle: FileHandle; info: Stats }
+
+/** Where a policy check runs: the session's directory and touched set (and, for tests, the file system calls). */
+export type PolicyContext = Pick<MediaPathInput, "directory" | "touched" | "fs"> & {
+  /** The touched set's real paths, resolved once (resolvedPolicy). */
+  readonly touchedReal?: ReadonlySet<string>
+  /** The directory's real path, resolved once (resolvedPolicy; missingAllowed only, allowed() resolves it per check). */
+  readonly realDir?: string
+}
+
+/**
+ * Opens the image source `src` of a message whose text is `text` when it may be served. A process in the workspace
+ * may swap files and directories between lookups, so the open file itself is checked (see openAllowed).
+ * The caller reads only from the returned handle and closes it.
+ */
+async function openChecked(input: MediaPathInput): Promise<Opened | typeof REFUSED> {
+  if (!markdownImageSources(input.text).includes(input.src)) return REFUSED
+  const path = sourcePath(input.src, input.directory)
+  if (!path) return REFUSED
+  return openAllowed(path, input)
+}
+
+/**
+ * Opens the absolute `path` when the path policy allows it (rules 2–4 above; whoever calls checks rule 1, that the
+ * message names it), in the platform's order below. The caller reads only from the returned handle and closes it.
+ */
+export async function openAllowed(path: string, input: PolicyContext): Promise<Opened | typeof REFUSED> {
+  const fs: Fs = {
+    realpath: input.fs?.realpath ?? realpath,
+    open: input.fs?.open ?? ((p, flags) => open(p, flags)),
+    readlink: input.fs?.readlink ?? ((p) => readlink(p)),
+    platform: input.fs?.platform ?? process.platform,
+  }
+  if (fs.platform === "darwin") {
+    const opened = await openRealNoSymlinks(path, input, fs)
+    if (opened !== "unsupported") return opened
+  }
+  return openThenCheck(path, input, fs)
+}
+
+/**
+ * macOS: realpath first, the policy on the real path, then open exactly that path with O_NOFOLLOW_ANY (no symlink
+ * anywhere in it, so no swapped parent directory can redirect the open), a regular file with the real path's device
+ * and inode. "unsupported" when the kernel does not know the flag.
+ */
+async function openRealNoSymlinks(path: string, input: PolicyContext, fs: Fs): Promise<Opened | typeof REFUSED | "unsupported"> {
+  // A final symlink is refused as on the other platforms (O_NOFOLLOW there); not for safety, the real path is checked.
+  if ((await lstat(path).catch(() => undefined))?.isSymbolicLink()) return REFUSED
+  const real = await fs.realpath(path).catch(() => undefined)
+  if (!real || !(await allowed(real, input, fs.realpath))) return REFUSED
+  let handle: FileHandle
+  try {
+    handle = await fs.open(real, OPEN_FLAGS | O_NOFOLLOW_ANY)
+  } catch (error) {
+    return (error as NodeJS.ErrnoException)?.code === "EINVAL" ? "unsupported" : REFUSED
+  }
+  return identified(real, handle)
+}
+
+/**
+ * Linux, Windows and the rest: the requested path is opened first, without following a final symlink and without
+ * blocking, and must be a regular file; only then is its realpath checked against the policy, and the realpath's
+ * device and inode must be the open file's. On Linux the kernel's path of the open file (/proc/self/fd) must also be
+ * the realpath, and a failing readlink refuses. Elsewhere there is no such path: on Windows (no O_NOFOLLOW, no
+ * O_NOFOLLOW_ANY) a parent directory swapped three times (a symlink to a file outside when opened, the directory
+ * during realpath, the symlink again for the identity check) can still serve a file outside the workspace; so can
+ * macOS before 11. Bun itself needs macOS 13+, where the O_NOFOLLOW_ANY order above applies.
+ */
+async function openThenCheck(path: string, input: PolicyContext, fs: Fs): Promise<Opened | typeof REFUSED> {
+  const handle = await fs.open(path, OPEN_FLAGS).catch(() => undefined)
+  if (!handle) return REFUSED
+  const real = await checkedReal(path, handle, input, fs).catch(() => undefined)
+  if (!real) {
+    await handle.close().catch(() => {})
+    return REFUSED
+  }
+  return identified(real, handle)
+}
+
+/** The realpath of the opened `path` when the policy allows it (and, on Linux, /proc names it for the open file). */
+async function checkedReal(path: string, handle: FileHandle, input: PolicyContext, fs: Fs): Promise<string | undefined> {
+  if (!(await handle.stat()).isFile()) return undefined
+  const real = await fs.realpath(path).catch(() => undefined)
+  if (!real || !(await allowed(real, input, fs.realpath))) return undefined
+  if (fs.platform === "linux" && (await fs.readlink(`/proc/self/fd/${handle.fd}`).catch(() => undefined)) !== real) return undefined
+  return real
+}
+
+/** The open file when it is regular and `real` names it now (same device and inode); else closed and refused. */
+async function identified(real: string, handle: FileHandle): Promise<Opened | typeof REFUSED> {
+  try {
+    const info = await handle.stat()
+    const named = await stat(real).catch(() => undefined)
+    if (info.isFile() && named && named.dev === info.dev && named.ino === info.ino) return { path: real, handle, info }
+  } catch {}
+  await handle.close().catch(() => {})
+  return REFUSED
+}
+
+/** Whether the image source `src` may be served (its real path and the file's identity), else refused. */
+export async function checkMediaPath(input: MediaPathInput): Promise<PathCheck> {
+  const opened = await openChecked(input)
+  if ("refused" in opened) return opened
+  await opened.handle.close()
+  return { path: opened.path, dev: opened.info.dev, ino: opened.info.ino }
+}
+
+/**
+ * The bytes of the image source `src` (openChecked), read only from the checked handle and never more than `max`:
+ * `tooLarge` with the size seen when it is (or grows) larger; refused when it changes size while it is read.
+ */
+export async function readMediaPath(input: MediaPathInput & { readonly max: number }): Promise<ReadResult> {
+  const opened = await openChecked(input)
+  return "refused" in opened ? opened : readOpened(opened, input.max)
+}
+
+export type ReadResult = { path: string; bytes: Uint8Array } | { tooLarge: number } | typeof REFUSED
+
+/** The bytes of the absolute `path` when the path policy allows it (openAllowed), as readMediaPath reads them. */
+export async function readAllowedPath(path: string, input: PolicyContext & { readonly max: number }): Promise<ReadResult> {
+  const opened = await openAllowed(path, input)
+  return "refused" in opened ? opened : readOpened(opened, input.max)
+}
+
+async function readOpened({ handle, info, path }: Opened, max: number): Promise<ReadResult> {
+  try {
+    if (info.size > max) return { tooLarge: info.size }
+    // One byte more than the file had: reading it means the file grew while it was read.
+    const buffer = new Uint8Array(info.size + 1)
+    let length = 0
+    while (length < buffer.length) {
+      const { bytesRead } = await handle.read(buffer, length, buffer.length - length, length)
+      if (bytesRead === 0) break
+      length += bytesRead
+    }
+    if (length !== info.size) {
+      const now = (await handle.stat()).size
+      return now > max ? { tooLarge: now } : REFUSED
+    }
+    return { path, bytes: buffer.subarray(0, length) }
+  } finally {
+    await handle.close()
+  }
+}