@oar-sh/oar 0.9.7 → 0.9.9

package/server/server-runtime.mjs

@@ -24,6 +24,7 @@ import {
   normalizeWorkspaceRootKey,
 } from './services/workspace-root-path-policy.mjs';
 import { stopSessionWorkerProcesses } from './services/session-worker-stop-service.mjs';
+import { applyCdnNoStoreHeaders } from './services/file-serving.mjs';
 import { pickLiveTurnRowId } from './services/live-turn-picker.mjs';
 import { buildSteerSettleFailure, steerAgentLabelForProvider } from '../shared/steer-settle-failure.mjs';
 import { sanitizeRelayQuestionContext as sanitizeRelayQuestionContextWith } from './services/relay-question-context.mjs';
@@ -176,6 +177,7 @@ import {
   isSafeProviderModelId,
 } from '../shared/model-id.mjs';
 import { createModelVariantCatalogService } from './services/model-variant-catalog-service.mjs';
+import { applyPwaManifestTheme, normalizePwaTheme } from './services/pwa-manifest-theme.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = path.resolve(__dirname, '..');
@@ -1509,6 +1511,17 @@ const WORKSPACE_CONTENT_TYPES = Object.freeze({
   '.gif': 'image/gif',
   '.webp': 'image/webp',
   '.ico': 'image/x-icon',
+  '.bmp': 'image/bmp',
+  '.avif': 'image/avif',
+  '.mp3': 'audio/mpeg',
+  '.wav': 'audio/wav',
+  '.m4a': 'audio/mp4',
+  '.aac': 'audio/aac',
+  '.ogg': 'audio/ogg',
+  '.oga': 'audio/ogg',
+  '.opus': 'audio/ogg',
+  '.flac': 'audio/flac',
+  '.weba': 'audio/webm',
   '.mp4': 'video/mp4',
   '.m4v': 'video/mp4',
   '.mov': 'video/quicktime',
@@ -1649,6 +1662,7 @@ const WORKSPACE_CODE_EXTENSIONS = new Set(Object.keys(WORKSPACE_PREVIEW_LANGUAGE
   .filter((ext) => !WORKSPACE_MARKDOWN_EXTENSIONS.has(ext)));
 const WORKSPACE_IMAGE_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.svg', '.ico', '.bmp', '.avif']);
 const WORKSPACE_VIDEO_EXTENSIONS = new Set(['.mp4', '.m4v', '.mov', '.webm', '.mkv', '.avi', '.ogv', '.wmv']);
+const WORKSPACE_AUDIO_EXTENSIONS = new Set(['.mp3', '.wav', '.m4a', '.aac', '.ogg', '.oga', '.opus', '.flac', '.weba']);
 const REPO_HEAVY_DIR_NAMES = new Set(['.git', 'node_modules']);
 const MAX_REPO_TREE_NODES = 20_000;
 const MAX_REPO_TREE_DEPTH = 64;
@@ -2992,6 +3006,7 @@ const updateCheckService = updateCheckKilled ? null : createUpdateCheckService({
 const updateInstallService = createUpdateInstallService({
   runningVersion: RUNNING_VERSION,
   installMethod: INSTALL_METHOD,
+  packageRoot: PACKAGE_ROOT,
   readSetting: readAppSettingValue,
   writeSetting: (key, value) => stmts.upsertAppSetting.run(key, value, new Date().toISOString()),
   deleteSetting: (key) => stmts.deleteAppSetting.run(key),
@@ -4146,6 +4161,7 @@ function readWorkspaceFileMeta(filePath) {
   return cacheWorkspaceFileMeta(filePath, {
     kind: 'file',
     size: Number(stat.size || 0),
+    mtimeMs: Number(stat.mtimeMs || 0),
     contentType: workspaceContentType(filePath),
   });
 }
@@ -4212,6 +4228,8 @@ function workspacePreviewKindForMeta(filePath, contentType) {
   if (WORKSPACE_MARKDOWN_EXTENSIONS.has(normalizedExt)) return 'markdown';
   if (WORKSPACE_IMAGE_EXTENSIONS.has(normalizedExt) || normalizedType.startsWith('image/')) return 'image';
   if (WORKSPACE_VIDEO_EXTENSIONS.has(normalizedExt) || normalizedType.startsWith('video/')) return 'video';
+  if (WORKSPACE_AUDIO_EXTENSIONS.has(normalizedExt) || normalizedType.startsWith('audio/')) return 'audio';
+  if (normalizedExt === '.pdf' || normalizedType === 'application/pdf') return 'pdf';
   if (WORKSPACE_CODE_EXTENSIONS.has(normalizedExt) || WORKSPACE_PREVIEW_LANGUAGE_BY_FILENAME[filename]) return 'code';
   if (isLikelyTextContentType(normalizedType)) return 'text';
   return 'binary';
@@ -5525,8 +5543,7 @@ function shouldIncludeInPwaVersion(relativePath) {
   const normalized = String(relativePath).replace(/\\/g, '/').replace(/^\/+/, '');
   if (!normalized || normalized.startsWith('.')) return false;
   if (normalized === 'index.html' || normalized === 'sw.js' || normalized === 'manifest.webmanifest') return true;
-  if (/^app-icon(?:-\d+)?\.png$/i.test(normalized)) return true;
-  if (/^app-icon\.svg$/i.test(normalized)) return true;
+  if (/^app-icon(?:-light)?(?:-maskable)?(?:-\d+)?\.(?:png|svg)$/i.test(normalized)) return true;
   if (/^favicon\.ico$/i.test(normalized)) return true;
   if (normalized.startsWith('app/')) {
     const ext = path.extname(normalized).toLowerCase();
@@ -5598,12 +5615,13 @@ function loadPwaManifestTemplate() {
     description: 'OAR — Open Agent Relay: drive your local coding agents from any browser.',
     display_override: ['standalone'],
     display: 'standalone',
-    background_color: '#161b22',
-    theme_color: '#161b22',
+    background_color: '#0d1117',
+    theme_color: '#0d1117',
     icons: [
-      { src: 'app-icon.svg?v=25', sizes: 'any', type: 'image/svg+xml', purpose: 'any' },
+      { src: 'app-icon.svg?v=26', sizes: 'any', type: 'image/svg+xml', purpose: 'any' },
       { src: 'app-icon-192.png', sizes: '192x192', type: 'image/png', purpose: 'any' },
       { src: 'app-icon-512.png', sizes: '512x512', type: 'image/png', purpose: 'any' },
+      { src: 'app-icon-maskable-512.png', sizes: '512x512', type: 'image/png', purpose: 'maskable' },
     ],
   };
   try {
@@ -5614,8 +5632,8 @@ function loadPwaManifestTemplate() {
   return fallback;
 }
 
-function buildScopedPwaManifest({ shared = false } = {}) {
-  const manifest = loadPwaManifestTemplate();
+function buildScopedPwaManifest({ shared = false, theme = 'dark' } = {}) {
+  const manifest = applyPwaManifestTheme(loadPwaManifestTemplate(), theme);
   // The custom name must be baked into every served manifest: Android's WebAPK
   // update check re-fetches this route outside any page session, so a name the
   // route doesn't know reverts on the phone with an accept-or-uninstall prompt.
@@ -6339,6 +6357,10 @@ app.use((req, _res, next) => {
   stripRequestPathPrefix(req, remotePath);
   next();
 });
+function isApiRequestPath(requestPath) {
+  return /^\/api(?:\/|$)/.test(String(requestPath || ''));
+}
+
 // Baseline security headers on every response. Served-file/attachment endpoints
 // layer a stricter sandbox CSP on top (see applySafeServedContentHeaders). A
 // global script-src CSP is intentionally omitted for now: the SPA relies on
@@ -6347,6 +6369,14 @@ app.use((req, res, next) => {
   res.setHeader('X-Content-Type-Options', 'nosniff');
   res.setHeader('X-Frame-Options', 'SAMEORIGIN');
   res.setHeader('Referrer-Policy', 'no-referrer');
+  // Nothing this relay answers belongs in a CDN's cache: it is all behind a
+  // login. These two headers bind the edge itself, whatever cache rule the
+  // zone in front of a tunnel has.
+  applyCdnNoStoreHeaders(res);
+  // An API answer is never stored by default, errors included (a 404 or a
+  // 401 for a file must not outlive the file's absence). A route that
+  // serves content-addressed bytes sets its own, longer-lived value.
+  if (isApiRequestPath(req.path)) res.setHeader('Cache-Control', 'no-store');
   next();
 });
 app.get('/socket.io/socket.io.js', (req, res, next) => {
@@ -6358,7 +6388,7 @@ app.get('/socket.io/socket.io.js', (req, res, next) => {
 app.get('/manifest.webmanifest', (req, res, next) => {
   try {
     const shared = String(req.query?.shared || '').trim() === '1';
-    const manifest = buildScopedPwaManifest({ shared });
+    const manifest = buildScopedPwaManifest({ shared, theme: normalizePwaTheme(req.query?.theme) });
     res.setHeader('Cache-Control', 'no-store');
     res.type('application/manifest+json').send(JSON.stringify(manifest, null, 2));
   } catch (error) {
@@ -6550,6 +6580,7 @@ const sharedRouteDeps = {
   compareRepoDirEntries,
   shouldSkipRepoEntryName,
   readWorkspaceFileMeta,
+  workspaceFileMetaCache,
   resolveWorkspaceFilePath,
   normalizeWorkspaceRelativePath,
   previewLanguageForWorkspaceFile,

package/server/services/claude-context-usage.mjs

@@ -209,26 +209,40 @@ export function buildClaudeContextSnapshot({
   };
 }
 
+/**
+ * The model's own context limit in tokens, from the turn result's
+ * `modelUsage[model].contextWindow`. Unlike the usage response's maxTokens
+ * (which follows the active auto-compact window), this is what the model can
+ * hold. Null when the snapshot does not carry it.
+ */
+export function resolveModelContextLimit({ contextUsage = null, modelUsage = null, model = '' } = {}) {
+  const usage = normalizeClaudeContextUsage(contextUsage);
+  const entry = resolveModelUsageEntry(modelUsage, model || usage?.model);
+  const limit = toNullableInt(entry?.contextWindow);
+  return limit !== null && limit > 0 ? limit : null;
+}
+
 /**
  * Parse the JSON blob persisted on `runtime_sessions` and rebuild both the
  * snapshot and the normalized usage the view layer renders.
  */
 export function readStoredClaudeContextUsage(row) {
   const rawJson = normalizeText(row?.context_usage_json);
-  if (!rawJson) return { snapshot: null, contextUsage: null };
+  if (!rawJson) return { snapshot: null, contextUsage: null, modelContextLimit: null };
 
   let parsed = null;
   try {
     parsed = JSON.parse(rawJson);
   } catch {
-    return { snapshot: null, contextUsage: null };
+    return { snapshot: null, contextUsage: null, modelContextLimit: null };
   }
 
   const capturedAt = normalizeText(row?.context_usage_captured_at) || null;
+  const model = parsed?.model || row?.provider_model || row?.model || '';
   const snapshot = buildClaudeContextSnapshot({
     contextUsage: parsed?.contextUsage,
     modelUsage: parsed?.modelUsage,
-    model: parsed?.model || row?.provider_model || row?.model || '',
+    model,
     runtimeSessionId: row?.id || null,
     sdkSessionId: row?.sdk_session_id || null,
     capturedAt,
@@ -236,5 +250,39 @@ export function readStoredClaudeContextUsage(row) {
   return {
     snapshot,
     contextUsage: normalizeClaudeContextUsage(parsed?.contextUsage),
+    modelContextLimit: resolveModelContextLimit({
+      contextUsage: parsed?.contextUsage,
+      modelUsage: parsed?.modelUsage,
+      model,
+    }),
   };
 }
+
+/**
+ * Where the conversation's stored compaction window stands against the
+ * running Claude CLI, for the context-usage modal. `steering` is the worker's
+ * heartbeat snapshot; its `autoCompactWindow` ({active, backgroundWork}) is
+ * present only while a CLI runs, so an older worker or a stopped one yields
+ * nulls.
+ *
+ * - `activeAutoCompactWindow`: the window the running CLI was spawned with.
+ * - `autoCompactWindowDeferred`: why a stored window that differs from it is
+ *   not applied yet — 'turn' (a turn is running), 'background' (idle, but
+ *   background agents/shells hold the process) or 'next-message' (the next
+ *   message respawns the CLI). Null when the two agree or no CLI runs.
+ */
+export function resolveAutoCompactWindowStatus({ storedWindow = null, steering = null } = {}) {
+  const running = steering?.autoCompactWindow;
+  if (!running || typeof running !== 'object') {
+    return { activeAutoCompactWindow: null, autoCompactWindowDeferred: null };
+  }
+  const active = toNullableInt(running.active);
+  const stored = toNullableInt(storedWindow);
+  let deferred = null;
+  if (stored !== active) {
+    if (steering.turnActive === true) deferred = 'turn';
+    else if (running.backgroundWork === true) deferred = 'background';
+    else deferred = 'next-message';
+  }
+  return { activeAutoCompactWindow: active, autoCompactWindowDeferred: deferred };
+}

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/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);
+}