@polderlabs/bizar 8.0.0 → 9.0.0

package/.claude/worktrees/kanban-overhaul/bizar-dash/src/server/lib/path-safe.mjs

@@ -0,0 +1,283 @@
+/**
+ * src/server/lib/path-safe.mjs
+ *
+ * Helpers for the file-browser / scan endpoints that need to accept
+ * an arbitrary absolute path from the authenticated client and decide
+ * whether it is safe to operate on.
+ *
+ * The dashboard runs on a developer's machine, so the boundary here
+ * is the user's home directory. Any path outside `os.homedir()` (and
+ * any explicitly-listed additional allowed root, validated by the
+ * caller) is rejected before we ever call `fs` on it.
+ *
+ * No `..` traversal escapes — `path.resolve` normalizes first, then
+ * we check the resolved string against the allow-list.
+ */
+import { resolve as pathResolve, sep, isAbsolute } from 'node:path';
+import { homedir } from 'node:os';
+import { randomBytes } from 'node:crypto';
+
+/**
+ * Normalize an arbitrary list of root paths and dedupe them. Empty /
+ * non-string entries are dropped silently so callers can pass
+ * `readSettings().dashboard.projectsDirectory` directly.
+ *
+ * @param {Array<string | null | undefined>} roots
+ * @returns {string[]}
+ */
+function normalizeRoots(roots) {
+  const out = [];
+  const seen = new Set();
+  for (const raw of roots) {
+    if (typeof raw !== 'string') continue;
+    const trimmed = raw.trim();
+    if (!trimmed) continue;
+    const resolved = pathResolve(trimmed);
+    if (seen.has(resolved)) continue;
+    seen.add(resolved);
+    out.push(resolved);
+  }
+  return out;
+}
+
+/**
+ * Build the default allow-list: the user's home plus any explicit
+ * extra roots. The caller is expected to validate the extras against
+ * home before calling this (we don't try to be clever about Windows
+ * reparse points, symlinks, etc. — this is a developer-tool boundary,
+ * not a chroot).
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.home]           — override for `os.homedir()`
+ * @param {Array<string>} [opts.extras]  — additional absolute roots (already resolved)
+ * @returns {string[]}
+ */
+export function defaultAllowedRoots({ home, extras } = {}) {
+  return normalizeRoots([home || homedir(), ...(extras || [])]);
+}
+
+/**
+ * Build the per-request allow-list straight from a settings object.
+ * Each configured entry is re-validated against home; entries that
+ * fail validation (escape home, empty, non-string, NUL/backslash,
+ * …) are silently dropped. The intent is to survive a tampered
+ * settings.json: the writer (`validateDashboardSettings`) catches
+ * the bad values, but the reader has to be robust against anything
+ * on disk.
+ *
+ * Includes both:
+ *   - `dashboard.allowedRoots[]` (operator-declared extras)
+ *   - `dashboard.projectsDirectory` (single legacy extra)
+ *
+ * @param {object} opts
+ * @param {Record<string, unknown> | null | undefined} opts.settings
+ * @param {string} [opts.home]             — override for `os.homedir()`
+ * @returns {string[]}
+ */
+export function buildAllowedRootsFromSettings({ settings, home } = {}) {
+  const homeResolved = home || homedir();
+  const extras = [];
+  const configured = settings?.dashboard?.allowedRoots;
+  if (Array.isArray(configured)) {
+    for (const candidate of configured) {
+      if (typeof candidate !== 'string' || !candidate.trim()) continue;
+      const safe = resolveSafePath(candidate, [homeResolved]);
+      if (safe) extras.push(safe);
+      // Silently skip entries that fail validation. The Settings UI
+      // (frontend) is responsible for surfacing a warning when a
+      // user-typed root is silently dropped.
+    }
+  }
+  const proj = settings?.dashboard?.projectsDirectory;
+  if (typeof proj === 'string' && proj.trim()) {
+    const safe = resolveSafePath(proj, [homeResolved]);
+    if (safe) extras.push(safe);
+  }
+  return defaultAllowedRoots({ home: homeResolved, extras });
+}
+
+/**
+ * Resolve and authorize a requested absolute path against an
+ * allow-list of roots.
+ *
+ * Rules:
+ *   - The input must be a non-empty string.
+ *   - The path is `path.resolve()`d — `..` segments collapse.
+ *   - The resolved path must be `===` to one of the allowed roots,
+ *     OR live strictly beneath it (segment-aware — `pathA` does NOT
+ *     count as "inside" `pathB` if `pathB` is just a prefix string).
+ *   - Dotfile / dotdir roots (e.g. `~/.ssh`, `~/.aws`) are rejected
+ *     even when they live under home. The frontend can still SEE them
+ *     in listings (so users know the directory exists) but cannot
+ *     enter them via the browser.
+ *
+ * Returns `null` on any failure. The caller is expected to translate
+ * `null` into a 403 with a clear message.
+ *
+ * @param {unknown} requestedPath
+ * @param {string[]} allowedRoots
+ * @returns {string | null}
+ */
+export function resolveSafePath(requestedPath, allowedRoots) {
+  if (typeof requestedPath !== 'string') return null;
+  const trimmed = requestedPath.trim();
+  if (!trimmed) return null;
+  const resolved = pathResolve(trimmed);
+
+  const roots = Array.isArray(allowedRoots) ? allowedRoots : [];
+  for (const root of roots) {
+    if (typeof root !== 'string' || !root) continue;
+    const resolvedRoot = pathResolve(root);
+    if (resolved === resolvedRoot) {
+      if (isDotRoot(resolved)) return null;
+      return resolved;
+    }
+    // Strict segment-aware prefix: ensure a separator boundary so
+    // `/home/user/foo` is NOT considered inside `/home/user/foobar`.
+    const rootWithSep = resolvedRoot.endsWith(sep)
+      ? resolvedRoot
+      : resolvedRoot + sep;
+    if (resolved.startsWith(rootWithSep)) {
+      if (isDotRoot(resolved)) return null;
+      return resolved;
+    }
+  }
+  return null;
+}
+
+/**
+ * Return `true` if the path is (or lives directly inside) a dotdir
+ * at the home root. We deliberately do NOT match deeper dotdirs
+ * (`/home/user/projects/.secret` is fine to enter) — only the ones
+ * at the top of the home tree are treated as sensitive.
+ *
+ * @param {string} resolvedPath
+ * @param {string} [home]
+ * @returns {boolean}
+ */
+export function isDotRoot(resolvedPath, home = homedir()) {
+  if (typeof resolvedPath !== 'string') return false;
+  const homeRoot = pathResolve(home);
+  const homeWithSep = homeRoot.endsWith(sep) ? homeRoot : homeRoot + sep;
+  if (resolvedPath === homeRoot) return false;
+  if (!resolvedPath.startsWith(homeWithSep)) return false;
+  const tail = resolvedPath.slice(homeWithSep.length);
+  if (!tail) return false;
+  // Only first-level dotdirs under home are blocked.
+  const first = tail.split(sep)[0];
+  return first.startsWith('.') && first.length > 1;
+}
+
+// --- Background-agent logPath reconstruction ------------------------------
+//
+// The plugin's `bgr_<id>.json` state files include a `logPath` field
+// built as `${worktree}/.cline/log/${id}.log`. If `worktree` was
+// empty or `/` when the bg instance was spawned, the resulting
+// `logPath` is broken (e.g. `//.cline/log/...`) and no log file
+// can ever be written. The bg-retry loop calls into this helper to
+// repair the field before re-dispatching.
+//
+// `deriveAbsoluteBgLogPath(worktree, instanceId)` always returns an
+// absolute path. It falls back to the user's home directory when
+// `worktree` is missing or non-absolute. Never throws — a bad input
+// produces a synthetic `~/.cache/bizar/logs/<id>.log` rather than
+// crashing the retry loop.
+//
+// v3.11.1 — Note on log path correctness:
+//   The plugin's `LogWriter` (plugins/bizar/src/report.ts:147) writes
+//   to `${logDir}/${sessionId}.log` where `logDir` defaults to
+//   `~/.cache/bizar/logs` (plugins/bizar/src/options.ts:88). The
+//   bg-spawn tool records a DIFFERENT path —
+//   `${worktree}/.cline/log/${instanceId}.log` — in the state
+//   file. Nothing ever writes to that path. This module's
+//   `deriveAbsoluteBgLogPath` historically returned the same broken
+//   path; the new `getActualBgLogPath` below returns the path the
+//   LogWriter actually writes to. Use that for any operator-facing
+//   `tail -F` (e.g. the tmux wrap in task-delegator.mjs).
+
+const FALLBACK_LOG_DIR = pathResolve(homedir(), '.cache', 'bizar', 'logs');
+
+/**
+ * Resolve the per-session log directory used by the plugin's
+ * `LogWriter`. The plugin's default is `~/.cache/bizar/logs`
+ * (configurable via the `logDir` option in `cline.json`). We
+ * honor the `BIZAR_LOG_DIR` env var first, fall back to the
+ * plugin's default, and never throw.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.env]  — env-var bag to read (defaults to process.env)
+ * @returns {string}
+ */
+export function getBgLogDir({ env } = {}) {
+  const source = env || process.env;
+  const fromEnv = source?.BIZAR_LOG_DIR;
+  if (typeof fromEnv === 'string' && fromEnv.trim()) {
+    const resolved = pathResolve(fromEnv);
+    return resolved;
+  }
+  return FALLBACK_LOG_DIR;
+}
+
+/**
+ * Resolve the per-session log path the plugin's `LogWriter` actually
+ * writes to. Use this for any operator-facing `tail -F` so the user
+ * sees real activity rather than a phantom-file error.
+ *
+ * Important: the LogWriter keys files by SESSION id (not instance
+ * id). When you only have an `instanceId` (e.g. `bg_<sessionId16>`),
+ * pass it as `sessionId` — the function will accept any non-empty
+ * string and sanitize it.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.sessionId]  — the cline session id (or any unique key)
+ * @param {string} [opts.env]        — env-var bag to read
+ * @returns {string} absolute path that exists or will exist once the plugin writes
+ */
+export function getActualBgLogPath({ sessionId, env } = {}) {
+  const safeId = typeof sessionId === 'string' && sessionId.length > 0
+    ? sessionId.replace(/[^a-zA-Z0-9_.-]/g, '_')
+    : `unknown_${randomBytes(4).toString('hex')}`;
+  return pathResolve(getBgLogDir({ env }), `${safeId}.log`);
+}
+
+/**
+ * @param {unknown} worktree
+ * @param {string} instanceId
+ * @returns {string}
+ */
+export function deriveAbsoluteBgLogPath(worktree, instanceId) {
+  const safeId = typeof instanceId === 'string' && instanceId.length > 0
+    ? instanceId.replace(/[^a-zA-Z0-9_.-]/g, '_')
+    : `unknown_${randomBytes(4).toString('hex')}`;
+  const base = typeof worktree === 'string' && worktree.length > 0 && isAbsolute(worktree)
+    ? pathResolve(worktree)
+    : FALLBACK_LOG_DIR;
+  return pathResolve(base, '.cline', 'log', `${safeId}.log`);
+}
+
+/**
+ * Decide whether a `logPath` value stored on a bg instance needs to
+ * be repaired. A path is considered broken when it is:
+ *   - not a string
+ *   - empty
+ *   - not absolute
+ *   - contains a literal double-slash sequence (`//` outside of the
+ *     protocol prefix) — a tell-tale sign of `${empty}/${...}`
+ *     concatenation
+ *
+ * @param {unknown} logPath
+ * @returns {boolean}
+ */
+export function isBrokenBgLogPath(logPath) {
+  if (typeof logPath !== 'string' || logPath.length === 0) return true;
+  if (!isAbsolute(logPath)) return true;
+  // Look for `//` not at the protocol position. Cheap heuristic that
+  // catches the user's `//.cline/log/...` case without requiring
+  // a full URL parser.
+  const idx = logPath.indexOf('//');
+  if (idx === -1) return false;
+  // Allow a leading `//` only on Windows-style UNC paths like `\\server\share`.
+  // On POSIX, a leading `/` followed by another `/` is always broken.
+  if (idx === 0) return true;
+  return false;
+}

