agentgui 1.0.1117 → 1.0.1118

package/lib/http-routes/mutations.js

@@ -0,0 +1,199 @@
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+import {
+  confineToRoots, fsAllowRoots, sanitizeEntryName, safeErrMsg, readBody,
+  isAllowRoot, moveToTrash, restoreFromTrash, SECRET_RE,
+} from './shared.js';
+
+// --- File mutations ----------------------------------------------------
+// The Files surface is a real manager (fsbrowse-grade): rename, delete,
+// mkdir, upload. Every route re-confines via confineToRoots (realpath, so
+// a symlink inside a root cannot point a mutation outside it), refuses
+// the roots themselves as targets, and sanitizes any NEW name to a single
+// path component (sanitizeEntryName). All are POST/PUT-only with JSON or
+// raw-byte bodies; errors map to plain machine codes the client renders
+// as human copy.
+
+// POST /api/rename {path, newName} -> {ok, path}
+export async function handleRename(req, res, sendJSON) {
+  let body;
+  try { body = JSON.parse((await readBody(req, 64 * 1024)).toString('utf8') || '{}'); }
+  catch (e) { sendJSON(req, res, e.code === 'TOO_LARGE' ? 413 : 400, { error: 'bad request body' }); return; }
+  const allowRoots = fsAllowRoots();
+  const conf = confineToRoots(String(body.path || ''), allowRoots);
+  if (!conf.ok) { sendJSON(req, res, conf.reason === 'not found' ? 404 : 403, { error: 'forbidden: ' + conf.reason }); return; }
+  if (isAllowRoot(conf.realPath, allowRoots)) { sendJSON(req, res, 403, { error: 'forbidden: cannot rename an allowed root' }); return; }
+  const newName = sanitizeEntryName(body.newName);
+  if (!newName) { sendJSON(req, res, 400, { error: 'invalid name' }); return; }
+  if (SECRET_RE.test(newName)) { sendJSON(req, res, 403, { error: 'forbidden: secret/dotfile name' }); return; }
+  const target = path.join(path.dirname(conf.realPath), newName);
+  // The target stays in the same (already-confined) directory by
+  // construction, but re-check anyway so the invariant is local.
+  const tConf = confineToRoots(path.dirname(target), allowRoots);
+  if (!tConf.ok) { sendJSON(req, res, 403, { error: 'forbidden: target outside allowed roots' }); return; }
+  if (fs.existsSync(target)) { sendJSON(req, res, 409, { error: 'a file with that name already exists' }); return; }
+  try { fs.renameSync(conf.realPath, target); sendJSON(req, res, 200, { ok: true, path: target }); }
+  catch (err) { sendJSON(req, res, err.code === 'EACCES' || err.code === 'EPERM' ? 403 : 400, { error: safeErrMsg(err) }); }
+}
+
+// POST /api/move {path, destDir, overwrite?} -> {ok, path}. Moves an
+// entry into another directory; BOTH endpoints re-confine via realpath.
+// Refuses: a root as the source, a directory moved into itself or its
+// own subtree, and an existing target unless overwrite:true (and never
+// overwrites a directory).
+export async function handleMove(req, res, sendJSON) {
+  let body;
+  try { body = JSON.parse((await readBody(req, 64 * 1024)).toString('utf8') || '{}'); }
+  catch (e) { sendJSON(req, res, e.code === 'TOO_LARGE' ? 413 : 400, { error: 'bad request body' }); return; }
+  const allowRoots = fsAllowRoots();
+  const conf = confineToRoots(String(body.path || ''), allowRoots);
+  if (!conf.ok) { sendJSON(req, res, conf.reason === 'not found' ? 404 : 403, { error: 'forbidden: ' + conf.reason }); return; }
+  if (isAllowRoot(conf.realPath, allowRoots)) { sendJSON(req, res, 403, { error: 'forbidden: cannot move an allowed root' }); return; }
+  const dConf = confineToRoots(String(body.destDir || ''), allowRoots);
+  if (!dConf.ok) { sendJSON(req, res, dConf.reason === 'not found' ? 404 : 403, { error: 'forbidden: ' + dConf.reason }); return; }
+  let destIsDir = false;
+  try { destIsDir = fs.statSync(dConf.realPath).isDirectory(); } catch {}
+  if (!destIsDir) { sendJSON(req, res, 400, { error: 'destination is not a directory' }); return; }
+  const name = sanitizeEntryName(path.basename(conf.realPath));
+  if (!name) { sendJSON(req, res, 400, { error: 'invalid name' }); return; }
+  // A directory must never move into itself or its own subtree.
+  const srcPrefix = conf.realPath + path.sep;
+  if (dConf.realPath === conf.realPath || dConf.realPath.startsWith(srcPrefix)) {
+    sendJSON(req, res, 400, { error: 'cannot move a folder into itself' }); return;
+  }
+  const target = path.join(dConf.realPath, name);
+  if (target === conf.realPath) { sendJSON(req, res, 200, { ok: true, path: target }); return; }
+  if (fs.existsSync(target)) {
+    let targetIsDir = false;
+    try { targetIsDir = fs.lstatSync(target).isDirectory(); } catch {}
+    if (targetIsDir || body.overwrite !== true) {
+      sendJSON(req, res, 409, { error: 'a file with that name already exists' }); return;
+    }
+  }
+  try { fs.renameSync(conf.realPath, target); sendJSON(req, res, 200, { ok: true, path: target }); }
+  catch (err) {
+    const code = err.code === 'EACCES' || err.code === 'EPERM' ? 403 : 400;
+    sendJSON(req, res, code, { error: err.code === 'EXDEV' ? 'cannot move across drives' : err.message });
+  }
+}
+
+// POST /api/delete {path, recursive?} -> {ok}. Deleting a non-empty dir
+// requires recursive:true (the client confirms first).
+export async function handleDelete(req, res, sendJSON) {
+  let body;
+  try { body = JSON.parse((await readBody(req, 64 * 1024)).toString('utf8') || '{}'); }
+  catch (e) { sendJSON(req, res, e.code === 'TOO_LARGE' ? 413 : 400, { error: 'bad request body' }); return; }
+  const allowRoots = fsAllowRoots();
+  const conf = confineToRoots(String(body.path || ''), allowRoots);
+  if (!conf.ok) { sendJSON(req, res, conf.reason === 'not found' ? 404 : 403, { error: 'forbidden: ' + conf.reason }); return; }
+  if (isAllowRoot(conf.realPath, allowRoots)) { sendJSON(req, res, 403, { error: 'forbidden: cannot delete an allowed root' }); return; }
+  try {
+    const st = fs.lstatSync(conf.realPath);
+    // Soft-delete: move into a confined per-root .agentgui-trash/ instead
+    // of unlinking, so the only safety net isn't confirm-before (the
+    // pre-existing ConfirmDialog) but also undo-after, matching an
+    // fsbrowse-grade file manager. A non-empty directory without
+    // recursive=true still throws ENOTEMPTY BEFORE any move happens
+    // (checked via a dry probe) to keep that existing guard's semantics.
+    if (st.isDirectory() && body.recursive !== true) {
+      const dryEntries = fs.readdirSync(conf.realPath);
+      if (dryEntries.length) { sendJSON(req, res, 409, { error: 'directory is not empty' }); return; }
+    }
+    const trashInfo = moveToTrash(conf.realPath, allowRoots);
+    sendJSON(req, res, 200, { ok: true, trashId: trashInfo.trashId });
+  } catch (err) {
+    const code = err.code === 'ENOTEMPTY' ? 409 : (err.code === 'EACCES' || err.code === 'EPERM' ? 403 : (err.code === 'ENOENT' ? 404 : 400));
+    sendJSON(req, res, code, { error: err.code === 'ENOTEMPTY' ? 'directory is not empty' : err.message });
+  }
+}
+
+// POST /api/restore {trashId} -> {ok, path}. Undoes a /api/delete within
+// its retention window (trashRetentionMs, default 10 minutes) by moving
+// the entry back from .agentgui-trash/ to its original confined path.
+export async function handleRestore(req, res, sendJSON) {
+  let body;
+  try { body = JSON.parse((await readBody(req, 64 * 1024)).toString('utf8') || '{}'); }
+  catch (e) { sendJSON(req, res, e.code === 'TOO_LARGE' ? 413 : 400, { error: 'bad request body' }); return; }
+  try {
+    const restored = restoreFromTrash(String(body.trashId || ''), fsAllowRoots());
+    sendJSON(req, res, 200, { ok: true, path: restored.path });
+  } catch (err) {
+    sendJSON(req, res, err.code === 'NOT_FOUND' ? 404 : (err.code === 'CONFLICT' ? 409 : 400), { error: err.message });
+  }
+}
+
+// POST /api/mkdir {dir, name} -> {ok, path}. dir must exist inside roots.
+export async function handleMkdir(req, res, sendJSON) {
+  let body;
+  try { body = JSON.parse((await readBody(req, 64 * 1024)).toString('utf8') || '{}'); }
+  catch (e) { sendJSON(req, res, e.code === 'TOO_LARGE' ? 413 : 400, { error: 'bad request body' }); return; }
+  const allowRoots = fsAllowRoots();
+  const conf = confineToRoots(String(body.dir || ''), allowRoots);
+  if (!conf.ok) { sendJSON(req, res, conf.reason === 'not found' ? 404 : 403, { error: 'forbidden: ' + conf.reason }); return; }
+  const name = sanitizeEntryName(body.name);
+  if (!name) { sendJSON(req, res, 400, { error: 'invalid name' }); return; }
+  if (SECRET_RE.test(name)) { sendJSON(req, res, 403, { error: 'forbidden: secret/dotfile name' }); return; }
+  const target = path.join(conf.realPath, name);
+  if (fs.existsSync(target)) { sendJSON(req, res, 409, { error: 'a file with that name already exists' }); return; }
+  try { fs.mkdirSync(target); sendJSON(req, res, 200, { ok: true, path: target }); }
+  catch (err) { sendJSON(req, res, err.code === 'EACCES' || err.code === 'EPERM' ? 403 : 400, { error: err.message }); }
+}
+
+// PUT /api/upload-file?dir=<enc>&name=<enc> with raw file bytes as the
+// body (no multipart dependency; the client sends fetch(file)). 50MB cap,
+// never overwrites unless ?overwrite=1. Distinct path from the legacy
+// express-mounted /api/upload/:conversationId.
+export async function handleUploadFile(req, res, sendJSON) {
+  let qs;
+  try { qs = new URL(req.url, 'http://localhost').searchParams; } catch { qs = new URLSearchParams(); }
+  // Require Content-Length header: rejects chunked or missing-length requests
+  // that could claim any size. Pre-validates the announced size before streaming.
+  const contentLength = req.headers['content-length'];
+  if (!contentLength) {
+    sendJSON(req, res, 411, { error: 'length required' }); return;
+  }
+  const MAX_UPLOAD = 50 * 1024 * 1024;
+  const len = parseInt(contentLength, 10);
+  if (isNaN(len) || len < 0 || len > MAX_UPLOAD) {
+    sendJSON(req, res, 413, { error: `file too large (max ${MAX_UPLOAD} bytes)` }); return;
+  }
+  const allowRoots = fsAllowRoots();
+  const conf = confineToRoots(qs.get('dir') || '', allowRoots);
+  if (!conf.ok) { sendJSON(req, res, conf.reason === 'not found' ? 404 : 403, { error: 'forbidden: ' + conf.reason }); return; }
+  const name = sanitizeEntryName(qs.get('name'));
+  if (!name) { sendJSON(req, res, 400, { error: 'invalid name' }); return; }
+  if (SECRET_RE.test(name)) { sendJSON(req, res, 403, { error: 'forbidden: secret/dotfile name' }); return; }
+  const target = path.join(conf.realPath, name);
+  if (fs.existsSync(target) && qs.get('overwrite') !== '1') { sendJSON(req, res, 409, { error: 'a file with that name already exists' }); return; }
+  // Stream the upload body to a temp file to keep memory constant and
+  // avoid blocking the event loop with a large synchronous writeFileSync.
+  const tmpPath = target + '.tmp.' + crypto.randomBytes(6).toString('hex');
+  try {
+    await new Promise((resolve, reject) => {
+      const ws = fs.createWriteStream(tmpPath);
+      let total = 0;
+      ws.on('error', reject);
+      req.on('error', reject);
+      req.on('data', (chunk) => {
+        total += chunk.length;
+        if (total > MAX_UPLOAD) {
+          ws.destroy();
+          req.destroy();
+          const e = new Error('file too large (50MB cap)'); e.code = 'TOO_LARGE';
+          reject(e); return;
+        }
+        ws.write(chunk);
+      });
+      req.on('end', () => ws.end());
+      ws.on('finish', () => resolve(total));
+    });
+    fs.renameSync(tmpPath, target);
+    const uploadedSize = fs.statSync(target).size;
+    sendJSON(req, res, 200, { ok: true, path: target, size: uploadedSize });
+  } catch (err) {
+    try { fs.unlinkSync(tmpPath); } catch (_) {}
+    if (err.code === 'TOO_LARGE') { sendJSON(req, res, 413, { error: 'file too large (50MB cap)' }); return; }
+    sendJSON(req, res, err.code === 'EACCES' || err.code === 'EPERM' ? 403 : 400, { error: 'upload failed' });
+  }
+}

