@oar-sh/oar 0.9.24 → 0.9.25

package/server/repositories/media-repository.mjs

@@ -0,0 +1,305 @@
+'use strict';
+
+// The media gallery index (migration 0039): the queue of messages to
+// (re)index and the `media_items` rows made from them. Every reader tolerates
+// a schema without the migration: it then sees an empty index and writes
+// nothing.
+
+export const MEDIA_PENDING_COUNT_CAP = 10_000;
+
+function tableExists(db, name) {
+  return !!db.prepare(`SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?`).get(name);
+}
+
+function columnsOf(db, table) {
+  return db.prepare(`PRAGMA table_info(${table})`).all().map((column) => column.name);
+}
+
+/** Who a message comes from, for the Source filter: the owner, an agent, or the relay itself. */
+export function mediaSenderFor({ role, kind, originJson }) {
+  if (role === 'assistant') return 'agent';
+  if (role === 'user' && !kind && !originJson) return 'me';
+  return 'relay';
+}
+
+export function createMediaRepository(db) {
+  const available = tableExists(db, 'media_items')
+    && tableExists(db, 'media_index_queue')
+    && tableExists(db, 'messages');
+  if (!available) {
+    return {
+      available: false,
+      nextQueueBatch: () => [],
+      loadQueuedMessage: () => null,
+      replaceMessageItems: () => 0,
+      pendingCount: () => 0,
+      hasPending: () => false,
+      removeOrphanQueueRows: () => 0,
+      inTransaction: (fn) => fn(),
+      listMedia: () => [],
+      countMedia: () => ({ media: 0, file: 0 }),
+      mediaFacets: () => ({ sessions: [], providers: [] }),
+      getMediaItem: () => null,
+    };
+  }
+  const messageColumns = columnsOf(db, 'messages');
+  // octet_length reads a value's size without reading the value (SQLite 3.43+).
+  let hasOctetLength = true;
+  try {
+    db.prepare(`SELECT octet_length('x')`).get();
+  } catch {
+    hasOctetLength = false;
+  }
+  const sizeOf = (column) => (hasOctetLength ? `octet_length(${column})` : `length(${column})`);
+  const conversationColumns = columnsOf(db, 'conversations');
+  const optional = (columns, column, alias) => (columns.includes(column) ? `${alias}.${column}` : 'NULL');
+  const workspaceRoot = `COALESCE(${optional(conversationColumns, 'runtime_workspace_root_path', 'c')}, ${optional(conversationColumns, 'configured_workspace_root_path', 'c')})`;
+
+  const statements = {
+    // Queue order is the rowid (insertion order); no sort over the queue.
+    // Ids and body sizes only: a batch never loads message bodies, which can be
+    // megabytes (a pasted data image); the indexer loads them one by one.
+    nextBatch: db.prepare(`
+      SELECT q.message_id AS messageId, q.seq AS seq,
+             ${sizeOf('m.text')} + COALESCE(${sizeOf('m.attachments')}, 0) AS bytes
+        FROM media_index_queue q
+        JOIN messages m ON m.id = q.message_id
+       ORDER BY q.rowid
+       LIMIT ?
+    `),
+    loadMessage: db.prepare(`
+      SELECT m.id AS messageId,
+             m.conversation_id AS conversationId, m.role AS role, m.text AS text,
+             m.attachments AS attachments, m.timestamp AS timestamp,
+             ${optional(messageColumns, 'kind', 'm')} AS kind,
+             ${optional(messageColumns, 'origin_json', 'm')} AS originJson,
+             ${workspaceRoot} AS workspaceRoot
+        FROM messages m
+        LEFT JOIN conversations c ON c.id = m.conversation_id
+       WHERE m.id = ?
+    `),
+    deleteItems: db.prepare(`DELETE FROM media_items WHERE message_id = ?`),
+    insertItem: db.prepare(`
+      INSERT INTO media_items (message_id, conversation_id, ordinal, role, sender, origin, locator_kind, locator,
+        identity_key, category, media_kind, mime, name, alt, size_bytes, message_ts)
+      VALUES (@messageId, @conversationId, @ordinal, @role, @sender, @origin, @locatorKind, @locator,
+        @identityKey, @category, @mediaKind, @mime, @name, @alt, @sizeBytes, @messageTs)
+    `),
+    // Only the queue row that was read: a re-queue meanwhile bumped `seq`
+    // and keeps the row for the next batch.
+    deleteQueueRow: db.prepare(`DELETE FROM media_index_queue WHERE message_id = ? AND seq = ?`),
+    // Capped: a full count over a large backfill queue costs tens of ms.
+    pending: db.prepare(`SELECT COUNT(*) AS n FROM (SELECT 1 FROM media_index_queue LIMIT ${MEDIA_PENDING_COUNT_CAP + 1})`),
+    hasPending: db.prepare(`SELECT EXISTS (SELECT 1 FROM media_index_queue) AS present`),
+    // Rows whose message is gone while foreign keys were off (an outside tool).
+    removeOrphans: db.prepare(`DELETE FROM media_index_queue WHERE message_id NOT IN (SELECT id FROM messages)`),
+  };
+
+  const replace = db.transaction((row, items) => {
+    statements.deleteItems.run(row.messageId);
+    const sender = mediaSenderFor(row);
+    for (const item of items) {
+      statements.insertItem.run({
+        messageId: row.messageId,
+        conversationId: row.conversationId,
+        ordinal: item.ordinal,
+        role: String(row.role || ''),
+        sender,
+        origin: item.origin,
+        locatorKind: item.locatorKind,
+        locator: item.locator,
+        identityKey: item.identityKey,
+        category: item.category,
+        mediaKind: item.mediaKind,
+        mime: item.mime ?? null,
+        name: item.name ?? null,
+        alt: item.alt ?? null,
+        sizeBytes: Number.isFinite(item.sizeBytes) ? item.sizeBytes : null,
+        messageTs: String(row.timestamp || ''),
+      });
+    }
+    statements.deleteQueueRow.run(row.messageId, row.seq);
+    return items.length;
+  });
+
+  return {
+    available: true,
+    /** Queued messages in queue order: `{ messageId, seq, bytes }`, no bodies. */
+    nextQueueBatch: (limit = 200) => statements.nextBatch.all(Math.max(1, Math.min(1000, Number(limit) || 200))),
+    /** A queued message with what the indexer needs; null when it is gone. */
+    loadQueuedMessage: (entry) => {
+      const row = statements.loadMessage.get(entry.messageId);
+      return row ? { ...row, seq: entry.seq } : null;
+    },
+    /** Replaces the rows of one queued message and removes its queue row, in one transaction. */
+    replaceMessageItems: (row, items) => replace(row, items),
+    /** Queued messages, counted up to MEDIA_PENDING_COUNT_CAP + 1 (that value means "more"). */
+    pendingCount: () => statements.pending.get().n,
+    hasPending: () => statements.hasPending.get().present === 1,
+    removeOrphanQueueRows: () => statements.removeOrphans.run().changes,
+    /** Runs `fn` in one transaction (one commit for a whole slice of messages). */
+    inTransaction: (fn) => db.transaction(fn)(),
+    ...createMediaQueries(db),
+  };
+}
+
+// --- reading the gallery ---------------------------------------------------
+
+export const MEDIA_SOURCES = Object.freeze(['all', 'mine', 'agent', 'generated']);
+export const MEDIA_PAGE_MAX = 120;
+
+function escapeLike(value) {
+  return String(value).replace(/[\\%_]/g, (ch) => `\\${ch}`);
+}
+
+/** Opaque page cursor: the (message time, id) of the last item of a page. */
+export function encodeMediaCursor(item) {
+  return Buffer.from(JSON.stringify([item.timestamp, item.id]), 'utf8').toString('base64url');
+}
+
+export function decodeMediaCursor(raw) {
+  if (!raw) return null;
+  try {
+    const [timestamp, id] = JSON.parse(Buffer.from(String(raw), 'base64url').toString('utf8'));
+    if (typeof timestamp !== 'string' || !Number.isSafeInteger(id)) return null;
+    return { timestamp, id };
+  } catch {
+    return null;
+  }
+}
+
+function createMediaQueries(db) {
+  const runtimeColumns = tableExists(db, 'runtime_sessions') ? columnsOf(db, 'runtime_sessions') : [];
+  // The session's provider, as the sidebar shows it (github when unknown).
+  const providerExpr = runtimeColumns.includes('provider_type')
+    ? `COALESCE((SELECT rs.provider_type FROM runtime_sessions rs WHERE rs.conversation_id = c.id AND rs.provider_type IS NOT NULL ORDER BY rs.last_used_at DESC LIMIT 1), 'github')`
+    : `'github'`;
+  const cache = new Map();
+  const prepared = (key, sql) => {
+    if (!cache.has(key)) cache.set(key, db.prepare(sql));
+    return cache.get(key);
+  };
+
+  const providerFor = (c) => providerExpr.replace('rs.conversation_id = c.id', `rs.conversation_id = ${c}.id`);
+
+  // The scope's conditions for a media row `mi` of a session `c` (aliases
+  // given, so the dedupe check can ask them of another row).
+  function scopeClauses({ conversationId, source, provider, archived, q }, params, mi = 'mi', c = 'c') {
+    const where = [`${c}.status != 'deleted'`];
+    const key = [];
+    if (conversationId) {
+      where.push(`${mi}.conversation_id = @conversationId`);
+      params.conversationId = String(conversationId);
+      key.push('conv');
+    }
+    if (source === 'mine') { where.push(`${mi}.sender = 'me' AND ${mi}.origin != 'generated'`); key.push('mine'); }
+    if (source === 'agent') { where.push(`${mi}.sender != 'me' AND ${mi}.origin != 'generated'`); key.push('agent'); }
+    if (source === 'generated') { where.push(`${mi}.origin = 'generated'`); key.push('generated'); }
+    if (provider) {
+      where.push(`${providerFor(c)} = @provider`);
+      params.provider = String(provider);
+      key.push('provider');
+    }
+    if (archived === 'hide') { where.push(`${c}.archived = 0`); key.push('live'); }
+    const text = String(q || '').trim().slice(0, 200);
+    if (text) {
+      where.push(`(${mi}.name LIKE @q ESCAPE '\\' OR ${mi}.alt LIKE @q ESCAPE '\\' OR ${c}.title LIKE @q ESCAPE '\\')`);
+      params.q = `%${escapeLike(text)}%`;
+      key.push('q');
+    }
+    return { where: where.join(' AND '), key: key.join(',') };
+  }
+
+  /**
+   * One page of a gallery: each picture once (its newest occurrence in the
+   * scope), newest first. The rows are walked newest first along the time
+   * index and a row is kept when no newer row of the scope has its identity,
+   * so a page stops after `limit` hits instead of sorting the whole scope,
+   * and an older copy of a picture never comes back on a later page. The
+   * occurrences, the session's title and its provider are read for the
+   * page's rows alone.
+   */
+  function listMedia({ category = 'media', cursor = null, limit = 60, ...filters } = {}) {
+    const params = { category: category === 'file' ? 'file' : 'media', limit: Math.max(1, Math.min(MEDIA_PAGE_MAX, Number(limit) || 60)) };
+    const scope = scopeClauses(filters, params);
+    // For the other rows of an identity (n: a newer copy, o: every copy) the
+    // columns are written as +col: a unary plus keeps a column out of index
+    // lookups, so identity_key = ? is the only one left and the planner takes
+    // idx_media_items_identity by itself (an index hint would fail outright on
+    // a database that lacks the index; this falls back to a slower scan).
+    const newer = scopeClauses(filters, {}, '+n', 'cn');
+    const same = scopeClauses(filters, {}, '+o', 'co');
+    let after = '';
+    if (cursor) {
+      after = 'AND (mi.message_ts < @cursorTs OR (mi.message_ts = @cursorTs AND mi.id < @cursorId))';
+      params.cursorTs = cursor.timestamp;
+      params.cursorId = cursor.id;
+    }
+    const sql = `
+      SELECT mi.id, mi.conversation_id AS conversationId, mi.message_id AS messageId, mi.role, mi.sender, mi.origin,
+             mi.locator_kind AS locatorKind, mi.locator, mi.identity_key AS identityKey, mi.category,
+             mi.media_kind AS mediaKind, mi.mime, mi.name, mi.alt, mi.size_bytes AS sizeBytes,
+             mi.message_ts AS message_ts, c.title AS conversationTitle, c.archived AS archived,
+             ${providerFor('c')} AS provider,
+             (SELECT COUNT(*) FROM media_items o JOIN conversations co ON co.id = o.conversation_id
+               WHERE o.identity_key = mi.identity_key AND +o.category = mi.category AND ${same.where}) AS occurrences
+        FROM media_items mi
+        JOIN conversations c ON c.id = mi.conversation_id
+       WHERE mi.category = @category AND ${scope.where} ${after}
+         AND EXISTS (SELECT 1 FROM messages m WHERE m.id = mi.message_id)
+         AND NOT EXISTS (
+           SELECT 1 FROM media_items n JOIN conversations cn ON cn.id = n.conversation_id
+            WHERE n.identity_key = mi.identity_key AND +n.category = mi.category
+              AND (+n.message_ts, +n.id) > (mi.message_ts, mi.id)
+              AND ${newer.where})
+       ORDER BY mi.message_ts DESC, mi.id DESC
+       LIMIT @limit`;
+    const rows = prepared(`list:${scope.key}:${cursor ? 'c' : ''}`, sql).all(params);
+    return rows.map(({ message_ts: timestamp, archived, ...row }) => ({ ...row, timestamp, archived: archived === 1 }));
+  }
+  /** How many distinct pictures and files a scope has. */
+  function countMedia(filters = {}) {
+    const params = {};
+    const scope = scopeClauses(filters, params);
+    const sql = `
+      SELECT mi.category AS category, COUNT(DISTINCT mi.identity_key) AS n
+        FROM media_items mi
+        JOIN messages m ON m.id = mi.message_id
+        JOIN conversations c ON c.id = mi.conversation_id
+       WHERE ${scope.where}
+       GROUP BY mi.category`;
+    const counts = { media: 0, file: 0 };
+    for (const row of prepared(`count:${scope.key}`, sql).all(params)) counts[row.category] = row.n;
+    return counts;
+  }
+
+  /** Sessions and providers that have media, for the global filters. */
+  function mediaFacets() {
+    const sessions = prepared('facets:sessions', `
+      SELECT c.id AS id, c.title AS title, c.archived AS archived, ${providerExpr} AS provider,
+             COUNT(DISTINCT mi.identity_key) AS count, MAX(mi.message_ts) AS lastAt
+        FROM media_items mi
+        JOIN conversations c ON c.id = mi.conversation_id
+       WHERE c.status != 'deleted'
+       GROUP BY c.id
+       ORDER BY lastAt DESC
+       LIMIT 1000`).all().map((row) => ({ ...row, archived: row.archived === 1 }));
+    const providers = [...new Set(sessions.map((row) => row.provider).filter(Boolean))].sort();
+    return { sessions, providers };
+  }
+
+  /** One indexed item with what serving it needs; null when gone or its session is deleted. */
+  function getMediaItem(id) {
+    if (!Number.isSafeInteger(id) || id <= 0) return null;
+    return prepared('item', `
+      SELECT mi.id, mi.conversation_id AS conversationId, mi.message_id AS messageId, mi.locator_kind AS locatorKind,
+             mi.locator, mi.identity_key AS identityKey, mi.category, mi.media_kind AS mediaKind, mi.mime, mi.name,
+             m.text AS text, m.attachments AS attachments
+        FROM media_items mi
+        JOIN messages m ON m.id = mi.message_id
+        JOIN conversations c ON c.id = mi.conversation_id
+       WHERE mi.id = ? AND c.status != 'deleted'`).get(id) || null;
+  }
+
+  return { listMedia, countMedia, mediaFacets, getMediaItem };
+}