package/.claude/worktrees/kanban-overhaul/bizar-dash/src/server/lib/rate-limit.mjs

@@ -0,0 +1,122 @@
+/**
+ * src/server/lib/rate-limit.mjs
+ *
+ * v4.8.0 — Per-IP token bucket rate limiter for /api/chat and /api/v2/event.
+ *
+ * Implementation notes
+ * ────────────────────
+ * Each scope + remote IP pair gets its own bucket. Buckets refill
+ * continuously at `refillPerSecond` tokens / second, capped at
+ * `capacity`. Every accepted request consumes one token; rejected
+ * requests do not consume, and include `Retry-After` so polite clients
+ * can back off.
+ *
+ * Why a token bucket and not a sliding window?
+ *   - O(1) memory per IP (two floats + a timestamp).
+ *   - Refill is implicit — no periodic timer, no sweep job.
+ *   - Burst tolerance is built in (up to `capacity` in one go).
+ *
+ * Headers set on every accepted response:
+ *   - X-RateLimit-Limit       : capacity
+ *   - X-RateLimit-Remaining   : Math.floor(tokens) after consumption
+ *   - X-RateLimit-Reset       : seconds until full (omitted on success
+ *                               because it's not well-defined at
+ *                               `capacity`; only emitted on 429)
+ *
+ * Headers set on a 429 response:
+ *   - Retry-After             : seconds until 1 token is available
+ *   - X-RateLimit-Limit       : capacity
+ *   - X-RateLimit-Remaining   : 0
+ *   - X-RateLimit-Reset       : seconds until 1 token is available
+ *
+ * The bucket map is process-global. Tests call `clearBuckets()` to
+ * reset between cases so they don't leak state.
+ */
+
+const buckets = new Map();
+
+/**
+ * @param {object} opts
+ * @param {number} opts.capacity         — max tokens per bucket
+ * @param {number} opts.refillPerSecond  — tokens added per second
+ * @param {string} [opts.scope='global'] — bucket-key prefix; isolates chat vs event buckets
+ * @returns {import('express').RequestHandler}
+ */
+export function createRateLimiter({ capacity, refillPerSecond, scope = 'global' }) {
+  if (!Number.isFinite(capacity) || capacity <= 0) {
+    throw new TypeError('createRateLimiter: capacity must be a positive number');
+  }
+  if (!Number.isFinite(refillPerSecond) || refillPerSecond <= 0) {
+    throw new TypeError('createRateLimiter: refillPerSecond must be a positive number');
+  }
+  if (typeof scope !== 'string' || !scope) {
+    throw new TypeError('createRateLimiter: scope must be a non-empty string');
+  }
+
+  return function rateLimit(req, res, next) {
+    const ip = req.ip || (req.socket && req.socket.remoteAddress) || 'unknown';
+    const key = `${scope}:${ip}`;
+    const now = Date.now();
+    const bucket = buckets.get(key) || { tokens: capacity, lastRefill: now };
+
+    // Refill based on elapsed wall-clock time. Cap at capacity.
+    const elapsedSec = (now - bucket.lastRefill) / 1000;
+    bucket.tokens = Math.min(capacity, bucket.tokens + elapsedSec * refillPerSecond);
+    bucket.lastRefill = now;
+
+    if (bucket.tokens < 1) {
+      // Compute retry-after: seconds until we have at least 1 token.
+      const deficit = 1 - bucket.tokens;
+      const retryAfterSec = Math.max(1, Math.ceil(deficit / refillPerSecond));
+      res.set('Retry-After', String(retryAfterSec));
+      res.set('X-RateLimit-Limit', String(capacity));
+      res.set('X-RateLimit-Remaining', '0');
+      res.set('X-RateLimit-Reset', String(retryAfterSec));
+      // Persist the (still-empty) bucket so subsequent calls also see 0.
+      buckets.set(key, bucket);
+      // The 429 response carries the rate-limit scope so the operator
+      // can tell chat-throttling from event-throttling in logs.
+      res.set('X-RateLimit-Scope', scope);
+      res.status(429).json({
+        error: 'rate_limited',
+        message: 'Too many requests',
+        scope,
+        retryAfter: retryAfterSec,
+      });
+      return;
+    }
+
+    bucket.tokens -= 1;
+    buckets.set(key, bucket);
+    res.set('X-RateLimit-Limit', String(capacity));
+    res.set('X-RateLimit-Remaining', String(Math.floor(bucket.tokens)));
+    res.set('X-RateLimit-Scope', scope);
+    next();
+  };
+}
+
+/**
+ * Reset all buckets. Tests call this in setup/teardown to avoid
+ * leaking state between cases. Production code should not need it.
+ */
+export function clearBuckets() {
+  buckets.clear();
+}
+
+/**
+ * Inspect a single bucket. Returns undefined if no requests have been
+ * recorded for `key` yet. Exported for tests only.
+ *
+ * @param {string} key
+ */
+export function _peekBucket(key) {
+  return buckets.get(key);
+}
+
+/**
+ * Total number of buckets currently tracked. Exported for tests /
+ * observability.
+ */
+export function _bucketSize() {
+  return buckets.size;
+}

