@sunshinelife83/hearth 1.0.0

package/dist/policy/env-allowlist.js

@@ -0,0 +1,96 @@
+import { logEvent } from "../logger.js";
+/**
+ * Environment filtering for model-invoked shell tools.
+ *
+ * Model-run commands must not inherit arbitrary user-environment variables:
+ * the environment commonly holds cloud/API credentials, and any command the
+ * model executes could read and exfiltrate them. Commands are instead given a
+ * conservative allowlist plus the Hearth workspace markers they legitimately
+ * need. Individual values can still be provided inline per command
+ * (`API_KEY=x cmd`) when the user chooses to.
+ */
+export const DEFAULT_ENV_ALLOWLIST = [
+    // Identity and basics
+    "PATH",
+    "HOME",
+    "SHELL",
+    "USER",
+    "LOGNAME",
+    "LANG",
+    "LC_ALL",
+    "LC_CTYPE",
+    "TZ",
+    "TMPDIR",
+    "TEMP",
+    "TMP",
+    // Terminal/display conventions (Hearth also sets some of these explicitly)
+    "TERM",
+    "COLORTERM",
+    // XDG conventions used by many CLIs for config/cache locations
+    "XDG_CONFIG_HOME",
+    "XDG_CACHE_HOME",
+    "XDG_DATA_HOME",
+    "XDG_STATE_HOME",
+    // Proxy settings: required for network operations behind proxies
+    "HTTP_PROXY",
+    "HTTPS_PROXY",
+    "NO_PROXY",
+    "http_proxy",
+    "https_proxy",
+    "no_proxy",
+    // Windows essentials
+    "SystemRoot",
+    "windir",
+    "COMSPEC",
+    "PATHEXT",
+    "APPDATA",
+    "LOCALAPPDATA",
+    "PROGRAMFILES",
+    "ProgramFiles",
+    "USERPROFILE",
+    "HOMEDRIVE",
+    "HOMEPATH",
+];
+export function filterChildEnvironment(parentEnv, filter, context) {
+    const source = Object.fromEntries(Object.entries(parentEnv).filter((entry) => entry[1] !== undefined));
+    if (filter.allowAll) {
+        logEvent(context?.logging ?? silentLogging(), "debug", "env_filter_bypassed", {
+            allowAll: true,
+            workspaceId: context?.workspaceId,
+        });
+        return source;
+    }
+    const allowlist = new Set([...DEFAULT_ENV_ALLOWLIST, ...(filter.extraAllowlist ?? [])]);
+    if (context?.workspaceId) {
+        // Hearth's own non-secret workspace markers are always passed so CLI
+        // helpers invoked from tool shells can scope themselves.
+        allowlist.add("HEARTH_WORKSPACE_ID");
+        allowlist.add("HEARTH_WORKSPACE_ROOT");
+    }
+    allowlist.add("HEARTH_ORIGIN");
+    const result = {};
+    for (const [key, value] of Object.entries(source)) {
+        if (allowlist.has(key))
+            result[key] = value;
+    }
+    if (context?.logging) {
+        const dropped = Object.keys(source).length - Object.keys(result).length;
+        logEvent(context.logging, "debug", "env_filter_applied", {
+            kept: Object.keys(result).length,
+            dropped,
+            workspaceId: context.workspaceId,
+        });
+    }
+    return result;
+}
+function silentLogging() {
+    return {
+        level: "silent",
+        format: "json",
+        requests: false,
+        assets: false,
+        toolCalls: false,
+        shellCommands: false,
+        trustProxy: false,
+    };
+}

package/dist/policy/sandbox.js

