@yemi33/minions 0.1.2086 → 0.1.2087

package/dashboard.js

@@ -2357,6 +2357,163 @@ function getStatusJson() {
   return _statusCacheJson;
 }
 
+// ── /state/<path> — raw state-file passthrough ────────────────────────────
+// Static-file handler that serves files from under MINIONS_DIR directly,
+// bypassing the /api/status assembled-snapshot cache. Per-page polls hit
+// this instead of /api/status so a stale outer cache cannot hold a fresh
+// disk write hostage. ETag = mtimeMs + size → 304 when unchanged.
+//
+// Safety:
+//   1. shared.sanitizePath rejects null bytes / .. / absolute paths and
+//      asserts the resolved target stays under MINIONS_DIR.
+//   2. Top-level dir must be in STATE_READ_ALLOWED_DIRS — no exposing
+//      config.json, .install-id, source code, .gitignored secrets.
+//   3. STATE_READ_DENIED_PATTERNS deny-lists sensitive files INSIDE
+//      allowed dirs (SQLite db, .backup sidecars, live-output.log,
+//      session.json — any of which leak credentials or runtime state).
+//   4. Symlinks are rejected outright (no follow → realpath round-trip).
+//   5. Directory paths return a JSON listing [{name,size,mtimeMs,isDir}],
+//      one level deep — needed for inbox/ and notes/inbox/ enumeration.
+const STATE_READ_ALLOWED_DIRS = new Set([
+  'projects', 'engine', 'prd', 'notes', 'plans',
+  'pipelines', 'knowledge', 'agents', 'watches.d',
+]);
+const STATE_READ_DENIED_PATTERNS = [
+  /(^|[\\/])state\.db($|-wal$|-shm$)/i,
+  /\.backup$/i,
+  /(^|[\\/])live-output\.log$/i,
+  /(^|[\\/])session\.json$/i,
+  /(^|[\\/])\.env($|\.)/i,
+];
+function _isStateReadPathDenied(rel) {
+  return STATE_READ_DENIED_PATTERNS.some(re => re.test(rel));
+}
+function _stateReadContentType(ext) {
+  switch (ext.toLowerCase()) {
+    case '.json': return 'application/json; charset=utf-8';
+    case '.md': return 'text/markdown; charset=utf-8';
+    case '.txt': case '.log': return 'text/plain; charset=utf-8';
+    default: return 'application/octet-stream';
+  }
+}
+function handleStateRead(req, res) {
+  const urlPath = req.url.split('?')[0];
+  const rel = decodeURIComponent(urlPath.slice('/state/'.length));
+  if (!rel) {
+    res.statusCode = 400;
+    res.setHeader('Content-Type', 'application/json');
+    res.end(JSON.stringify({ error: 'path required' }));
+    return;
+  }
+  // Top-level allowlist — first path segment must match.
+  const top = rel.split(/[\\/]/)[0];
+  if (!STATE_READ_ALLOWED_DIRS.has(top)) {
+    res.statusCode = 403;
+    res.setHeader('Content-Type', 'application/json');
+    res.end(JSON.stringify({ error: 'forbidden directory' }));
+    return;
+  }
+  if (_isStateReadPathDenied(rel)) {
+    res.statusCode = 403;
+    res.setHeader('Content-Type', 'application/json');
+    res.end(JSON.stringify({ error: 'forbidden file' }));
+    return;
+  }
+  let resolved;
+  try {
+    resolved = shared.sanitizePath(rel, MINIONS_DIR);
+  } catch (e) {
+    res.statusCode = 403;
+    res.setHeader('Content-Type', 'application/json');
+    res.end(JSON.stringify({ error: e.message }));
+    return;
+  }
+  let lstat;
+  try { lstat = fs.lstatSync(resolved); }
+  catch {
+    res.statusCode = 404;
+    res.setHeader('Content-Type', 'application/json');
+    res.end(JSON.stringify({ error: 'not found' }));
+    return;
+  }
+  // Reject symlinks outright — even if they point inside MINIONS_DIR, they
+  // can be swapped after the allowlist check (TOCTOU) to escape. Engine
+  // never writes symlinks into state dirs in normal operation.
+  if (lstat.isSymbolicLink()) {
+    res.statusCode = 403;
+    res.setHeader('Content-Type', 'application/json');
+    res.end(JSON.stringify({ error: 'symlinks not served' }));
+    return;
+  }
+  if (lstat.isDirectory()) {
+    // One-level directory listing for enumeration (inbox, archive, etc.).
+    // Per-entry stat lives inside the inner try-catch so a single bad entry
+    // doesn't fail the whole listing — bad entry just gets dropped.
+    const etag = '"dir-' + Math.floor(lstat.mtimeMs) + '"';
+    res.setHeader('ETag', etag);
+    res.setHeader('Cache-Control', 'private, max-age=0, must-revalidate');
+    if (req.headers['if-none-match'] === etag) {
+      res.statusCode = 304;
+      res.end();
+      return;
+    }
+    let entries;
+    try {
+      entries = fs.readdirSync(resolved).map(name => {
+        try {
+          const s = fs.lstatSync(path.join(resolved, name));
+          if (s.isSymbolicLink()) return null;
+          return {
+            name,
+            size: s.size,
+            mtimeMs: Math.floor(s.mtimeMs),
+            isDir: s.isDirectory(),
+          };
+        } catch { return null; }
+      }).filter(Boolean);
+    } catch (e) {
+      res.statusCode = 500;
+      res.setHeader('Content-Type', 'application/json');
+      res.end(JSON.stringify({ error: e.message }));
+      return;
+    }
+    res.statusCode = 200;
+    res.setHeader('Content-Type', 'application/json; charset=utf-8');
+    res.end(JSON.stringify({ path: rel.replace(/\\/g, '/'), entries }));
+    return;
+  }
+  // File path: mtime+size ETag, stream the bytes.
+  const etag = '"' + Math.floor(lstat.mtimeMs) + '-' + lstat.size + '"';
+  res.setHeader('ETag', etag);
+  res.setHeader('Cache-Control', 'private, max-age=0, must-revalidate');
+  if (req.headers['if-none-match'] === etag) {
+    res.statusCode = 304;
+    res.end();
+    return;
+  }
+  res.statusCode = 200;
+  res.setHeader('Content-Type', _stateReadContentType(path.extname(resolved)));
+  try {
+    const stream = fs.createReadStream(resolved);
+    stream.on('error', (err) => {
+      if (!res.headersSent) {
+        res.statusCode = 500;
+        res.setHeader('Content-Type', 'application/json');
+        res.end(JSON.stringify({ error: err.message }));
+      } else if (!res.writableEnded) {
+        res.end();
+      }
+    });
+    stream.pipe(res);
+  } catch (e) {
+    if (!res.headersSent) {
+      res.statusCode = 500;
+      res.setHeader('Content-Type', 'application/json');
+      res.end(JSON.stringify({ error: e.message }));
+    }
+  }
+}
+
 // Top-level /api/status request handler (W-mpehsyhv0017085a). Extracted from
 // the inline route handler so unit tests can call it with mock req/res and so
 // production routing has a single source of truth. The inline route delegates
