@oar-sh/oar 0.9.8 → 0.9.10

package/server/services/cloudflared-tunnel-service.mjs

@@ -2,16 +2,17 @@
 
 import path from 'path';
 import fs from 'fs';
-import { createRequire } from 'module';
 import { spawn } from 'child_process';
 
-const requireFromHere = createRequire(import.meta.url);
-
 const BACKOFF_STEPS = [5_000, 10_000, 20_000, 40_000, 60_000];
 const READINESS_WINDOW_MS = 5_000;
 const STABLE_CONNECTION_MS = 30_000;
 const FAST_EXIT_MS = 10_000;
 const MAX_CONSECUTIVE_FAST_EXITS = 3;
+const BINARY_RECHECK_MS = 60_000;
+// What Windows starts without a shell. A `.cmd`/`.bat` launcher would need
+// cmd.exe, and the tunnel token does not go through a shell command line.
+const WINDOWS_DIRECT_EXTENSIONS = ['.exe', '.com'];
 
 function toText(value) {
   return String(value || '').trim();
@@ -29,28 +30,91 @@ function normalizeExtraArgs(rawValue) {
   return rawValue.map((entry) => toText(entry)).filter(Boolean);
 }
 
-// The npm `cloudflared` package downloads the official binary on demand; it is an
-// optional dependency, so absence must degrade to a config error, never a crash.
-// `requireImpl` is a seam: the package is optional, so a suite running under
-// `npm ci --omit=optional` (or after a failed postinstall download) must still be
-// able to exercise this logic instead of silently testing the host's install state.
-export function resolveCloudflaredBinaryFromPackage({
-  existsSync = fs.existsSync,
-  requireImpl = requireFromHere,
+function hasDirectoryPart(value) {
+  return value.includes('/') || value.includes('\\');
+}
+
+/**
+ * Where the cloudflared the tunnel would run really is, or null. OAR ships no
+ * copy: a name is looked up on PATH (on Windows with the `.exe`/`.com`
+ * suffixes PATHEXT lists), a path must be an executable file.
+ */
+export function locateCloudflaredBinary(binary, {
+  platform = process.platform,
+  env = process.env,
+  fsImpl = fs,
+  pathImpl = platform === 'win32' ? path.win32 : path.posix,
 } = {}) {
-  try {
-    const mod = requireImpl('cloudflared');
-    const bin = toText(mod?.bin);
-    // `bin` is where the package *will* place the binary; it only exists after
-    // the on-demand download has run, so an un-downloaded path is not usable.
-    if (bin && existsSync(bin)) return bin;
-  } catch {}
+  const name = toText(binary);
+  if (!name) return null;
+
+  let names = [name];
+  if (platform === 'win32' && !WINDOWS_DIRECT_EXTENSIONS.includes(pathImpl.extname(name).toLowerCase())) {
+    const listed = String(env?.PATHEXT || '')
+      .split(';')
+      .map((ext) => toText(ext).toLowerCase())
+      .filter((ext) => WINDOWS_DIRECT_EXTENSIONS.includes(ext));
+    names = (listed.length ? listed : WINDOWS_DIRECT_EXTENSIONS).map((ext) => `${name}${ext}`);
+  }
+
+  const isExecutableFile = (candidate) => {
+    try {
+      if (!fsImpl.statSync(candidate).isFile()) return false;
+      // Windows has no execute bit; the suffix above decided.
+      if (platform !== 'win32') fsImpl.accessSync(candidate, fs.constants.X_OK);
+      return true;
+    } catch {
+      return false;
+    }
+  };
+
+  const dirs = hasDirectoryPart(name)
+    ? [null]
+    : String(env?.PATH ?? env?.Path ?? '').split(pathImpl.delimiter).map(toText).filter(Boolean);
+  for (const dir of dirs) {
+    for (const candidate of names) {
+      const full = dir === null ? candidate : pathImpl.join(dir, candidate);
+      if (isExecutableFile(full)) return full;
+    }
+  }
   return null;
 }
 
+export function cloudflaredInstallPointer(platform = process.platform) {
+  if (platform === 'win32') return 'install it with: winget install --id Cloudflare.cloudflared';
+  if (platform === 'darwin') return 'install it with: brew install cloudflared';
+  return "install it from Cloudflare's package repository: https://pkg.cloudflare.com/";
+}
+
+/** The one sentence the tunnel state, the status dot and the CLI show. */
+export function describeMissingCloudflaredBinary({ binary = '', binarySource = 'path', platform = process.platform } = {}) {
+  const pointer = cloudflaredInstallPointer(platform);
+  if (binarySource === 'config') {
+    return `cloudflared was not found as configured (${binary}) — correct cloudflaredTunnel.binary, or ${pointer}`;
+  }
+  return `cloudflared is not installed — ${pointer}`;
+}
+
+/**
+ * The tunnel in one line for a CLI status row. Takes the manager's state or
+ * the `cloudflaredTunnel` object of `/api/status`; the public address is the
+ * caller's to pass, the relay does not know it (the route lives in Cloudflare).
+ */
+export function describeTunnelState(state, { url = '' } = {}) {
+  const tunnel = state && typeof state === 'object' ? state : {};
+  const managed = toText(tunnel.mode).toLowerCase() === 'managed' || tunnel.enabled === true;
+  if (!managed) return 'off';
+  const reason = toText(tunnel.lastError);
+  if (tunnel.connected === true) {
+    const address = toText(url);
+    return address ? `running (${address})` : 'running';
+  }
+  if (tunnel.binaryMissing === true || tunnel.valid === false) return reason ? `off: ${reason}` : 'off';
+  return reason ? `not connected (${reason})` : 'not connected';
+}
+
 export function normalizeCloudflaredTunnelConfig(rawConfig = {}, {
   env = process.env,
-  resolveBinary = resolveCloudflaredBinaryFromPackage,
   configBaseDir = process.cwd(),
   pathImpl = path,
 } = {}) {
@@ -64,33 +128,20 @@ export function normalizeCloudflaredTunnelConfig(rawConfig = {}, {
   const binaryInput = toText(env?.COPILOT_CLOUDFLARED_BINARY) || toText(raw.binary);
   const extraArgs = normalizeExtraArgs(raw.extraArgs);
 
-  let binary = '';
-  let binarySource = null;
+  // The configured binary, else `cloudflared` from PATH. Whether it is really
+  // there is checked when the tunnel starts (locateCloudflaredBinary).
+  let binary = 'cloudflared';
+  let binarySource = 'path';
   if (binaryInput) {
-    binary = binaryInput.includes('/') || binaryInput.includes('\\')
+    binary = hasDirectoryPart(binaryInput)
       ? pathImpl.resolve(configBaseDir, binaryInput)
       : binaryInput;
     binarySource = 'config';
-  } else {
-    let packageBinary = null;
-    try {
-      packageBinary = toText(typeof resolveBinary === 'function' ? resolveBinary() : '');
-    } catch {
-      packageBinary = null;
-    }
-    if (packageBinary) {
-      binary = packageBinary;
-      binarySource = 'package';
-    } else {
-      binary = 'cloudflared';
-      binarySource = 'path';
-    }
   }
 
   const errors = [];
   if (mode === 'managed') {
     if (!token) errors.push('cloudflaredTunnel.token is required when cloudflaredTunnel.mode is "managed"');
-    if (!binary) errors.push('cloudflaredTunnel.binary could not be resolved (install the "cloudflared" package or set cloudflaredTunnel.binary)');
   }
 
   return {
@@ -106,6 +157,28 @@ export function normalizeCloudflaredTunnelConfig(rawConfig = {}, {
   };
 }
 
+/**
+ * The tunnel as `oar doctor` reports it, from the config alone (no relay
+ * needed): whether the built-in tunnel is on and whether it could start.
+ */
+export function describeConfiguredTunnel(rawConfig = {}, {
+  env = process.env,
+  platform = process.platform,
+  configBaseDir = process.cwd(),
+  pathImpl = path,
+  locateBinary = locateCloudflaredBinary,
+} = {}) {
+  const tunnelConfig = normalizeCloudflaredTunnelConfig(rawConfig, { env, configBaseDir, pathImpl });
+  if (tunnelConfig.mode !== 'managed') return 'disabled';
+  if (!tunnelConfig.valid) return `managed, cannot start: ${tunnelConfig.errors[0]}`;
+  const located = locateBinary(tunnelConfig.binary, { platform, env });
+  if (!located) {
+    const { binary, binarySource } = tunnelConfig;
+    return `managed, cannot start: ${describeMissingCloudflaredBinary({ binary, binarySource, platform })}`;
+  }
+  return `managed (cloudflared: ${located})`;
+}
+
 export function buildCloudflaredArgs(tunnelConfig) {
   return ['tunnel', 'run', '--token', tunnelConfig.token, ...tunnelConfig.extraArgs];
 }
@@ -145,12 +218,11 @@ export function createCloudflaredTunnelManager({
   clearTimeoutImpl = clearTimeout,
   configBaseDir = process.cwd(),
   env = process.env,
-  resolveBinary = resolveCloudflaredBinaryFromPackage,
+  locateBinary = locateCloudflaredBinary,
   pathImpl = path,
 } = {}) {
   const tunnelConfig = normalizeCloudflaredTunnelConfig(rawTunnelConfig, {
     env,
-    resolveBinary,
     configBaseDir,
     pathImpl,
   });
@@ -174,6 +246,7 @@ export function createCloudflaredTunnelManager({
     lastError: tunnelConfig.errors[0] || null,
     lastEventAt: nowIso(),
     binary: tunnelConfig.binary || null,
+    binaryMissing: false,
     proc: null,
     backoffTimer: null,
   };
@@ -189,6 +262,7 @@ export function createCloudflaredTunnelManager({
       reconnectAttempts: state.reconnectAttempts,
       connectedSince: state.connectedSince,
       lastError: state.lastError,
+      binaryMissing: state.binaryMissing,
     });
   };
 
@@ -220,9 +294,33 @@ export function createCloudflaredTunnelManager({
       return;
     }
 
+    // OAR ships no cloudflared. Without one the tunnel stays off, the state
+    // says how to install it, and a look every minute starts the tunnel once
+    // it is there (no relay restart, as long as it lands on the relay's PATH).
+    let located = null;
+    try { located = toText(locateBinary(tunnelConfig.binary, { platform, env })); } catch {}
+    if (!located) {
+      if (!state.binaryMissing) {
+        state.binaryMissing = true;
+        state.lastError = describeMissingCloudflaredBinary({
+          binary: tunnelConfig.binary,
+          binarySource: tunnelConfig.binarySource,
+          platform,
+        });
+        warn(`Tunnel not started: ${state.lastError}`);
+        updateBlockingState();
+        emitStatus();
+      }
+      if (state.backoffTimer) clearTimeoutImpl(state.backoffTimer);
+      state.backoffTimer = setTimeoutImpl(spawnTunnel, BINARY_RECHECK_MS);
+      if (typeof state.backoffTimer?.unref === 'function') state.backoffTimer.unref();
+      return;
+    }
+    state.binaryMissing = false;
+
     const args = buildCloudflaredArgs(tunnelConfig);
-    log(`Spawning: ${tunnelConfig.binary} ${redactCloudflaredArgs(args).join(' ')}`);
-    const proc = spawnImpl(tunnelConfig.binary, args, buildSpawnOptions(platform, ['ignore', 'pipe', 'pipe']));
+    log(`Spawning: ${located} ${redactCloudflaredArgs(args).join(' ')}`);
+    const proc = spawnImpl(located, args, buildSpawnOptions(platform, ['ignore', 'pipe', 'pipe']));
     state.proc = proc;
     state.lastError = null;
     updateBlockingState();

package/server/services/explorer-entry-name.mjs

@@ -0,0 +1,26 @@
+// The one rule set for a file or folder name typed in the explorer: a single
+// path segment, nothing that could leave the parent, and on Windows nothing
+// the filesystem itself refuses. The Windows set applies only when the relay
+// runs there; a Linux name such as `a:b` is legal and stays legal.
+
+const MAX_NAME_BYTES = 255;
+const WINDOWS_FORBIDDEN_CHARS = /[<>:"|?*\u0000-\u001f]/;
+const WINDOWS_RESERVED_NAMES = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(\..*)?$/i;
+
+/**
+ * Validate a name. Returns `{ ok: true, name }` with the trimmed name, or
+ * `{ ok: false, error }` with a message fit for the UI.
+ */
+export function validateEntryName(rawName, { platform = process.platform } = {}) {
+  const name = String(rawName ?? '').trim();
+  if (!name) return { ok: false, error: 'Enter a name' };
+  if (name === '.' || name === '..') return { ok: false, error: 'That name is not allowed' };
+  if (/[/\\\0]/.test(name)) return { ok: false, error: 'A name cannot contain / or \\' };
+  if (Buffer.byteLength(name, 'utf8') > MAX_NAME_BYTES) return { ok: false, error: 'That name is too long' };
+  if (platform === 'win32') { // host-platform: Windows filesystem naming rules
+    if (WINDOWS_FORBIDDEN_CHARS.test(name)) return { ok: false, error: 'A name cannot contain < > : " | ? *' };
+    if (/[. ]$/.test(name)) return { ok: false, error: 'A name cannot end with a dot or a space' };
+    if (WINDOWS_RESERVED_NAMES.test(name)) return { ok: false, error: 'That name is reserved by Windows' };
+  }
+  return { ok: true, name };
+}

package/server/services/explorer-mutations.mjs

@@ -0,0 +1,122 @@
+// Filesystem changes made from the explorer: create a folder, rename an
+// entry, delete an entry, and count what a delete would remove. The callers
+// (the routes) have already resolved the absolute target inside a browsable
+// root; this module only touches the filesystem and turns its errors into
+// `{ error, statusCode }` answers the routes can send as they are.
+//
+// Symbolic links are refused everywhere. The listings skip them, so the user
+// never saw one in the explorer, and a rename or delete through a link would
+// act on something outside the folder they are looking at.
+
+import fsDefault from 'node:fs';
+import pathDefault from 'node:path';
+
+export const DEFAULT_COUNT_CAP = 10000;
+
+function failure(error, fallback, statusCode = 500) {
+  const code = String(error?.code || '');
+  if (code === 'ENOENT' || code === 'ENOTDIR') return { error: 'Not found', statusCode: 404 };
+  if (code === 'EEXIST' || code === 'ENOTEMPTY') return { error: 'That name is already taken', statusCode: 409 };
+  if (code === 'EACCES' || code === 'EPERM' || code === 'EBUSY') return { error: 'Permission denied', statusCode: 403 };
+  return { error: error?.message || fallback, statusCode };
+}
+
+function lstatOrNull(fs, target) {
+  try {
+    return fs.lstatSync(target);
+  } catch (error) {
+    if (error?.code === 'ENOENT' || error?.code === 'ENOTDIR') return null;
+    throw error;
+  }
+}
+
+/** Create `target`; missing parents are created with it. */
+export function createDirectory(target, { fs = fsDefault } = {}) {
+  try {
+    if (lstatOrNull(fs, target)) return { error: 'That name is already taken', statusCode: 409 };
+    fs.mkdirSync(target, { recursive: true });
+    return { ok: true };
+  } catch (error) {
+    return failure(error, 'Failed to create the folder');
+  }
+}
+
+/**
+ * Rename `target` to `newName` inside its own parent. A name that differs
+ * only in case is allowed: on a case-insensitive filesystem the destination
+ * stat finds the source itself, which is not a collision.
+ */
+export function renameEntry(target, newName, { fs = fsDefault, path = pathDefault } = {}) {
+  const destination = path.join(path.dirname(target), newName);
+  try {
+    const source = lstatOrNull(fs, target);
+    if (!source) return { error: 'Not found', statusCode: 404 };
+    if (source.isSymbolicLink()) return { error: 'Links cannot be changed here', statusCode: 409 };
+    if (destination === target) return { ok: true, path: destination };
+    const existing = lstatOrNull(fs, destination);
+    const sameEntry = existing && existing.ino === source.ino && existing.dev === source.dev && existing.ino !== 0;
+    if (existing && !sameEntry) return { error: 'That name is already taken', statusCode: 409 };
+    fs.renameSync(target, destination);
+    return { ok: true, path: destination };
+  } catch (error) {
+    return failure(error, 'Failed to rename');
+  }
+}
+
+/** Remove `target`; a folder goes with everything inside it. */
+export function removeEntry(target, { fs = fsDefault } = {}) {
+  try {
+    const stat = lstatOrNull(fs, target);
+    if (!stat) return { error: 'Not found', statusCode: 404 };
+    if (stat.isSymbolicLink()) return { error: 'Links cannot be changed here', statusCode: 409 };
+    fs.rmSync(target, { recursive: true, force: false, maxRetries: 2 });
+    return { ok: true };
+  } catch (error) {
+    return failure(error, 'Failed to delete');
+  }
+}
+
+/**
+ * What a delete of `target` would remove: `{ kind, files, dirs, capped }`.
+ * `dirs` excludes the target itself. The walk stops once `files + dirs`
+ * reaches `cap`, so a huge tree answers quickly with `capped: true`. Links
+ * inside count as files and are not followed.
+ */
+export function countEntries(target, { fs = fsDefault, path = pathDefault, cap = DEFAULT_COUNT_CAP } = {}) {
+  let stat = null;
+  try {
+    stat = lstatOrNull(fs, target);
+  } catch (error) {
+    return failure(error, 'Failed to read the entry');
+  }
+  if (!stat) return { error: 'Not found', statusCode: 404 };
+  if (stat.isSymbolicLink()) return { error: 'Links cannot be changed here', statusCode: 409 };
+  if (!stat.isDirectory()) return { ok: true, kind: 'file', files: 0, dirs: 0, capped: false };
+
+  let files = 0;
+  let dirs = 0;
+  let capped = false;
+  const stack = [target];
+  while (stack.length && !capped) {
+    const dir = stack.pop();
+    let entries = [];
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue; // an unreadable branch is still removed by rm; it just stays uncounted
+    }
+    for (const entry of entries) {
+      if (entry.isDirectory() && !entry.isSymbolicLink()) {
+        dirs += 1;
+        stack.push(path.join(dir, entry.name));
+      } else {
+        files += 1;
+      }
+      if (files + dirs >= cap) {
+        capped = true;
+        break;
+      }
+    }
+  }
+  return { ok: true, kind: 'dir', files, dirs, capped };
+}

package/server/services/file-serving.mjs

@@ -0,0 +1,155 @@
+// Serving a file from disk so that what arrives is the file as it is now:
+// one open, one fstat, and length, validators and bytes all from that handle.
+// The headers tell every cache on the way, the browser's and a CDN's alike,
+// to keep nothing.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { applySafeServedContentHeaders } from './safe-served-content.mjs';
+
+/**
+ * A short token that changes whenever the file's bytes may have changed
+ * (modification time or size). It goes into download URLs as `v=…`: the
+ * server ignores it, and a changed file gets a URL nothing has seen before.
+ */
+export function fileVersionToken({ mtimeMs, size } = {}) {
+  const modified = Math.floor(Number(mtimeMs));
+  const bytes = Number(size);
+  if (!Number.isFinite(modified) || !Number.isFinite(bytes) || modified < 0 || bytes < 0) return '';
+  return `${modified.toString(36)}-${Math.floor(bytes).toString(36)}`;
+}
+
+/**
+ * `Cache-Control` speaks to browsers and to proxies that honour it. The two
+ * CDN headers bind the edge itself: Cloudflare obeys them ahead of
+ * `Cache-Control` and of a "cache everything" rule that would otherwise
+ * override the origin's wish.
+ */
+export function applyNoStoreHeaders(res) {
+  res.setHeader('Cache-Control', 'no-store');
+  applyCdnNoStoreHeaders(res);
+}
+
+export function applyCdnNoStoreHeaders(res) {
+  res.setHeader('CDN-Cache-Control', 'no-store');
+  res.setHeader('Cloudflare-CDN-Cache-Control', 'no-store');
+}
+
+/**
+ * The name a download is saved under, when the client asks for one (`as=…`).
+ * Accepted only as a plain file name with the real file's extension, so the
+ * request cannot change what kind of file the browser believes it gets.
+ */
+export function downloadNameOverride(requested, realName) {
+  const wanted = String(requested || '').trim();
+  if (!wanted || wanted.length > 200) return '';
+  if (/[\\/:*?"<>|\u0000-\u001f\u007f]/.test(wanted) || wanted === '.' || wanted === '..') return '';
+  const realExt = path.extname(String(realName || '')).toLowerCase();
+  if (path.extname(wanted).toLowerCase() !== realExt) return '';
+  return wanted;
+}
+
+function appendUrlParam(url, key, value) {
+  if (!value) return url;
+  return `${url}${url.includes('?') ? '&' : '?'}${key}=${encodeURIComponent(value)}`;
+}
+
+/** `url` with the file's version token appended, or unchanged when there is none. */
+export function withFileVersion(url, version) {
+  return appendUrlParam(String(url || ''), 'v', String(version || ''));
+}
+
+/**
+ * `cacheControl` replaces the no-store default for content whose URL names
+ * its bytes (an upload addressed by its hash): such an answer may be kept.
+ */
+export function serveFileWithRangeSupport(req, res, filePath, meta, { safeName, cacheDelete = null, fsImpl = fs, cacheControl = '' } = {}) {
+  const realName = safeName || path.basename(filePath).replace(/"/g, '');
+  const name = downloadNameOverride(req.query?.as, realName) || realName;
+  const rangeHeader = req.headers['range'];
+
+  const fail = (error) => {
+    if (cacheDelete) cacheDelete(filePath);
+    if (res.headersSent) { res.destroy(error); return; }
+    if (error?.code === 'ENOENT' || error?.code === 'ENOTDIR' || error?.code === 'EISDIR') {
+      res.status(404).json({ error: 'File not found' });
+      return;
+    }
+    res.status(500).json({ error: 'Failed to read file' });
+  };
+
+  // The caller's `meta` may be a moment old (it is cached). Size, validators
+  // and bytes all come from this one handle instead: a length taken from an
+  // older stat cut a file that had just grown down to its previous size.
+  let fd = null;
+  let stat = null;
+  try {
+    fd = fsImpl.openSync(filePath, 'r');
+    stat = fsImpl.fstatSync(fd);
+  } catch (error) {
+    if (fd !== null) { try { fsImpl.closeSync(fd); } catch {} }
+    fail(error);
+    return;
+  }
+  const closeFd = () => { try { fsImpl.closeSync(fd); } catch {} };
+  if (!stat.isFile()) {
+    closeFd();
+    fail(Object.assign(new Error('Not a file'), { code: 'EISDIR' }));
+    return;
+  }
+  const fileSize = Number(stat.size || 0);
+
+  // From here until the stream owns the handle, any throw (a header value
+  // `setHeader` refuses, say) must close the handle, or every such request
+  // would leak one.
+  let start = 0;
+  let end = fileSize - 1;
+  try {
+    res.setHeader('Accept-Ranges', 'bytes');
+    if (cacheControl) res.setHeader('Cache-Control', cacheControl);
+    else applyNoStoreHeaders(res);
+    // Validators cost nothing next to no-store, and they let a client or a
+    // person with curl see which version of the file an answer carries.
+    const version = fileVersionToken({ mtimeMs: stat.mtimeMs, size: fileSize });
+    if (version) res.setHeader('ETag', `W/"${version}"`);
+    if (Number.isFinite(stat.mtimeMs)) res.setHeader('Last-Modified', new Date(stat.mtimeMs).toUTCString());
+    // Neutralize browser-executable types (HTML/SVG/XML), force nosniff, and
+    // sandbox the response so a worker-written workspace file can't run as script
+    // on this origin. Media stays inline for preview; everything else downloads.
+    applySafeServedContentHeaders(res, meta?.contentType, { fileName: name });
+
+    if (rangeHeader) {
+      const match = /bytes=(\d+)-(\d*)/.exec(rangeHeader);
+      const from = match ? parseInt(match[1], 10) : NaN;
+      const to = match && match[2] ? parseInt(match[2], 10) : fileSize - 1;
+      if (!match || from > to || from >= fileSize || to >= fileSize) {
+        closeFd();
+        res.setHeader('Content-Range', `bytes */${fileSize}`);
+        res.status(416).end();
+        return;
+      }
+      start = from;
+      end = to;
+      res.setHeader('Content-Range', `bytes ${start}-${end}/${fileSize}`);
+      res.status(206);
+    }
+    res.setHeader('Content-Length', String(Math.max(0, end - start + 1)));
+  } catch (error) {
+    closeFd();
+    fail(error);
+    return;
+  }
+  if (end - start + 1 <= 0) {
+    closeFd();
+    res.end();
+    return;
+  }
+  // Bounded to the size just read, so a file that grows while it is sent
+  // still yields exactly the announced number of bytes.
+  const stream = fsImpl.createReadStream(null, { fd, start, end, autoClose: true });
+  stream.on('error', fail);
+  // A client that goes away mid-download would otherwise leave the handle open.
+  res.on?.('close', () => stream.destroy());
+  stream.pipe(res);
+}

package/server/services/message-pin-list.mjs

@@ -0,0 +1,52 @@
+'use strict';
+
+// The list of pinned messages a conversation carries: one short plain-text
+// preview per pin, so the browser can show the list without loading (or
+// rendering markdown for) messages outside its history page.
+
+import { stripRelayPromptContext } from './relay-prompt-sanitizer.mjs';
+
+export const MESSAGE_PIN_LIMIT = 100;
+export const PIN_PREVIEW_MAX_LENGTH = 160;
+
+function countAttachments(raw) {
+  if (Array.isArray(raw)) return raw.length;
+  if (typeof raw !== 'string' || !raw) return 0;
+  try {
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed.length : 0;
+  } catch {
+    return 0;
+  }
+}
+
+// Light on purpose: enough that a heading, a list or a link reads as a line of
+// text. Single * and _ stay, they are more often part of a name than emphasis.
+export function buildPinPreview(text, mode = '') {
+  const plain = String(stripRelayPromptContext(String(text || ''), mode) || '')
+    .replace(/```[^\n]*\n?/g, ' ')
+    .replace(/!\[([^\]]*)\]\([^)]*\)/g, (_match, alt) => (alt ? `🖼 ${alt}` : '🖼'))
+    .replace(/\[([^\]]+)\]\([^)]*\)/g, '$1')
+    .replace(/^\s{0,3}(?:#{1,6}|>+|[-*+]|\d+[.)])\s+/gm, '')
+    .replace(/\*\*|__|~~|`/g, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+  // By code point, so an emoji at the cut is dropped whole.
+  const points = Array.from(plain);
+  if (points.length <= PIN_PREVIEW_MAX_LENGTH) return plain;
+  return `${points.slice(0, PIN_PREVIEW_MAX_LENGTH - 1).join('').trimEnd()}…`;
+}
+
+export function buildPinList(rows) {
+  return (Array.isArray(rows) ? rows : [])
+    .filter((row) => String(row?.id || '').trim() && row?.pinned_at)
+    .map((row) => ({
+      messageId: String(row.id).trim(),
+      role: String(row.role || '').trim(),
+      preview: buildPinPreview(row.text, row.mode),
+      timestamp: row.timestamp || null,
+      pinnedAt: row.pinned_at,
+      attachmentCount: countAttachments(row.attachments),
+      hiddenFromShares: Number(row.hidden_from_shares || 0) === 1,
+    }));
+}