@@ -0,0 +1,68 @@
+import { execFileSync } from "node:child_process";
+let cachedAdapter;
+export function resetSandboxProbeCache() {
+    cachedAdapter = undefined;
+}
+/** Probe (once per process) which sandbox adapter is usable. */
+export function probeSandboxAdapter(platform = process.platform) {
+    if (cachedAdapter)
+        return cachedAdapter;
+    cachedAdapter = probe(platform);
+    return cachedAdapter;
+}
+function probe(platform) {
+    if (platform === "linux") {
+        return commandWorks("bwrap", ["--version"]) ? "bwrap" : "none";
+    }
+    if (platform === "darwin") {
+        return commandWorks("sandbox-exec", ["-h"]) ? "seatbelt" : "none";
+    }
+    return "none";
+}
+function commandWorks(command, args) {
+    try {
+        execFileSync(command, args, { stdio: "ignore", timeout: 5_000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Wrap a resolved shell command so it runs inside the sandbox. The original
+ * shell invocation becomes the sandboxed child verbatim.
+ */
+export function wrapCommandWithSandbox(shell, adapter, options) {
+    if (adapter === "none")
+        return shell;
+    if (adapter === "bwrap") {
+        const args = [
+            "--ro-bind", "/", "/",
+            "--dev-bind", "/dev", "/dev",
+            "--proc", "/proc",
+            "--bind", options.workspaceRoot, options.workspaceRoot,
+            "--tmpfs", "/tmp",
+            "--tmpfs", "/run",
+            "--die-with-parent",
+            "--new-session",
+            ...(options.allowNetwork ? [] : ["--unshare-net"]),
+            // "--" stops bwrap option parsing; without it a shell like
+            // `zsh -lc cmd` makes bwrap consume `-lc` as its own options.
+            "--",
+            shell.executable,
+            ...shell.args,
+        ];
+        return { executable: "bwrap", args };
+    }
+    // seatbelt: profile denies writes outside the workspace/temp, allows the rest.
+    const profile = [
+        "(version 1)",
+        "(allow default)",
+        "(deny file-write*)",
+        `(allow file-write* (subpath "${options.workspaceRoot}") (subpath "/private/tmp") (subpath "/tmp") (literal "/dev/null") (subpath "/dev/stdout") (subpath "/dev/stderr"))`,
+    ].join(" ");
+    return {
+        executable: "sandbox-exec",
+        args: ["-p", profile, shell.executable, ...shell.args],
+    };
+}

package/dist/policy/workspace-profiles.js

@@ -0,0 +1,47 @@
+import { isPathInsideRoot } from "../roots.js";
+export function resolveExecutionForWorkspace(config, workspaceRoot) {
+    let best;
+    for (const profile of config.workspaceProfiles) {
+        if (!isPathInsideRoot(workspaceRoot, profile.path))
+            continue;
+        if (!best || profile.path.length > best.path.length)
+            best = profile;
+    }
+    return {
+        mode: best?.mode ?? config.execution.mode,
+        sandbox: best?.sandbox,
+        sandboxNetwork: best?.sandboxNetwork,
+        requireSandboxForAutonomous: best?.requireSandboxForAutonomous ?? config.execution.requireSandboxForAutonomous,
+        commandAllow: best?.commandAllow ?? [],
+        commandDeny: best?.commandDeny ?? [],
+        agentsAllowed: best?.agentsAllowed ?? true,
+        ...(best ? { profilePath: best.path } : {}),
+    };
+}
+/** Regex allow/deny command lists from the matched profile. */
+export function commandListVerdict(resolved, command) {
+    for (const pattern of resolved.commandDeny) {
+        try {
+            if (new RegExp(pattern).test(command)) {
+                return { allowed: false, rule: `workspace commandDeny: /${pattern}/` };
+            }
+        }
+        catch {
+            // Invalid user regex: skip rather than fail open silently? Fail closed.
+            return { allowed: false, rule: `workspace commandDeny has invalid regex: /${pattern}/` };
+        }
+    }
+    if (resolved.commandAllow.length > 0) {
+        for (const pattern of resolved.commandAllow) {
+            try {
+                if (new RegExp(pattern).test(command))
+                    return { allowed: true };
+            }
+            catch {
+                return { allowed: false, rule: `workspace commandAllow has invalid regex: /${pattern}/` };
+            }
+        }
+        return { allowed: false, rule: "command not in workspace commandAllow list" };
+    }
+    return { allowed: true };
+}

package/dist/process-journal.js

@@ -0,0 +1,116 @@
+import { readdir, readFile, rm, writeFile, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+const entryFile = (dir, pid) => join(dir, `proc-${pid}.json`);
+export async function recordProcessJournal(dir, entry) {
+    await mkdir(dir, { recursive: true });
+    await writeFile(entryFile(dir, entry.pid), JSON.stringify(entry), { mode: 0o600 });
+}
+export async function removeProcessJournal(dir, pid) {
+    await rm(entryFile(dir, pid), { force: true });
+}
+export async function listProcessJournal(dir) {
+    let files;
+    try {
+        files = await readdir(dir);
+    }
+    catch {
+        return [];
+    }
+    const entries = [];
+    for (const file of files) {
+        if (!file.startsWith("proc-") || !file.endsWith(".json"))
+            continue;
+        try {
+            const raw = await readFile(join(dir, file), "utf8");
+            const parsed = JSON.parse(raw);
+            if (typeof parsed.pid === "number" && parsed.pid > 1)
+                entries.push(parsed);
+        }
+        catch {
+            // Corrupt entry: drop it on reap.
+            entries.push({ pid: -1, workspaceId: "", workspaceRoot: "", commandPreview: "", startedAt: "" });
+        }
+    }
+    return entries;
+}
+function procCmdline(pid) {
+    try {
+        if (process.platform === "linux" && existsSync(`/proc/${pid}/cmdline`)) {
+            const raw = execFileSync("cat", [`/proc/${pid}/cmdline`], { timeout: 3_000 });
+            return raw.toString("utf8").replaceAll("\0", " ");
+        }
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        const out = execFileSync("ps", ["-o", "command=", "-p", String(pid)], { timeout: 5_000 });
+        const text = out.toString("utf8").trim();
+        return text ? text : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function matchesEntry(cmdline, entry) {
+    if (entry.workspaceRoot && cmdline.includes(entry.workspaceRoot))
+        return true;
+    if (entry.commandPreview && entry.commandPreview.length >= 8 && cmdline.includes(entry.commandPreview.slice(0, 64))) {
+        return true;
+    }
+    return false;
+}
+/** Reap stale journal entries. Never throws; reports per-entry outcomes. */
+export async function reapProcessJournal(dir, audit = () => undefined) {
+    const report = { reaped: 0, skipped: 0, errors: [], details: [] };
+    const entries = await listProcessJournal(dir);
+    for (const entry of entries) {
+        if (entry.pid <= 1) {
+            report.skipped += 1;
+            report.details.push(`dropped corrupt journal entry`);
+            continue;
+        }
+        const cmdline = procCmdline(entry.pid);
+        if (cmdline === undefined) {
+            // No such process (or no way to confirm): drop the stale entry.
+            await removeProcessJournal(dir, entry.pid);
+            audit("orphan_reap_stale", { pid: entry.pid, workspaceId: entry.workspaceId });
+            report.skipped += 1;
+            report.details.push(`pid ${entry.pid}: not running, entry dropped`);
+            continue;
+        }
+        if (!matchesEntry(cmdline, entry)) {
+            // PID reused by an unrelated process: never kill, just drop.
+            await removeProcessJournal(dir, entry.pid);
+            audit("orphan_reap_pid_reused", { pid: entry.pid, workspaceId: entry.workspaceId });
+            report.skipped += 1;
+            report.details.push(`pid ${entry.pid}: cmdline no longer matches, left alone`);
+            continue;
+        }
+        try {
+            if (entry.pgid && entry.pgid > 1 && entry.pgid !== process.pid) {
+                try {
+                    process.kill(-entry.pgid, "SIGTERM");
+                }
+                catch {
+                    process.kill(entry.pid, "SIGTERM");
+                }
+            }
+            else {
+                process.kill(entry.pid, "SIGTERM");
+            }
+            await removeProcessJournal(dir, entry.pid);
+            audit("orphan_reaped", { pid: entry.pid, workspaceId: entry.workspaceId });
+            report.reaped += 1;
+            report.details.push(`pid ${entry.pid}: terminated`);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            report.errors.push(`pid ${entry.pid}: ${message}`);
+            report.details.push(`pid ${entry.pid}: kill failed (${message})`);
+        }
+    }
+    return report;
+}

package/dist/process-platform.js

@@ -0,0 +1,49 @@
+import { basename } from "node:path";
+import { spawnSync } from "node:child_process";
+const defaultProcessTreeRuntime = {
+    platform: process.platform,
+    killGroup: (pid, signal) => process.kill(-pid, signal),
+    killWindowsTree: (pid) => {
+        const result = spawnSync("taskkill.exe", ["/pid", String(pid), "/T", "/F"], {
+            stdio: "ignore",
+            windowsHide: true,
+        });
+        return !result.error && result.status === 0;
+    },
+};
+const LOGIN_SHELLS = new Set(["bash", "ksh", "zsh"]);
+const POSIX_SHELLS = new Set(["ash", "dash", "sh"]);
+export function resolveShellCommand(command, platform = process.platform, environment = process.env) {
+    if (platform === "win32") {
+        return {
+            executable: environment.ComSpec ?? environment.COMSPEC ?? "cmd.exe",
+            args: ["/d", "/s", "/c", command],
+        };
+    }
+    const configuredShell = environment.SHELL;
+    const shellName = configuredShell ? basename(configuredShell) : "";
+    if (configuredShell && LOGIN_SHELLS.has(shellName)) {
+        return { executable: configuredShell, args: ["-lc", command] };
+    }
+    if (configuredShell && POSIX_SHELLS.has(shellName)) {
+        return { executable: configuredShell, args: ["-c", command] };
+    }
+    return { executable: "/bin/sh", args: ["-c", command] };
+}
+export function terminateProcessTree(child, signal, detached, runtime = defaultProcessTreeRuntime) {
+    if (runtime.platform === "win32" && child.pid) {
+        if (runtime.killWindowsTree(child.pid))
+            return;
+    }
+    else if (detached && child.pid) {
+        try {
+            runtime.killGroup(child.pid, signal);
+            return;
+        }
+        catch (error) {
+            if (error.code === "ESRCH")
+                return;
+        }
+    }
+    child.kill(signal);
+}