@musashishao/folderforge 1.2.0

package/dist/policy/approvals.js

@@ -0,0 +1,143 @@
+import { randomUUID } from 'node:crypto';
+import { mkdirSync, readFileSync, existsSync, appendFileSync, writeFileSync, renameSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { logger } from '../core/logger.js';
+/**
+ * Approval queue. The dashboard reads/resolves these.
+ *
+ * Session-scoped approvals remember the tool name so repeated calls pass within
+ * the same session. When constructed with a `persistPath`, every state change is
+ * appended to an append-only JSONL log and replayed on startup so pending and
+ * resolved approvals survive a restart.
+ */
+export class ApprovalEngine {
+    requests = new Map();
+    sessionAllowed = new Set();
+    persistPath;
+    restoreSession;
+    constructor(opts = {}) {
+        this.persistPath = opts.persistPath;
+        this.restoreSession = opts.restoreSession ?? false;
+        if (this.persistPath)
+            this.load();
+    }
+    create(tool, args, risk, reason) {
+        const req = {
+            id: `appr_${randomUUID().slice(0, 8)}`,
+            tool,
+            args,
+            risk,
+            reason,
+            state: 'pending',
+            createdAt: Date.now(),
+            scope: 'once',
+        };
+        this.requests.set(req.id, req);
+        this.append(req);
+        return req;
+    }
+    isSessionAllowed(tool) {
+        return this.sessionAllowed.has(tool);
+    }
+    approve(id, scope = 'once') {
+        const req = this.requests.get(id);
+        if (!req || req.state !== 'pending')
+            return req;
+        req.state = 'approved';
+        req.scope = scope;
+        req.resolvedAt = Date.now();
+        if (scope === 'session')
+            this.sessionAllowed.add(req.tool);
+        this.append(req);
+        return req;
+    }
+    deny(id) {
+        const req = this.requests.get(id);
+        if (!req || req.state !== 'pending')
+            return req;
+        req.state = 'denied';
+        req.resolvedAt = Date.now();
+        this.append(req);
+        return req;
+    }
+    get(id) {
+        return this.requests.get(id);
+    }
+    pending() {
+        return [...this.requests.values()].filter((r) => r.state === 'pending');
+    }
+    all() {
+        return [...this.requests.values()].sort((a, b) => b.createdAt - a.createdAt);
+    }
+    /**
+     * Replay the persisted JSONL log. Each line is the latest snapshot of one
+     * request keyed by id, so later lines overwrite earlier ones. After loading
+     * we compact the file to one line per request to keep it from growing forever.
+     */
+    load() {
+        const path = this.persistPath;
+        if (!path || !existsSync(path))
+            return;
+        let lines;
+        try {
+            lines = readFileSync(path, 'utf8').split('\n');
+        }
+        catch (err) {
+            logger.warn({ path, err: String(err) }, 'Failed to read approvals store; starting empty');
+            return;
+        }
+        let loaded = 0;
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            try {
+                const req = JSON.parse(trimmed);
+                if (req && typeof req.id === 'string') {
+                    this.requests.set(req.id, req);
+                    loaded++;
+                }
+            }
+            catch {
+                // Skip corrupt lines rather than failing startup.
+            }
+        }
+        if (this.restoreSession) {
+            for (const req of this.requests.values()) {
+                if (req.state === 'approved' && req.scope === 'session') {
+                    this.sessionAllowed.add(req.tool);
+                }
+            }
+        }
+        logger.info({ path, loaded }, 'Loaded persisted approvals');
+        this.compact();
+    }
+    /** Append the current snapshot of one request to the JSONL log. */
+    append(req) {
+        const path = this.persistPath;
+        if (!path)
+            return;
+        try {
+            mkdirSync(dirname(path), { recursive: true });
+            appendFileSync(path, JSON.stringify(req) + '\n', 'utf8');
+        }
+        catch (err) {
+            logger.warn({ path, id: req.id, err: String(err) }, 'Failed to persist approval');
+        }
+    }
+    /** Rewrite the log with exactly one current line per request (atomic). */
+    compact() {
+        const path = this.persistPath;
+        if (!path)
+            return;
+        try {
+            const body = [...this.requests.values()].map((r) => JSON.stringify(r)).join('\n');
+            const tmp = `${path}.tmp`;
+            writeFileSync(tmp, body ? body + '\n' : '', 'utf8');
+            renameSync(tmp, path);
+        }
+        catch (err) {
+            logger.warn({ path, err: String(err) }, 'Failed to compact approvals store');
+        }
+    }
+}