package/.claude/worktrees/kanban-overhaul/bizar-dash/src/server/logger.mjs

@@ -0,0 +1,71 @@
+/**
+ * src/server/logger.mjs
+ *
+ * v4.7.0 — Structured JSON logger with level filtering.
+ *
+ * Replaces ad-hoc `console.log('[module] message')` calls across the
+ * server with a single, level-gated logger that emits one JSON object
+ * per line. Output goes to the matching console.* stream (log/warn/
+ * error) so existing terminal capture keeps working, but the body is
+ * machine-parseable.
+ *
+ * Level selection: BIZAR_LOG_LEVEL env var (debug | info | warn | error).
+ * Default `info` matches the existing behaviour — everything but debug
+ * is visible. Set `debug` to surface verbose tracing during development.
+ *
+ * Usage:
+ *   import { info, warn, error, child } from './logger.mjs';
+ *   info('server started', { port: 4317 });
+ *   warn('rate limited', { module: 'lightrag', err: e.message });
+ *   const log = child({ module: 'overview' });
+ *   log.info('snapshot built', { size: 1234 });
+ */
+
+const LEVELS = { debug: 10, info: 20, warn: 30, error: 40 };
+const ENV_LEVEL = process.env.BIZAR_LOG_LEVEL;
+const currentLevel = LEVELS[ENV_LEVEL] !== undefined ? ENV_LEVEL : 'info';
+
+function format(level, msg, ctx) {
+  const entry = {
+    ts: new Date().toISOString(),
+    level,
+    msg,
+    ...(ctx && typeof ctx === 'object' ? ctx : {}),
+  };
+  return JSON.stringify(entry);
+}
+
+function shouldLog(level) {
+  return LEVELS[currentLevel] <= LEVELS[level];
+}
+
+export function debug(msg, ctx) {
+  if (shouldLog('debug')) console.log(format('debug', msg, ctx));
+}
+
+export function info(msg, ctx) {
+  if (shouldLog('info')) console.log(format('info', msg, ctx));
+}
+
+export function warn(msg, ctx) {
+  if (shouldLog('warn')) console.warn(format('warn', msg, ctx));
+}
+
+export function error(msg, ctx) {
+  if (shouldLog('error')) console.error(format('error', msg, ctx));
+}
+
+/**
+ * Build a child logger that binds a context object to every log call.
+ * Useful for tagging a series of related entries with a module/session id.
+ */
+export function child(ctx) {
+  return {
+    debug: (m, c) => debug(m, { ...ctx, ...(c && typeof c === 'object' ? c : {}) }),
+    info: (m, c) => info(m, { ...ctx, ...(c && typeof c === 'object' ? c : {}) }),
+    warn: (m, c) => warn(m, { ...ctx, ...(c && typeof c === 'object' ? c : {}) }),
+    error: (m, c) => error(m, { ...ctx, ...(c && typeof c === 'object' ? c : {}) }),
+  };
+}
+
+export { currentLevel };