package/server/routes/media-routes.mjs

@@ -0,0 +1,361 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { promisify } from 'node:util';
+
+import { createMediaRepository, decodeMediaCursor, encodeMediaCursor, MEDIA_SOURCES } from '../repositories/media-repository.mjs';
+import { fileVersionToken, serveFileWithRangeSupport } from '../services/file-serving.mjs';
+import { DATA_IMAGE_MAGIC as IMAGE_MAGIC, findDataImage, isPseudoFileSystemPath } from '../services/media-extract.mjs';
+import { sniffMimeType } from '../services/mime-sniffer.mjs';
+import { createMediaIndexService } from '../services/media-index-service.mjs';
+import { applySafeServedContentHeaders } from '../services/safe-served-content.mjs';
+
+// The media gallery: the 🧠 Media tab of a session and the global Media view.
+// Owner only: every route sits behind `auth`; there is no shared-view or
+// remote-relay counterpart. Files are served by index id only, so a file
+// reaches the gallery only when a message really referenced it, and its
+// stored path is checked again on every request.
+
+const CONTENT_ADDRESSED_CACHE = 'private, max-age=31536000, immutable';
+const REVALIDATE_CACHE = 'private, no-cache';
+const DRIVES_TTL_MS = 60_000;
+const MAX_PAGE_ROUNDS = 5;
+// A file system call on a stored path that takes longer (an offline network
+// drive) counts as a missing file.
+const FS_TIMEOUT_MS = 1500;
+const SERVABLE_TTL_MS = 60_000;
+const SERVABLE_CACHE_MAX = 5000;
+// The JS realpath, not the native one: on Windows the native one turns a
+// mapped drive letter into its UNC path, which the drive check refuses.
+const realpathKeepingDrives = promisify(fs.realpath);
+const openFile = promisify(fs.open);
+const fstatFile = promisify(fs.fstat);
+const readFile = promisify(fs.read);
+const closeFile = (fd) => fs.close(fd, () => {});
+// O_NOFOLLOW where the platform has it: the checked path cannot become a link
+// between the check and the open.
+const OPEN_FLAGS = fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0);
+
+/** The promise's value, or allback after ms; onLate(value) gets a value that came too late. */
+function withTimeout(promise, ms, fallback, onLate = () => {}) {
+  let timedOut = false;
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      timedOut = true;
+      resolve(fallback);
+    }, ms);
+    timer.unref?.();
+    Promise.resolve(promise).then((value) => {
+      clearTimeout(timer);
+      if (timedOut) onLate(value);
+      else resolve(value);
+    }, () => {
+      clearTimeout(timer);
+      if (!timedOut) resolve(fallback);
+    });
+  });
+}
+
+/**
+ * The type to serve a local picture or video as, from its first bytes; '' when
+ * the bytes are not the kind its name promised (a text file renamed .png, an
+ * executable named .mp4): such a file is not served at all.
+ */
+export function sniffLocalMediaType(head, { mediaKind, mime }) {
+  const sniffed = sniffMimeType(head);
+  if (mediaKind === 'image') {
+    if (sniffed.startsWith('image/')) return sniffed;
+    if (mime === 'image/svg+xml') {
+      const text = head.toString('utf8').replace(/^/, '').trimStart().slice(0, 256).toLowerCase();
+      if (text.startsWith('<svg') || (text.startsWith('<?xml') && text.includes('<svg'))) return 'image/svg+xml';
+    }
+    return '';
+  }
+  if (mediaKind === 'video') {
+    if (sniffed.startsWith('video/')) return sniffed;
+    if (head.length > 4 && head[0] === 0x1a && head[1] === 0x45 && head[2] === 0xdf && head[3] === 0xa3) return 'video/webm';
+    if (head.length > 8 && head.subarray(4, 8).toString('latin1') === 'ftyp') return mime || 'video/mp4';
+    return '';
+  }
+  return '';
+}
+
+async function readHead(fd, length = 512) {
+  const buffer = Buffer.alloc(length);
+  const { bytesRead } = await readFile(fd, buffer, 0, length, 0);
+  return buffer.subarray(0, bytesRead);
+}
+
+function parseGeneratedLocator(locator) {
+  try {
+    const value = JSON.parse(locator);
+    return value && typeof value === 'object' ? value : {};
+  } catch {
+    return {};
+  }
+}
+
+function generatedFromMessage(attachments, imageId) {
+  let list = [];
+  try {
+    list = JSON.parse(attachments || '[]');
+  } catch {
+    return null;
+  }
+  if (!Array.isArray(list)) return null;
+  const entry = list.find((item) => item?.generatedImage && String(item.generatedImage.imageId || '') === String(imageId || ''));
+  return entry?.generatedImage || null;
+}
+
+export function registerMediaRoutes(app, {
+  auth,
+  db,
+  uploadPathForSha,
+  fetchBrowsableDrives = null,
+  resolveGeneratedImagePath = () => null,
+  platform = process.platform,
+  repository = createMediaRepository(db),
+  indexService = createMediaIndexService({ db, repository, platform }),
+  startIndexer = true,
+  now = () => Date.now(),
+} = {}) {
+  let drivesCache = null;
+
+  // Windows: the drive roots a stored path may live on, cached a minute
+  // (listing them starts a process).
+  function allowedDriveRoots() {
+    if (platform !== 'win32' || typeof fetchBrowsableDrives !== 'function') return Promise.resolve(null);
+    if (drivesCache && now() - drivesCache.at < DRIVES_TTL_MS) return Promise.resolve(drivesCache.roots);
+    return new Promise((resolve) => {
+      fetchBrowsableDrives((error, drives) => {
+        if (error || !Array.isArray(drives)) return resolve(new Set());
+        const roots = new Set(drives.map((drive) => String(drive.rootAbsolute || '').toUpperCase()).filter(Boolean));
+        drivesCache = { at: now(), roots };
+        resolve(roots);
+      });
+    });
+  }
+
+  /** The stored path when it is still a path this relay serves; '' otherwise. Never decodes. */
+  async function servableLocalPath(locator) {
+    const value = String(locator || '');
+    if (!value || value.includes('\0')) return '';
+    if (platform === 'win32') {
+      if (!/^[A-Z]:\\/.test(value) || path.win32.normalize(value) !== value) return '';
+      const roots = await allowedDriveRoots();
+      if (roots && !roots.has(value.slice(0, 3).toUpperCase())) return '';
+      return value;
+    }
+    if (!value.startsWith('/') || path.posix.normalize(value) !== value) return '';
+    if (isPseudoFileSystemPath(value, platform)) return '';
+    return value;
+  }
+
+  function generatedPath(item) {
+    let info = parseGeneratedLocator(item.locator);
+    if (!info.relativePath || !info.sessionId) {
+      // Embedded by its route only: the attachment of the message it names.
+      const message = info.messageId ? db.prepare(`SELECT attachments FROM messages WHERE id = ? AND conversation_id = ?`)
+        .get(info.messageId, info.conversationId) : null;
+      info = { ...info, ...(generatedFromMessage(message?.attachments, info.imageId) || {}) };
+    }
+    if (!info.relativePath || !info.sessionId) return '';
+    return resolveGeneratedImagePath({ sessionId: info.sessionId, relativePath: info.relativePath }) || '';
+  }
+
+  /** The file behind an item, for the presence check and for serving; null when it has none (remote, data). */
+  async function filePathFor(item) {
+    switch (item.locatorKind) {
+      case 'local_path': return (await servableLocalPath(item.locator)) || '';
+      case 'upload_sha': return /^[a-f0-9]{64}$/.test(item.locator) ? String(uploadPathForSha(item.locator) || '') : '';
+      case 'generated': return generatedPath(item);
+      default: return null;
+    }
+  }
+
+  function clientItem(item) {
+    const out = {
+      id: item.id,
+      conversationId: item.conversationId,
+      conversationTitle: item.conversationTitle,
+      archived: item.archived,
+      provider: item.provider,
+      messageId: item.messageId,
+      sender: item.sender,
+      origin: item.origin,
+      mediaKind: item.mediaKind,
+      mime: item.mime,
+      name: item.name,
+      alt: item.alt,
+      sizeBytes: item.sizeBytes,
+      timestamp: item.timestamp,
+      occurrences: item.occurrences,
+      contentUrl: null,
+      remoteUrl: null,
+      path: null,
+    };
+    if (item.locatorKind === 'remote_url') out.remoteUrl = item.locator;
+    else if (item.locatorKind === 'upload_sha') out.contentUrl = `/api/upload/${item.locator}/content`;
+    else out.contentUrl = `/api/media/${item.id}/content`;
+    if (item.locatorKind === 'local_path') out.path = item.locator;
+    return out;
+  }
+
+  /**
+   * Opens the file of an item when it may be served: the stored path passes
+   * the checks, so does its real path (a link is followed only to a target
+   * that passes them too), it is a regular file, and a local picture or video
+   * is what its name says. One descriptor from the open on: the checks, the
+   * first bytes and the bytes sent are of the same file. `null` when it may
+   * not be served (or a call on the drive took too long); the caller closes
+   * `fd`.
+   */
+  async function openServable(item) {
+    let filePath = await filePathFor(item);
+    if (!filePath) return null;
+    if (item.locatorKind === 'local_path') {
+      const real = await withTimeout(realpathKeepingDrives(filePath), FS_TIMEOUT_MS, '');
+      filePath = real ? await servableLocalPath(real) : '';
+      if (!filePath) return null;
+    }
+    const fd = await withTimeout(openFile(filePath, OPEN_FLAGS), FS_TIMEOUT_MS, null, closeFile);
+    if (fd === null || fd === undefined) return null;
+    try {
+      const stat = await withTimeout(fstatFile(fd), FS_TIMEOUT_MS, null);
+      if (!stat?.isFile()) throw new Error('not a file');
+      let contentType = item.mime || 'application/octet-stream';
+      if (item.locatorKind === 'local_path' && item.category === 'media') {
+        contentType = sniffLocalMediaType(await readHead(fd), item);
+        if (!contentType) throw new Error('not a picture or video');
+      }
+      return { fd, filePath, stat, contentType, contentAddressed: item.locatorKind !== 'local_path' };
+    } catch {
+      closeFile(fd);
+      return null;
+    }
+  }
+
+  // Whether a tile can be served, asked for every listed item with a file;
+  // kept a minute per item and file version of the stored path.
+  const servable = new Map();
+  async function present(item) {
+    if (item.locatorKind === 'remote_url') return true;
+    if (item.locatorKind === 'data_uri' || item.locatorKind === 'legacy_data_url') return true;
+    const key = `${item.id}:${item.locator}`;
+    const cached = servable.get(key);
+    if (cached && now() - cached.at < SERVABLE_TTL_MS) return cached.ok;
+    const opened = await openServable(item);
+    if (opened) closeFile(opened.fd);
+    servable.delete(key);
+    servable.set(key, { ok: Boolean(opened), at: now() });
+    while (servable.size > SERVABLE_CACHE_MAX) servable.delete(servable.keys().next().value);
+    return Boolean(opened);
+  }
+
+  function readFilters(query) {
+    const source = MEDIA_SOURCES.includes(String(query.source || '')) ? String(query.source) : 'all';
+    return {
+      category: query.category === 'file' ? 'file' : 'media',
+      conversationId: String(query.conversationId || '').trim() || null,
+      source,
+      provider: String(query.provider || '').trim() || null,
+      archived: query.archived === 'hide' ? 'hide' : 'include',
+      q: String(query.q || '').trim(),
+    };
+  }
+
+  app.get('/api/media', auth, async (req, res) => {
+    try {
+      const indexing = indexService.drainForRequest();
+      const filters = readFilters(req.query || {});
+      const limit = Math.max(1, Math.min(120, Number.parseInt(String(req.query?.limit || '60'), 10) || 60));
+      let cursor = decodeMediaCursor(req.query?.cursor);
+      if (req.query?.cursor && !cursor) return res.status(400).json({ error: 'Invalid cursor' });
+      const items = [];
+      let missingHidden = 0;
+      let nextCursor = null;
+      // Missing files are left out; the page refills from the next rows.
+      for (let round = 0; round < MAX_PAGE_ROUNDS && items.length < limit; round += 1) {
+        const rows = repository.listMedia({ ...filters, cursor, limit });
+        for (const row of rows) {
+          if (items.length >= limit) break;
+          if (await present(row)) items.push(clientItem(row));
+          else missingHidden += 1;
+          cursor = { timestamp: row.timestamp, id: row.id };
+        }
+        nextCursor = rows.length === limit ? encodeMediaCursor(cursor) : null;
+        if (!nextCursor) break;
+      }
+      res.json({ items, nextCursor, missingHidden, indexing: { pending: indexing.pending } });
+    } catch (error) {
+      res.status(500).json({ error: error?.message || 'Failed to list media' });
+    }
+  });
+
+  app.get('/api/media/counts', auth, (req, res) => {
+    try {
+      const indexing = indexService.drainForRequest();
+      const conversationId = String(req.query?.conversationId || '').trim() || null;
+      res.json({ ...repository.countMedia({ conversationId }), pending: indexing.pending });
+    } catch (error) {
+      res.status(500).json({ error: error?.message || 'Failed to count media' });
+    }
+  });
+
+  app.get('/api/media/facets', auth, (req, res) => {
+    try {
+      indexService.drainForRequest();
+      res.json(repository.mediaFacets());
+    } catch (error) {
+      res.status(500).json({ error: error?.message || 'Failed to list media filters' });
+    }
+  });
+
+  app.get('/api/media/:id/content', auth, async (req, res) => {
+    const raw = String(req.params.id || '');
+    if (!/^\d{1,15}$/.test(raw)) return res.status(400).json({ error: 'Invalid media id' });
+    const item = repository.getMediaItem(Number(raw));
+    if (!item) return res.status(404).json({ error: 'Not found' });
+    try {
+      if (item.locatorKind === 'data_uri' || item.locatorKind === 'legacy_data_url') {
+        const found = findDataImage({ text: item.text, attachments: item.attachments }, item.identityKey);
+        const bytes = found ? Buffer.from(found.payload, 'base64') : null;
+        if (!bytes || !IMAGE_MAGIC[found.mime]?.(bytes)) return res.status(404).json({ error: 'Not found' });
+        const etag = `"${item.identityKey.slice('data:'.length, 'data:'.length + 32)}"`;
+        res.setHeader('Cache-Control', CONTENT_ADDRESSED_CACHE);
+        res.setHeader('ETag', etag);
+        if (req.headers['if-none-match'] === etag) return res.status(304).end();
+        applySafeServedContentHeaders(res, found.mime, { fileName: item.name || 'image' });
+        res.setHeader('Content-Length', String(bytes.length));
+        return res.end(bytes);
+      }
+      const opened = await openServable(item);
+      if (!opened) return res.status(404).json({ error: 'Not found' });
+      const { fd, filePath, stat, contentType, contentAddressed } = opened;
+      const version = fileVersionToken({ mtimeMs: stat.mtimeMs, size: stat.size });
+      if (!contentAddressed && version && req.headers['if-none-match'] === `W/"${version}"`) {
+        closeFile(fd);
+        res.setHeader('Cache-Control', REVALIDATE_CACHE);
+        res.setHeader('ETag', `W/"${version}"`);
+        return res.status(304).end();
+      }
+      const safeName = String(item.name || path.basename(filePath)).replace(/"/g, '');
+      // Sent from the descriptor the checks were made on.
+      const fromOpenFile = {
+        openSync: () => fd,
+        fstatSync: (handle) => fs.fstatSync(handle),
+        closeSync: (handle) => fs.closeSync(handle),
+        createReadStream: (target, options) => fs.createReadStream(target, options),
+      };
+      return serveFileWithRangeSupport(req, res, filePath, { contentType }, {
+        safeName,
+        cacheControl: contentAddressed ? CONTENT_ADDRESSED_CACHE : REVALIDATE_CACHE,
+        fsImpl: fromOpenFile,
+      });
+    } catch (error) {
+      if (!res.headersSent) res.status(500).json({ error: error?.message || 'Failed to read media' });
+    }
+  });
+
+  if (startIndexer) indexService.start();
+  return { repository, indexService };
+}