package/dist/policy/command-policy.js

@@ -0,0 +1,99 @@
+/**
+ * Patterns that are always blocked (CRITICAL), regardless of policy mode.
+ */
+const CRITICAL_PATTERNS = [
+    /\brm\s+-rf?\s+\/(?:\s|$)/,
+    /\brm\s+-rf?\s+~(?:\/|\s|$)/,
+    /\bsudo\b/,
+    /\bmkfs\b/,
+    /\bdd\s+if=/,
+    /\bchmod\s+-R\s+777\s+\//,
+    /\bchown\s+-R\b/,
+    /\bcurl\b[^|]*\|\s*(?:bash|sh)\b/,
+    /\bwget\b[^|]*\|\s*(?:bash|sh)\b/,
+    /\bgit\s+reset\s+--hard\b/,
+    /\bgit\s+clean\s+-[a-z]*f/,
+    /\bgit\s+push\b[^&|;]*--force\b/,
+    /\bdocker\s+system\s+prune\b/,
+    /\bkubectl\s+delete\b/,
+    /\bterraform\s+apply\b/,
+    /\bmv\s+\S+\s+\/dev\/null\b/,
+    /:\(\)\s*\{.*\|.*&\s*\}\s*;/, // fork bomb
+];
+/**
+ * Patterns considered HIGH risk (require approval).
+ */
+const HIGH_PATTERNS = [
+    /\bgit\s+push\b/,
+    /\bgit\s+reset\b/,
+    /\bdocker\s+compose\s+down\b/,
+    /\bdocker\s+rm\b/,
+    /\bnpm\s+publish\b/,
+    /\brm\s+-rf?\b/,
+];
+/**
+ * Patterns considered MEDIUM risk (allowed in safe/dev, audited).
+ */
+const MEDIUM_PATTERNS = [
+    /\bnpm\s+(install|i|ci|add)\b/,
+    /\bpnpm\s+(install|add)\b/,
+    /\byarn\s+(add|install)\b/,
+    /\bpip\s+install\b/,
+    /\bdocker\s+compose\s+up\b/,
+    /\bmake\b/,
+    /\b(npm|pnpm|yarn)\s+run\s+build\b/,
+];
+export class CommandPolicy {
+    blocked;
+    constructor(blockedCommands) {
+        this.blocked = blockedCommands;
+    }
+    /** Substring/glob-ish blocklist from config, on top of the built-in regex set. */
+    matchesConfigBlocklist(command) {
+        const cmd = command.toLowerCase();
+        for (const entry of this.blocked) {
+            const pat = entry.toLowerCase();
+            if (pat.includes('*')) {
+                // very loose wildcard: split on '*' and check ordered substrings
+                const parts = pat.split('*').filter(Boolean);
+                let idx = 0;
+                let ok = true;
+                for (const p of parts) {
+                    const found = cmd.indexOf(p.trim(), idx);
+                    if (found === -1) {
+                        ok = false;
+                        break;
+                    }
+                    idx = found + p.length;
+                }
+                if (ok)
+                    return entry;
+            }
+            else if (cmd.includes(pat)) {
+                return entry;
+            }
+        }
+        return undefined;
+    }
+    classify(command) {
+        const trimmed = command.trim();
+        for (const re of CRITICAL_PATTERNS) {
+            if (re.test(trimmed)) {
+                return { risk: 'CRITICAL', blockedReason: `Matches destructive pattern: ${re}`, matched: re.source };
+            }
+        }
+        const cfgHit = this.matchesConfigBlocklist(trimmed);
+        if (cfgHit) {
+            return { risk: 'CRITICAL', blockedReason: `Matches blocked command rule: ${cfgHit}`, matched: cfgHit };
+        }
+        for (const re of HIGH_PATTERNS) {
+            if (re.test(trimmed))
+                return { risk: 'HIGH', matched: re.source };
+        }
+        for (const re of MEDIUM_PATTERNS) {
+            if (re.test(trimmed))
+                return { risk: 'MEDIUM', matched: re.source };
+        }
+        return { risk: 'LOW' };
+    }
+}