package/lib/http-routes/reads.js

@@ -0,0 +1,212 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import {
+  confineToRoots, fsAllowRoots, resolveConfinedPath, safeErrMsg, SECRET_RE,
+} from './shared.js';
+
+// Existence/shape probe for a proposed chat working directory, confined
+// to the same allowlist as the Files surface (an unconfined stat would be
+// a filesystem oracle). Returns {ok, dir} or a 403/404 with plain copy.
+export function handleStat(req, res, routePath, sendJSON) {
+  const decodedPath = resolveConfinedPath(req, routePath, 'path', '/api/stat');
+  const conf = confineToRoots(decodedPath, fsAllowRoots());
+  if (!conf.ok) { sendJSON(req, res, conf.reason === 'not found' ? 404 : 403, { error: conf.reason }); return; }
+  try {
+    const st = fs.statSync(conf.realPath);
+    sendJSON(req, res, 200, { ok: true, dir: st.isDirectory(), path: conf.realPath });
+  } catch (err) {
+    sendJSON(req, res, err.code === 'ENOENT' ? 404 : 403, { error: safeErrMsg(err) });
+  }
+}
+
+// Directory listing for the Files / folder-browser view (mirrors fsbrowse
+// /api/list). Confined to an allowlist root exactly like /api/image - the
+// normalize-then-prefix-check is the real guard (a `..` test after
+// path.normalize is a no-op). Returns {path, segments, entries} so the kit
+// FileGrid + BreadcrumbPath render directly. Allowed roots default to the
+// server cwd + Claude projects dir; widen via FS_ROOTS (path-separated).
+export function handleList(req, res, routePath, sendJSON) {
+  const decodedPath = resolveConfinedPath(req, routePath, 'dir', '/api/list');
+  const allowRoots = fsAllowRoots();
+  // Empty path = the first allow-root (a sane default landing dir).
+  const reqPath = !decodedPath ? allowRoots[0] : decodedPath;
+  const conf = confineToRoots(reqPath, allowRoots);
+  if (!conf.ok) {
+    const code = conf.reason === 'not found' ? 404 : 403;
+    sendJSON(req, res, code, { error: 'forbidden: ' + conf.reason }); return;
+  }
+  // Use the symlink-resolved real path for all reads.
+  const normalizedPath = conf.realPath;
+  try {
+    const st = fs.statSync(normalizedPath);
+    if (!st.isDirectory()) { sendJSON(req, res, 400, { error: 'not a directory' }); return; }
+    // Classify by extension into the kit's data-file-type buckets so
+    // FileGrid renders the right rail/icon. dir/symlink come from stat.
+    const EXT_TYPE = {
+      image: ['png','jpg','jpeg','gif','webp','svg','bmp','ico','avif'],
+      video: ['mp4','webm','mov','mkv','avi','m4v'],
+      audio: ['mp3','wav','ogg','flac','m4a','aac'],
+      code: ['js','mjs','cjs','ts','tsx','jsx','rs','go','py','rb','java','c','cpp','h','hpp','cs','php','sh','css','html','json','yml','yaml','toml','sql'],
+      text: ['txt','md','log','csv','env'],
+      archive: ['zip','tar','gz','tgz','rar','7z','bz2','xz'],
+      document: ['pdf','doc','docx','xls','xlsx','ppt','pptx','odt'],
+    };
+    const typeFor = (name, dirent) => {
+      if (dirent.isSymbolicLink()) return 'symlink';
+      if (dirent.isDirectory()) return 'dir';
+      const ext = path.extname(name).slice(1).toLowerCase();
+      for (const [t, exts] of Object.entries(EXT_TYPE)) if (exts.includes(ext)) return t;
+      return 'other';
+    };
+    const dirents = fs.readdirSync(normalizedPath, { withFileTypes: true }).filter((d) => !SECRET_RE.test(d.name));
+    const entries = dirents.map((d) => {
+      const full = path.join(normalizedPath, d.name);
+      let size = null, modified = null, permissions;
+      try {
+        const s = fs.statSync(full); size = s.isDirectory() ? null : s.size; modified = s.mtime.toISOString();
+        // Per-entry permission probe (mirrors fsbrowse checkPermissions) so
+        // the row reads honestly (read-only / no access) instead of a silent
+        // size:null on a stat failure. A stat success means at least read.
+        const perms = ['read'];
+        try { fs.accessSync(full, fs.constants.W_OK); perms.push('write'); } catch (_) {}
+        permissions = perms;
+      } catch (e) {
+        // Could not stat (commonly EACCES): mark no-access so the client
+        // disables open + shows the tag, rather than failing silently.
+        permissions = e && e.code === 'EACCES' ? 'EACCES' : [];
+      }
+      return { name: d.name, type: typeFor(d.name, d), size, modified, path: full, permissions };
+    }).sort((a, b) => (a.type === 'dir' ? 0 : 1) - (b.type === 'dir' ? 0 : 1) || a.name.localeCompare(b.name));
+    // Breadcrumb segments from the absolute path (drive/root aware).
+    const segments = normalizedPath.split(/[\\\/]+/).filter(Boolean);
+    sendJSON(req, res, 200, { path: normalizedPath, segments, entries, roots: allowRoots });
+  } catch (err) {
+    const code = err && err.code === 'ENOENT' ? 404 : (err && err.code === 'EACCES' ? 403 : 400);
+    sendJSON(req, res, code, { error: safeErrMsg(err) });
+  }
+}
+
+// Raw file bytes for the Files preview pane. Confined to the SAME
+// allowlist roots as /api/list (server cwd + Claude projects dir, widened
+// via FS_ROOTS). Same normalize-then-prefix-check guard. Capped at 512KB
+// and limited to reasonable text/code/image types so this is never a
+// generic arbitrary-file reader. Images are served via /api/image; this
+// returns text/* with utf-8.
+export function handleFile(req, res, routePath) {
+  const decodedPath = resolveConfinedPath(req, routePath, 'path', '/api/file/');
+  const allowRoots = fsAllowRoots();
+  const conf = confineToRoots(decodedPath, allowRoots);
+  if (!conf.ok) { res.writeHead(conf.reason === 'not found' ? 404 : 403); res.end('Forbidden'); return; }
+  const normalizedPath = conf.realPath;
+  // Block secret-bearing files regardless of root: dotfiles, env/key/cert
+  // material, and credential stores must never be readable through the
+  // Files preview even when they sit inside an allowed root.
+  const base = path.basename(normalizedPath);
+  if (SECRET_RE.test(base)) { res.writeHead(403); res.end('Forbidden'); return; }
+  // Only known text/code extensions (images go through /api/image). An
+  // unknown/binary extension is rejected, never served as octet-stream.
+  // env/conf/cfg/ini are dropped - they commonly carry secrets.
+  const TEXT_EXTS = new Set([
+    'js','mjs','cjs','ts','tsx','jsx','rs','go','py','rb','java','c','cpp','h','hpp','cs','php','sh','css','html','json','yml','yaml','toml','sql',
+    'txt','md','log','csv','xml','gitignore','dockerfile','svg',
+  ]);
+  const ext = path.extname(normalizedPath).slice(1).toLowerCase()
+    || path.basename(normalizedPath).toLowerCase();
+  if (!TEXT_EXTS.has(ext)) { res.writeHead(403); res.end('Forbidden: unsupported type'); return; }
+  try {
+    const st = fs.statSync(normalizedPath);
+    if (!st.isFile()) { res.writeHead(400); res.end('Not a file'); return; }
+    const MAX = 512 * 1024;
+    const fd = fs.openSync(normalizedPath, 'r');
+    const len = Math.min(st.size, MAX);
+    const buf = Buffer.alloc(len);
+    fs.readSync(fd, buf, 0, len, 0);
+    fs.closeSync(fd);
+    res.writeHead(200, {
+      'Content-Type': 'text/plain; charset=utf-8',
+      'Cache-Control': 'no-cache',
+      'X-File-Truncated': st.size > MAX ? '1' : '0',
+    });
+    res.end(buf);
+  } catch (err) {
+    const code = err && err.code === 'ENOENT' ? 404 : (err && err.code === 'EACCES' ? 403 : 400);
+    res.writeHead(code); res.end(safeErrMsg(err));
+  }
+}
+
+// Confined raw-bytes download (any type) with an attachment disposition,
+// so the Files view can offer download on a row. Same allowlist + realpath
+// confinement as /api/file and /api/image - never a generic file reader.
+export function handleDownload(req, res, routePath) {
+  const decodedPath = resolveConfinedPath(req, routePath, 'path', '/api/download/');
+  const allowRoots = fsAllowRoots();
+  const conf = confineToRoots(decodedPath, allowRoots);
+  if (!conf.ok) { res.writeHead(conf.reason === 'not found' ? 404 : 403); res.end('Forbidden'); return; }
+  const normalizedPath = conf.realPath;
+  // Same secret-name block as /api/file: a download must not exfiltrate
+  // .env/.pem/.key/credential material just because it streams bytes.
+  if (SECRET_RE.test(path.basename(normalizedPath))) { res.writeHead(403); res.end('Forbidden'); return; }
+  try {
+    const st = fs.statSync(normalizedPath);
+    if (!st.isFile()) { res.writeHead(400); res.end('Not a file'); return; }
+    const MAX = 50 * 1024 * 1024; // 50MB cap so a download can't exhaust memory
+    if (st.size > MAX) { res.writeHead(413); res.end('File too large to download'); return; }
+    const base = path.basename(normalizedPath);
+    const asciiName = base.replace(/[\\"\r\n]/g, '').replace(/[^\x20-\x7e]/g, '_');
+    res.writeHead(200, {
+      'Content-Type': 'application/octet-stream',
+      'Content-Disposition': 'attachment; filename="' + asciiName + '"; filename*=UTF-8\'\'' + encodeURIComponent(base),
+      'Content-Length': String(st.size),
+      'Cache-Control': 'no-cache',
+    });
+    const rs = fs.createReadStream(normalizedPath);
+    rs.on('error', (streamErr) => { if (!res.writableEnded) res.destroy(streamErr); });
+    rs.pipe(res);
+  } catch (err) {
+    const code = err && err.code === 'ENOENT' ? 404 : (err && err.code === 'EACCES' ? 403 : 400);
+    res.writeHead(code); res.end(safeErrMsg(err));
+  }
+}
+
+// Confined image bytes with a content-type allowlist (SVG intentionally
+// excluded - see inline comment below). Its own allowlist roots (Claude
+// projects dir + IMAGE_ROOTS), distinct from fsAllowRoots(), because the
+// user home is never a default root for arbitrary image reads.
+export function handleImage(req, res, routePath, sendJSON) {
+  const decodedPath = resolveConfinedPath(req, routePath, 'path', '/api/image/');
+  // Confine reads to an allowlist root. Without this the route is an
+  // arbitrary-file-read of any image-extensioned path on the host (the
+  // prior `includes('..')` guard is a no-op after path.normalize resolves
+  // the segments). Allowed roots: the Claude projects dir (history images)
+  // only; add more via IMAGE_ROOTS (path-separated). The user home is NOT
+  // a default root - it covers ~/.ssh, ~/.aws, dotfiles etc., so an image
+  // route reaching all of home is a broad read of anything image-shaped.
+  // confineToRoots also realpath-resolves so a symlink inside a root can't
+  // point an image read at an out-of-root file.
+  const allowRoots = [
+    process.env.CLAUDE_PROJECTS_DIR || path.join(os.homedir(), '.claude', 'projects'),
+    ...(process.env.IMAGE_ROOTS ? process.env.IMAGE_ROOTS.split(path.delimiter) : []),
+  ].map(r => path.normalize(r));
+  const conf = confineToRoots(decodedPath, allowRoots);
+  if (!conf.ok) { res.writeHead(conf.reason === 'not found' ? 404 : 403); res.end(conf.reason === 'not found' ? 'Not found' : 'Forbidden'); return; }
+  const normalizedPath = conf.realPath;
+  try {
+    const ext = path.extname(normalizedPath).toLowerCase();
+    const mimeTypes = { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.webp': 'image/webp' };
+    // SVG is intentionally excluded: browsers render SVG as a live document
+    // in the app's origin, so an agent-written SVG with a <script src=CDN>
+    // would execute in the agentgui origin (CSP allows unpkg/jsdelivr).
+    // Files preview uses /api/file/download (attachment) for SVG.
+    const contentType = mimeTypes[ext];
+    if (!contentType) { res.writeHead(403); res.end('Forbidden'); return; }
+    const imgSt = fs.statSync(normalizedPath);
+    const IMG_MAX = 20 * 1024 * 1024; // 20MB hard cap
+    if (imgSt.size > IMG_MAX) { res.writeHead(413); res.end('Image too large'); return; }
+    // Always stream to avoid blocking the event loop on large synchronous reads.
+    res.writeHead(200, { 'Content-Type': contentType, 'Cache-Control': 'no-cache', 'Content-Length': String(imgSt.size) });
+    const imgRs = fs.createReadStream(normalizedPath);
+    imgRs.on('error', (streamErr) => { if (!res.writableEnded) res.destroy(streamErr); });
+    imgRs.pipe(res);
+  } catch (err) { sendJSON(req, res, 400, { error: 'cannot read image' }); }
+}

package/lib/http-routes/shared.js

@@ -0,0 +1,213 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import crypto from 'crypto';
+
+// Module-level platform constant — never changes at runtime.
+export const IS_WINDOWS = os.platform() === 'win32';
+
+// Confine a requested filesystem path to an allowlist of roots. Two layers:
+//   1. normalize + resolved-prefix check on the LEXICAL path (blocks `../`
+//      traversal, which path.normalize collapses so a literal `..` test is a
+//      no-op);
+//   2. fs.realpathSync + the SAME prefix check on the REAL path, so a symlink
+//      that lives inside an allowed root but points outside it cannot escape
+//      (the lexical path passes layer 1, the resolved target fails layer 2).
+// Returns { ok, realPath, reason }. realPath is the symlink-resolved absolute
+// path to stat/read; callers use it, never the raw input. A non-existent path
+// has no realpath yet, so it fails closed with reason 'not found'.
+export function confineToRoots(inputPath, allowRoots) {
+  const norms = allowRoots.map(r => path.normalize(r));
+  const expanded = inputPath && inputPath.startsWith('~') ? inputPath.replace('~', os.homedir()) : inputPath;
+  const normalizedPath = path.normalize(expanded || '');
+  const isAbsolute = IS_WINDOWS ? /^[A-Za-z]:[\\/]/.test(normalizedPath) : normalizedPath.startsWith('/');
+  const within = (p) => {
+    const np = IS_WINDOWS ? p.toLowerCase() : p;
+    return norms.some(root => {
+      const r = IS_WINDOWS ? root.toLowerCase() : root;
+      return np === r || np.startsWith(r + path.sep);
+    });
+  };
+  if (!isAbsolute || !within(normalizedPath)) return { ok: false, reason: 'path outside allowed roots' };
+  // realpath the target and re-confine, defeating symlink escape (TOCTOU/link
+  // traversal). If realpath throws (missing path / broken link) fail closed.
+  let realPath;
+  try { realPath = fs.realpathSync(normalizedPath); }
+  catch (e) { return { ok: false, reason: e && e.code === 'ENOENT' ? 'not found' : 'cannot resolve path', code: e && e.code }; }
+  if (!within(realPath)) return { ok: false, reason: 'symlink target outside allowed roots' };
+  return { ok: true, realPath };
+}
+
+// Mask ?token=VALUE in a URL string before logging so credentials never
+// appear in server logs or error messages.
+export function maskToken(url) {
+  if (typeof url !== 'string') return url;
+  return url.replace(/([?&]token=)[^&]*/gi, '$1***');
+}
+
+// Secret-bearing basenames that must never be readable through ANY confined
+// raw-bytes route (preview or download), even when they sit inside an allowed
+// root: dotfiles, env/key/cert material, and credential stores. One const so
+// /api/file and /api/download can never drift apart.
+export const SECRET_RE = /(^\.|\.(env|pem|key|crt|p12|pfx)$|secret|credential|\.npmrc$|\.netrc$)/i;
+
+// The allowlist the Files surface operates within: server cwd + Claude
+// projects dir, widened via FS_ROOTS (path-separated). One construction so
+// /api/list,file,download and the mutation routes can never drift apart.
+export function fsAllowRoots() {
+  const roots = [
+    process.env.CLAUDE_PROJECTS_DIR || path.join(os.homedir(), '.claude', 'projects'),
+  ];
+  // The server cwd is only exposed when PASSWORD is set (the witnessed
+  // localhost-PASSWORD deploy lists the repo tree) or FS_ALLOW_CWD=1 is opted
+  // in. An open no-PASSWORD deploy must NOT expose the whole server tree.
+  if (process.env.PASSWORD || process.env.FS_ALLOW_CWD === '1') {
+    roots.push(process.env.STARTUP_CWD || process.cwd());
+  }
+  if (process.env.FS_ROOTS) roots.push(...process.env.FS_ROOTS.split(path.delimiter));
+  return roots.map(r => path.normalize(r));
+}
+
+// A new file/dir name must be a single path component: no separators, no
+// traversal, no NTFS alternate-data-stream colon, no reserved Windows device
+// names, no trailing dot/space (Windows silently strips them, aliasing two
+// names onto one entry). Returns the trimmed name or null when inadmissible.
+export function sanitizeEntryName(name) {
+  if (typeof name !== 'string') return null;
+  const n = name.trim();
+  if (!n || n.length > 255) return null;
+  if (/[\\/:*?"<>|\x00-\x1f]/.test(n)) return null;
+  if (n === '.' || n === '..') return null;
+  if (/[. ]$/.test(n)) return null;
+  if (/^(con|prn|aux|nul|com[1-9]|lpt[1-9])(\.|$)/i.test(n)) return null;
+  return n;
+}
+
+// Every confined filesystem route accepts its target path via a `?path=`/
+// `?dir=` query param, preferred over a path SEGMENT. A reverse proxy's
+// proxy_pass URI normalization can decode-then-reencode the request path,
+// collapsing an encoded %2F segment slash back into a literal '/' before
+// forwarding - the app then sees extra path segments instead of one opaque
+// one, strips what it thinks is a leading '/', and silently turns an absolute
+// path into a relative one that fails confinement even for genuinely
+// accessible directories/files. A query param is untouched by that
+// normalization on any proxy in front of this app. `legacyPrefix` is the old
+// `/api/xxx/<path>` route prefix, still accepted for any caller not yet
+// updated to the query-param form.
+export function resolveConfinedPath(req, routePath, queryKey, legacyPrefix) {
+  const url = new URL(req.url, 'http://x');
+  const qVal = url.searchParams.get(queryKey);
+  if (qVal != null) return qVal;
+  const raw = routePath.split('?')[0].slice(legacyPrefix.length).replace(/^\//, '');
+  return raw ? decodeURIComponent(raw) : '';
+}
+
+// Map a Node.js filesystem error code to a safe human-readable string that
+// does not disclose host paths or internal stack context. Used everywhere an
+// err.message would otherwise be returned to the client.
+export function safeErrMsg(err) {
+  if (!err) return 'unknown error';
+  switch (err.code) {
+    case 'ENOENT': return 'file not found';
+    case 'EACCES': return 'permission denied';
+    case 'EPERM':  return 'operation not permitted';
+    case 'EISDIR': return 'path is a directory';
+    case 'ENOTDIR': return 'path is not a directory';
+    case 'ENOTEMPTY': return 'directory is not empty';
+    case 'EEXIST': return 'file already exists';
+    case 'EXDEV': return 'cannot move across drives';
+    case 'EMFILE': return 'too many open files';
+    case 'ENOSPC': return 'no space left on device';
+    default: return 'operation failed';
+  }
+}
+
+// Read a request body with a hard size cap; resolves a Buffer or rejects with
+// .code='TOO_LARGE' so the caller can answer 413 without buffering the rest.
+export function readBody(req, maxBytes) {
+  return new Promise((resolve, reject) => {
+    const chunks = []; let total = 0;
+    req.on('data', (c) => {
+      total += c.length;
+      if (total > maxBytes) { const e = new Error('body too large'); e.code = 'TOO_LARGE'; req.destroy(); reject(e); return; }
+      chunks.push(c);
+    });
+    req.on('end', () => resolve(Buffer.concat(chunks)));
+    req.on('error', reject);
+  });
+}
+
+// True when the resolved path IS one of the allowlist roots - the roots
+// themselves are never mutation targets (rename/delete of a root would orphan
+// the whole surface).
+export function isAllowRoot(realPath, allowRoots) {
+  const p = IS_WINDOWS ? realPath.toLowerCase() : realPath;
+  return allowRoots.some(r => (IS_WINDOWS ? r.toLowerCase() : r) === p);
+}
+
+// --- Soft-delete (trash) -----------------------------------------------
+// /api/delete moves entries into <root>/.agentgui-trash/<trashId>__<name>
+// instead of unlinking, giving a short undo window. In-memory index only
+// (server restart forfeits the undo window - acceptable since the retention
+// window itself is short and this is a convenience net on top of, not a
+// replacement for, the pre-delete ConfirmDialog). Purged after
+// TRASH_RETENTION_MS or when trashIndex grows past TRASH_MAX_ENTRIES
+// (oldest-first), so a long-running server's trash dir can't grow unbounded.
+const TRASH_DIR_NAME = '.agentgui-trash';
+const TRASH_RETENTION_MS = parseInt(process.env.AGENTGUI_TRASH_RETENTION_MS || '', 10) || 10 * 60 * 1000;
+const TRASH_MAX_ENTRIES = 200;
+const trashIndex = new Map(); // trashId -> { trashPath, originalPath, root, deletedAt }
+
+function purgeExpiredTrash() {
+  const now = Date.now();
+  for (const [id, info] of trashIndex) {
+    if (now - info.deletedAt > TRASH_RETENTION_MS) {
+      try { fs.rmSync(info.trashPath, { recursive: true, force: true }); } catch { /* already gone */ }
+      trashIndex.delete(id);
+    }
+  }
+  if (trashIndex.size > TRASH_MAX_ENTRIES) {
+    const sorted = [...trashIndex.entries()].sort((a, b) => a[1].deletedAt - b[1].deletedAt);
+    for (const [id, info] of sorted.slice(0, trashIndex.size - TRASH_MAX_ENTRIES)) {
+      try { fs.rmSync(info.trashPath, { recursive: true, force: true }); } catch {}
+      trashIndex.delete(id);
+    }
+  }
+}
+
+// Which allowed root a confined realPath lives under - the trash dir sits
+// alongside it (still inside the SAME root, so confineToRoots covers the
+// trash path too - no new unconfined surface).
+function rootFor(realPath, allowRoots) {
+  const p = IS_WINDOWS ? realPath.toLowerCase() : realPath;
+  return allowRoots.find(r => { const rr = IS_WINDOWS ? r.toLowerCase() : r; return p === rr || p.startsWith(rr + path.sep); });
+}
+
+export function moveToTrash(realPath, allowRoots) {
+  purgeExpiredTrash();
+  const root = rootFor(realPath, allowRoots);
+  if (!root) { const e = new Error('not confined to an allowed root'); e.code = 'EACCES'; throw e; }
+  const trashDir = path.join(root, TRASH_DIR_NAME);
+  fs.mkdirSync(trashDir, { recursive: true });
+  const trashId = crypto.randomBytes(8).toString('hex');
+  const base = path.basename(realPath);
+  const trashPath = path.join(trashDir, trashId + '__' + base);
+  fs.renameSync(realPath, trashPath);
+  trashIndex.set(trashId, { trashPath, originalPath: realPath, root, deletedAt: Date.now() });
+  return { trashId };
+}
+
+export function restoreFromTrash(trashId, allowRoots) {
+  const info = trashIndex.get(trashId);
+  if (!info) { const e = new Error('nothing to restore - the undo window has expired or this was already restored'); e.code = 'NOT_FOUND'; throw e; }
+  // Re-confine the ORIGINAL path at restore time (not trust the cached one
+  // blindly) - the allowlist itself doesn't change at runtime, but this keeps
+  // restore honoring the exact same confinement contract every other route does.
+  const conf = confineToRoots(info.originalPath, allowRoots);
+  if (!conf.ok && conf.reason !== 'not found') { const e = new Error('restore target is no longer inside an accessible folder'); e.code = 'CONFLICT'; throw e; }
+  if (fs.existsSync(info.originalPath)) { const e = new Error('a file already exists at the original location'); e.code = 'CONFLICT'; throw e; }
+  fs.mkdirSync(path.dirname(info.originalPath), { recursive: true });
+  fs.renameSync(info.trashPath, info.originalPath);
+  trashIndex.delete(trashId);
+  return { path: info.originalPath };
+}