@@ -10633,6 +10790,9 @@ What would you like to discuss or change? When you're happy, say "approve" and I
 
     // Status & health
     { method: 'GET', path: '/api/status', desc: 'Full dashboard status snapshot (agents, PRDs, work items, dispatch, etc.)', handler: handleStatus },
+    // Raw state-file passthrough (no /api/ prefix — this serves files, not API
+    // responses). Allowlisted top-level dirs only; mtime+size ETag → 304.
+    { method: 'GET', path: /^\/state\/.+/, desc: 'Serve a raw state file (or directory listing) from MINIONS_DIR with mtime/size ETag', handler: handleStateRead },
     { method: 'GET', path: '/api/browser-presence', desc: 'Whether a dashboard browser tab was recently active', handler: (req, res) => {
       return jsonReply(res, 200, _getDashboardBrowserPresence(), req);
     }},
@@ -11579,6 +11739,10 @@ module.exports = {
   refreshStatusAsync,
   handleStatus: _handleStatusRequest,
   invalidateStatusCache,
+  // Raw state-file passthrough — exported for direct unit testing.
+  handleStateRead,
+  STATE_READ_ALLOWED_DIRS,
+  STATE_READ_DENIED_PATTERNS,
   _getStatusCacheVersion,
   _setStatusRefreshHook,
   _resetStatusCacheForTesting,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.2086",
+  "version": "0.1.2087",
   "description": "Multi-agent AI dev team that runs from ~/.minions/ — five autonomous agents share a single engine, dashboard, and knowledge base",
   "bin": {
     "minions": "bin/minions.js"