package/dist/policy/glob-match.js

@@ -0,0 +1,61 @@
+/**
+ * Minimal, dependency-free glob matcher supporting:
+ *   *      -> any chars except '/'
+ *   **     -> any chars including '/'
+ *   ?      -> single char except '/'
+ *   {a,b}  -> alternation
+ *   .      -> literal dot
+ * Patterns are matched against forward-slash paths.
+ */
+function globToRegExp(glob) {
+    let re = '';
+    for (let i = 0; i < glob.length; i++) {
+        const c = glob[i];
+        if (c === '*') {
+            if (glob[i + 1] === '*') {
+                // ** (optionally followed by /)
+                if (glob[i + 2] === '/') {
+                    re += '(?:.*/)?';
+                    i += 2;
+                }
+                else {
+                    re += '.*';
+                    i += 1;
+                }
+            }
+            else {
+                re += '[^/]*';
+            }
+        }
+        else if (c === '?') {
+            re += '[^/]';
+        }
+        else if (c === '{') {
+            const end = glob.indexOf('}', i);
+            if (end > -1) {
+                const parts = glob.slice(i + 1, end).split(',').map(escapeLiteral);
+                re += `(?:${parts.join('|')})`;
+                i = end;
+            }
+            else {
+                re += '\\{';
+            }
+        }
+        else {
+            re += escapeLiteral(c ?? '');
+        }
+    }
+    return new RegExp(`^${re}$`);
+}
+function escapeLiteral(s) {
+    return s.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+}
+const cache = new Map();
+export default function picomatchLite(pattern, value) {
+    let re = cache.get(pattern);
+    if (!re) {
+        re = globToRegExp(pattern);
+        cache.set(pattern, re);
+    }
+    return re.test(value);
+}

package/dist/policy/path-policy.js

@@ -0,0 +1,73 @@
+import { realpathSync, existsSync } from 'node:fs';
+import { resolve, relative, isAbsolute, sep, dirname } from 'node:path';
+import picomatchLite from './glob-match.js';
+import { PathEscapeError } from '../core/errors.js';
+/**
+ * PathPolicy enforces the workspace boundary:
+ *  - every path must resolve inside an allowed directory
+ *  - symlink escapes are rejected
+ *  - denied globs (secrets, node_modules, git internals) are blocked
+ */
+export class PathPolicy {
+    allowed;
+    deniedGlobs;
+    constructor(allowedDirectories, deniedGlobs) {
+        this.allowed = allowedDirectories.map((d) => resolve(d));
+        this.deniedGlobs = deniedGlobs;
+    }
+    /** Resolve a (possibly relative) path against the project root and validate it. */
+    resolveSafe(inputPath, projectRoot) {
+        const abs = isAbsolute(inputPath) ? resolve(inputPath) : resolve(projectRoot, inputPath);
+        this.assertInsideAllowed(abs);
+        this.assertNotDenied(abs, projectRoot);
+        this.assertNoSymlinkEscape(abs);
+        return abs;
+    }
+    isInsideAllowed(abs) {
+        return this.allowed.some((root) => {
+            const rel = relative(root, abs);
+            return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+        });
+    }
+    assertInsideAllowed(abs) {
+        if (!this.isInsideAllowed(abs)) {
+            throw new PathEscapeError(`Path is outside allowed directories: ${abs}`);
+        }
+    }
+    isDenied(abs, projectRoot) {
+        const rel = relative(projectRoot, abs).split(sep).join('/');
+        const candidates = [rel, abs.split(sep).join('/')];
+        return this.deniedGlobs.some((g) => candidates.some((c) => picomatchLite(g, c)));
+    }
+    assertNotDenied(abs, projectRoot) {
+        if (this.isDenied(abs, projectRoot)) {
+            throw new PathEscapeError(`Path is denied by policy (secret/ignored): ${abs}`);
+        }
+        // Extra hard guards for sensitive home folders.
+        const lowered = abs.toLowerCase();
+        const sensitive = ['/.ssh/', '/.aws/', '/.gnupg/', '/.config/gcloud/', '/.kube/'];
+        if (sensitive.some((s) => lowered.includes(s))) {
+            throw new PathEscapeError(`Path touches a protected credential folder: ${abs}`);
+        }
+    }
+    /** Resolve symlinks on the nearest existing ancestor and re-check the boundary. */
+    assertNoSymlinkEscape(abs) {
+        let probe = abs;
+        while (!existsSync(probe)) {
+            const parent = dirname(probe);
+            if (parent === probe)
+                return; // reached root, nothing exists yet
+            probe = parent;
+        }
+        let real;
+        try {
+            real = realpathSync(probe);
+        }
+        catch {
+            return;
+        }
+        if (!this.isInsideAllowed(real)) {
+            throw new PathEscapeError(`Symlink escapes the workspace boundary: ${abs} -> ${real}`);
+        }
+    }
+}

