agentgui 1.0.1117 → 1.0.1118

package/lib/http-handler.js

@@ -3,215 +3,11 @@ import path from 'path';
 import os from 'os';
 import crypto from 'crypto';
 import * as term from './terminal.js';
+import { confineToRoots, fsAllowRoots, maskToken, SECRET_RE } from './http-routes/shared.js';
+import { handleStat, handleList, handleFile, handleDownload, handleImage } from './http-routes/reads.js';
+import { handleRename, handleMove, handleDelete, handleRestore, handleMkdir, handleUploadFile } from './http-routes/mutations.js';
 
-// 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'.
-// 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***');
-}
-
-// Module-level platform constant — never changes at runtime.
-const IS_WINDOWS = os.platform() === 'win32';
-
-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 };
-}
-
-// 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.
-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.
-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.
-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.
-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).
-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); });
-}
-
-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 };
-}
-
-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 };
-}
+export { confineToRoots, fsAllowRoots, maskToken, SECRET_RE };
 
 export function createHttpHandler({ BASE_URL, expressApp, queries, sendJSON, serveFile, staticDir, messageQueues, getWss, activeExecutions, getACPStatus, discoveredAgents, PKG_VERSION, RATE_LIMIT_MAX, rateLimitMap, routes, PORT }) {
   // Warn operators when CORS_ORIGIN=* is combined with no PASSWORD: any
@@ -390,7 +186,12 @@ export function createHttpHandler({ BASE_URL, expressApp, queries, sendJSON, ser
     if (req.method === 'POST' || req.method === 'PUT' || req.method === 'DELETE') {
       const sfs = req.headers['sec-fetch-site'];
       const ct = (req.headers['content-type'] || '').toLowerCase();
-      const sameSite = !sfs || sfs === 'same-origin' || sfs === 'none';
+      // A MISSING Sec-Fetch-Site header must NOT be treated as same-site -
+      // older browsers/non-browser clients omitting it would otherwise pass
+      // unconditionally regardless of true origin. Only an explicit
+      // same-origin/none value counts; a present-but-absent header falls
+      // through to the Origin-host check below.
+      const sameSite = sfs === 'same-origin' || sfs === 'none';
       // Only application/json counts as a non-cross-site body now: a simple
       // cross-site <form> can send only urlencoded/multipart/text-plain, and
       // octet-stream / empty CT were too broad an escape (a no-CORS fetch can
@@ -464,19 +265,10 @@ export function createHttpHandler({ BASE_URL, expressApp, queries, sendJSON, ser
         return;
       }
 
-      // 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.
+      // Existence/shape probe for a proposed chat working directory - see
+      // lib/http-routes/reads.js for the confinement contract.
       if (routePath.startsWith('/api/stat') && req.method === 'GET') {
-        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) });
-        }
+        handleStat(req, res, routePath, sendJSON);
         return;
       }
 
@@ -519,392 +311,69 @@ export function createHttpHandler({ BASE_URL, expressApp, queries, sendJSON, ser
           if (h) { await h(req, res); return; }
         } catch (_) {}
       }
-      // 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).
+      // Directory listing for the Files / folder-browser view - see
+      // lib/http-routes/reads.js for the confinement contract.
       if (routePath.startsWith('/api/list')) {
-        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) });
-        }
+        handleList(req, res, routePath, sendJSON);
         return;
       }
 
-      // 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.
+      // Raw file bytes for the Files preview pane - see lib/http-routes/reads.js.
       if (routePath.startsWith('/api/file/') || routePath.startsWith('/api/file?')) {
-        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));
-        }
+        handleFile(req, res, routePath);
         return;
       }
 
-      // 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.
+      // Confined raw-bytes download - see lib/http-routes/reads.js.
       if (routePath.startsWith('/api/download/') || routePath.startsWith('/api/download?')) {
-        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));
-        }
+        handleDownload(req, res, routePath);
         return;
       }
 
       // --- 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.
+      // mkdir, upload. See lib/http-routes/mutations.js for the shared
+      // confinement/sanitization contract every route below follows.
 
       // POST /api/rename {path, newName} -> {ok, path}
       if (routePath.split('?')[0] === '/api/rename' && req.method === 'POST') {
-        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) }); }
+        await handleRename(req, res, sendJSON);
         return;
       }
 
-      // 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).
+      // POST /api/move {path, destDir, overwrite?} -> {ok, path}
       if (routePath.split('?')[0] === '/api/move' && req.method === 'POST') {
-        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 });
-        }
+        await handleMove(req, res, sendJSON);
         return;
       }
 
-      // POST /api/delete {path, recursive?} -> {ok}. Deleting a non-empty dir
-      // requires recursive:true (the client confirms first).
+      // POST /api/delete {path, recursive?} -> {ok}
       if (routePath.split('?')[0] === '/api/delete' && req.method === 'POST') {
-        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 });
-        }
+        await handleDelete(req, res, sendJSON);
         return;
       }
 
-      // 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.
+      // POST /api/restore {trashId} -> {ok, path}
       if (routePath.split('?')[0] === '/api/restore' && req.method === 'POST') {
-        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 });
-        }
+        await handleRestore(req, res, sendJSON);
         return;
       }
 
-      // POST /api/mkdir {dir, name} -> {ok, path}. dir must exist inside roots.
+      // POST /api/mkdir {dir, name} -> {ok, path}
       if (routePath.split('?')[0] === '/api/mkdir' && req.method === 'POST') {
-        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 }); }
+        await handleMkdir(req, res, sendJSON);
         return;
       }
 
-      // 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.
+      // PUT /api/upload-file?dir=<enc>&name=<enc> with raw file bytes as the body
       if (routePath.split('?')[0] === '/api/upload-file' && req.method === 'PUT') {
-        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' });
-        }
+        await handleUploadFile(req, res, sendJSON);
         return;
       }
 
+      // Confined image bytes - see lib/http-routes/reads.js.
       if (routePath.startsWith('/api/image/') || routePath.startsWith('/api/image?')) {
-        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' }); }
+        handleImage(req, res, routePath, sendJSON);
         return;
       }