package/dist/policy/policy-engine.js

@@ -0,0 +1,156 @@
+import { PathPolicy } from './path-policy.js';
+import { CommandPolicy } from './command-policy.js';
+import { SecretPolicy } from './secret-policy.js';
+import { ApprovalEngine } from './approvals.js';
+import { RISK_ORDER } from './risk.js';
+import { PolicyDeniedError, ApprovalRequiredError } from '../core/errors.js';
+import { resolve } from 'node:path';
+/**
+ * The PolicyEngine ties together path, command, secret policies, the risk
+ * model, the policy mode, and the approval queue into a single decision point.
+ */
+export class PolicyEngine {
+    config;
+    path;
+    command;
+    secret;
+    approvals;
+    mode;
+    requireApproval;
+    constructor(config) {
+        this.config = config;
+        this.path = new PathPolicy(config.workspace.allowedDirectories, config.workspace.deniedGlobs);
+        this.command = new CommandPolicy(config.policy.blockedCommands);
+        this.secret = new SecretPolicy(config.secretScan);
+        // Persist approvals under the project's .folderforge dir so pending and
+        // resolved requests survive restarts. Falls back to in-memory if unset.
+        const persistPath = config.workspace.defaultProject
+            ? resolve(config.workspace.defaultProject, '.folderforge', 'approvals.jsonl')
+            : undefined;
+        this.approvals = new ApprovalEngine(persistPath ? { persistPath } : {});
+        this.mode = config.policy.defaultMode;
+        this.requireApproval = new Set(config.policy.requireApproval);
+    }
+    getMode() {
+        return this.mode;
+    }
+    setMode(mode) {
+        this.mode = mode;
+    }
+    describe() {
+        return {
+            mode: this.mode,
+            requireApproval: [...this.requireApproval],
+            blockedCommands: this.config.policy.blockedCommands,
+            allowedDirectories: this.config.workspace.allowedDirectories,
+            deniedGlobs: this.config.workspace.deniedGlobs,
+        };
+    }
+    /**
+     * Evaluate whether a tool call may proceed.
+     * @param toolName name of the tool
+     * @param risk computed risk for this specific call
+     * @param mutates whether the call mutates state
+     * @param args original args (recorded on approval requests)
+     */
+    evaluate(toolName, risk, mutates, args) {
+        // CRITICAL is denied in every mode except an explicit danger-mode approval.
+        if (risk === 'CRITICAL') {
+            if (this.mode !== 'danger') {
+                return { kind: 'deny', risk, reason: `CRITICAL action blocked in ${this.mode} mode.` };
+            }
+            // A session-scoped approval (pre-granted via the dashboard/approval tools)
+            // lets the tool through without re-prompting on every call.
+            if (this.approvals.isSessionAllowed(toolName)) {
+                return { kind: 'allow', risk };
+            }
+            return this.toApproval(toolName, risk, args, 'CRITICAL action requires explicit approval.');
+        }
+        // readonly: any mutation is denied.
+        if (this.mode === 'readonly' && mutates) {
+            return { kind: 'deny', risk, reason: 'Workspace is in readonly mode; mutations are blocked.' };
+        }
+        // Explicit approval list or HIGH risk -> approval.
+        const needsApproval = this.requireApproval.has(toolName) || RISK_ORDER[risk] >= RISK_ORDER.HIGH;
+        if (needsApproval) {
+            // danger mode intentionally bypasses approval gating for non-CRITICAL
+            // actions: the operator has opted into an "anything goes" mode.
+            if (this.mode === 'danger') {
+                return { kind: 'allow', risk };
+            }
+            if (this.approvals.isSessionAllowed(toolName)) {
+                return { kind: 'allow', risk };
+            }
+            return this.toApproval(toolName, risk, args, `${toolName} (${risk}) requires approval.`);
+        }
+        // MEDIUM allowed in safe/dev/danger; audited by caller.
+        return { kind: 'allow', risk };
+    }
+    toApproval(toolName, risk, args, reason) {
+        const req = this.approvals.create(toolName, args, risk, reason);
+        return { kind: 'approval', risk, approvalId: req.id, reason };
+    }
+    /**
+     * Dry-run a tool call and explain the decision WITHOUT side effects.
+     *
+     * Unlike {@link evaluate}, this never creates an approval request, never
+     * records audit events, and never mutates session state. It mirrors the same
+     * decision logic and returns a structured, human-readable explanation so an
+     * agent can reason about whether a call would be allowed, denied, or gated.
+     */
+    explain(toolName, risk, mutates, args = {}) {
+        const factors = [];
+        let decision;
+        let reason;
+        if (risk === 'CRITICAL') {
+            factors.push('risk is CRITICAL');
+            if (this.mode !== 'danger') {
+                decision = 'deny';
+                reason = `CRITICAL action blocked in ${this.mode} mode.`;
+            }
+            else {
+                decision = 'approval';
+                reason = 'CRITICAL action requires explicit approval.';
+                factors.push('mode is danger (CRITICAL allowed only via approval)');
+            }
+        }
+        else if (this.mode === 'readonly' && mutates) {
+            factors.push('mode is readonly and the tool mutates state');
+            decision = 'deny';
+            reason = 'Workspace is in readonly mode; mutations are blocked.';
+        }
+        else {
+            const onApprovalList = this.requireApproval.has(toolName);
+            const highRisk = RISK_ORDER[risk] >= RISK_ORDER.HIGH;
+            if (onApprovalList)
+                factors.push(`tool is in requireApproval list`);
+            if (highRisk)
+                factors.push(`risk is ${risk} (>= HIGH)`);
+            if (onApprovalList || highRisk) {
+                if (this.approvals.isSessionAllowed(toolName)) {
+                    factors.push('a session-scoped approval is already active for this tool');
+                    decision = 'allow';
+                    reason = `${toolName} is allowed for this session.`;
+                }
+                else {
+                    decision = 'approval';
+                    reason = `${toolName} (${risk}) requires approval.`;
+                }
+            }
+            else {
+                factors.push(`risk is ${risk} and allowed in ${this.mode} mode`);
+                decision = 'allow';
+                reason = `${toolName} (${risk}) is allowed.`;
+            }
+        }
+        return { decision, risk, reason, mode: this.mode, mutates, factors };
+    }
+    /** Convenience: throws unless the decision is allow. */
+    enforce(decision) {
+        if (decision.kind === 'deny')
+            throw new PolicyDeniedError(decision.reason);
+        if (decision.kind === 'approval') {
+            throw new ApprovalRequiredError(decision.reason, decision.approvalId);
+        }
+    }
+}

package/dist/policy/rate-limiter.js

@@ -0,0 +1,96 @@
+const DAY_MS = 24 * 60 * 60 * 1000;
+/**
+ * Sliding-window per-tool rate limiter with an optional rolling daily quota.
+ *
+ * The limiter is intentionally in-memory and per-process: it guards a single
+ * running server against runaway agents, not a distributed cluster. Each tool
+ * gets its own bucket; the effective rule is `overrides[tool]` falling back to
+ * `default`.
+ *
+ * Call {@link check} to evaluate without recording, or {@link hit} to evaluate
+ * and record an accepted call. The registry uses {@link hit} so that denied
+ * calls do not consume quota.
+ */
+export class RateLimiter {
+    config;
+    now;
+    buckets = new Map();
+    constructor(config, now = Date.now) {
+        this.config = config;
+        this.now = now;
+    }
+    ruleFor(tool) {
+        return this.config.overrides[tool] ?? this.config.default;
+    }
+    /** Evaluate without recording a call. */
+    check(tool) {
+        return this.evaluate(tool, false);
+    }
+    /** Evaluate and, if allowed, record the call against the bucket. */
+    hit(tool) {
+        return this.evaluate(tool, true);
+    }
+    evaluate(tool, record) {
+        if (!this.config.enabled) {
+            return { allowed: true, windowCount: 0, dailyCount: 0 };
+        }
+        const rule = this.ruleFor(tool);
+        const t = this.now();
+        const bucket = this.buckets.get(tool) ?? { hits: [] };
+        // Drop anything older than the longest horizon we care about.
+        const horizon = Math.max(rule.windowMs, rule.dailyQuota ? DAY_MS : 0);
+        bucket.hits = bucket.hits.filter((ts) => t - ts < horizon);
+        const windowStart = t - rule.windowMs;
+        const windowHits = bucket.hits.filter((ts) => ts >= windowStart);
+        const dayHits = rule.dailyQuota ? bucket.hits.filter((ts) => ts >= t - DAY_MS) : [];
+        const windowCount = windowHits.length;
+        const dailyCount = dayHits.length;
+        if (windowCount >= rule.maxCalls) {
+            const oldest = windowHits[0] ?? t;
+            const retryAfterMs = Math.max(0, oldest + rule.windowMs - t);
+            return {
+                allowed: false,
+                reason: `Rate limit: ${tool} allows ${rule.maxCalls} calls per ${rule.windowMs}ms.`,
+                retryAfterMs,
+                windowCount,
+                dailyCount,
+            };
+        }
+        if (rule.dailyQuota !== undefined && dailyCount >= rule.dailyQuota) {
+            const oldest = dayHits[0] ?? t;
+            const retryAfterMs = Math.max(0, oldest + DAY_MS - t);
+            return {
+                allowed: false,
+                reason: `Daily quota reached: ${tool} allows ${rule.dailyQuota} calls per 24h.`,
+                retryAfterMs,
+                windowCount,
+                dailyCount,
+            };
+        }
+        if (record) {
+            bucket.hits.push(t);
+            this.buckets.set(tool, bucket);
+            return { allowed: true, windowCount: windowCount + 1, dailyCount: dailyCount + 1 };
+        }
+        this.buckets.set(tool, bucket);
+        return { allowed: true, windowCount, dailyCount };
+    }
+    /** Snapshot of current usage per tool, for the dashboard and tooling. */
+    snapshot() {
+        const t = this.now();
+        const out = [];
+        for (const [tool, bucket] of this.buckets) {
+            const rule = this.ruleFor(tool);
+            const windowCount = bucket.hits.filter((ts) => ts >= t - rule.windowMs).length;
+            const dailyCount = bucket.hits.filter((ts) => ts >= t - DAY_MS).length;
+            out.push({ tool, windowCount, dailyCount, rule });
+        }
+        return out;
+    }
+    reset(tool) {
+        if (tool)
+            this.buckets.delete(tool);
+        else
+            this.buckets.clear();
+    }
+}