@theowlops/boombot 0.0.0-stage → 1.1.0

package/dist/node_modules/@boombot/protocol/providers/types.js

@@ -0,0 +1,16 @@
+import { registeredProviderKinds } from './profiles/index.js';
+/**
+ * All known provider kinds, derived from the profile registry
+ * (`./profiles/`). The registry is the single source of truth; this list
+ * stays in sync automatically as providers are added.
+ */
+export const PROVIDER_KINDS = registeredProviderKinds();
+/** Error thrown by `ProviderService` for expected failure modes. */
+export class ProviderError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'ProviderError';
+        this.code = code;
+    }
+}

package/dist/node_modules/@boombot/sandbox/fs-path.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Resolves `target` relative to `root` and guarantees the result stays
+ * within `root`.
+ *
+ * Returns the symlink-resolved absolute path. Throws `Error` when:
+ * - `target` is empty or contains a NUL byte;
+ * - the path escapes the root, including via symlink or prefix trick
+ *   (`root-evil` does not count as inside `root`).
+ *
+ * `root` itself is considered valid (returned as-is), since `target: '.'` is
+ * a reasonable request — the caller decides whether to accept a directory.
+ */
+export declare function resolveWithin(root: string, target: string): Promise<string>;

package/dist/node_modules/@boombot/sandbox/fs-path.js

@@ -0,0 +1,79 @@
+/**
+ * Path confinement for direct file operations (not via subprocess).
+ *
+ * `confineCwd` (`./sandbox.ts`) only uses `path.resolve` — it matches the
+ * string prefix, so a symlink INSIDE the root that points OUTSIDE slips
+ * through. For a child process's cwd that is a narrow hole (the child is
+ * still env-scrubbed with shell-less argv). For files it is not:
+ * `root/link` → `/etc/passwd` is a direct read path, and `root/link` →
+ * `~/.ssh` is a direct write path. So the file tool does NOT use
+ * `confineCwd`; it uses `resolveWithin` below, which uses `realpath`.
+ *
+ * Boundary: only `node:fs/promises` + `node:path`, no `@boombot/*` imports.
+ */
+import { realpath } from 'node:fs/promises';
+import { dirname, resolve, sep } from 'node:path';
+/** `realpath` returning `null` instead of throwing when the path doesn't exist. */
+async function realpathOrNull(path) {
+    try {
+        return await realpath(path);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolves symlinks at the **deepest existing ancestor**, then re-attaches
+ * the non-existent tail.
+ *
+ * This is the crux: `file.write` must be able to write NEW files (not yet
+ * existing, so `realpath` on them would throw), but symlinks in every ancestor
+ * directory that DOES exist must still be resolved — otherwise
+ * `root/link-to-outside/new.txt` would be accepted because its string still
+ * lies within the root.
+ */
+async function realpathDeepest(path) {
+    const tail = [];
+    let current = path;
+    for (;;) {
+        const real = await realpathOrNull(current);
+        if (real !== null) {
+            return tail.length === 0 ? real : resolve(real, ...[...tail].reverse());
+        }
+        const parent = dirname(current);
+        // Hit the filesystem root with nothing existing yet: nothing left to resolve.
+        if (parent === current)
+            return path;
+        tail.push(current.slice(parent.length + 1));
+        current = parent;
+    }
+}
+/**
+ * Resolves `target` relative to `root` and guarantees the result stays
+ * within `root`.
+ *
+ * Returns the symlink-resolved absolute path. Throws `Error` when:
+ * - `target` is empty or contains a NUL byte;
+ * - the path escapes the root, including via symlink or prefix trick
+ *   (`root-evil` does not count as inside `root`).
+ *
+ * `root` itself is considered valid (returned as-is), since `target: '.'` is
+ * a reasonable request — the caller decides whether to accept a directory.
+ */
+export async function resolveWithin(root, target) {
+    if (typeof target !== 'string' || target.length === 0) {
+        throw new Error('resolveWithin: target path must be a non-empty string');
+    }
+    if (target.includes('\0')) {
+        throw new Error('resolveWithin: target path contains a NUL byte');
+    }
+    // realpath the root too: if the root itself sits behind a symlink (e.g.
+    // `/tmp` → `/private/tmp` on macOS), comparing against the UNRESOLVED root
+    // would wrongly reject every valid path.
+    const realRoot = await realpathDeepest(resolve(root));
+    const realCandidate = await realpathDeepest(resolve(realRoot, target));
+    if (realCandidate !== realRoot && !realCandidate.startsWith(realRoot + sep)) {
+        throw new Error(`resolveWithin: path escapes the workspace root (root=${realRoot}, target=${target})`);
+    }
+    return realCandidate;
+}

package/dist/node_modules/@boombot/sandbox/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @boombot/sandbox — injectable subprocess sandbox.
+ *
+ * Public surface:
+ * - `SandboxProvider` — swappable backend interface
+ * - `SubprocessSandbox` — spawn without shell, timeout kill
+ *   (SIGTERM → SIGKILL), cwd confinement, env allowlist, output caps
+ * - `confineCwd` — cwd confinement helper (also unit-tested directly)
+ * - `resolveWithin` — symlink-aware path confinement for direct fs access
+ */
+export { SubprocessSandbox, confineCwd, type SandboxProvider, type SandboxRunOptions, type SandboxResult, type SubprocessSandboxOptions, } from './sandbox.js';
+export { resolveWithin } from './fs-path.js';
+export { NativeSandbox, createSandboxProvider, findNativeHostBinary, type CreateSandboxOptions, type NativeSandboxOptions, type SandboxBackend, } from './native.js';

package/dist/node_modules/@boombot/sandbox/index.js

@@ -0,0 +1,13 @@
+/**
+ * @boombot/sandbox — injectable subprocess sandbox.
+ *
+ * Public surface:
+ * - `SandboxProvider` — swappable backend interface
+ * - `SubprocessSandbox` — spawn without shell, timeout kill
+ *   (SIGTERM → SIGKILL), cwd confinement, env allowlist, output caps
+ * - `confineCwd` — cwd confinement helper (also unit-tested directly)
+ * - `resolveWithin` — symlink-aware path confinement for direct fs access
+ */
+export { SubprocessSandbox, confineCwd, } from './sandbox.js';
+export { resolveWithin } from './fs-path.js';
+export { NativeSandbox, createSandboxProvider, findNativeHostBinary, } from './native.js';

package/dist/node_modules/@boombot/sandbox/native.d.ts

@@ -0,0 +1,39 @@
+import { type SandboxProvider, type SandboxResult, type SandboxRunOptions, type SubprocessSandboxOptions } from './sandbox.js';
+export type SandboxBackend = 'auto' | 'native' | 'subprocess';
+export interface NativeSandboxOptions extends SubprocessSandboxOptions {
+    /** Compiled `boombot-native-host` executable. */
+    binaryPath: string;
+}
+export interface CreateSandboxOptions extends SubprocessSandboxOptions {
+    /** `auto` uses Rust when built, otherwise preserves the Node rollback path. */
+    backend?: SandboxBackend;
+    nativeHostPath?: string;
+}
+/** Find an explicitly configured or repository-local release binary. */
+export declare function findNativeHostBinary(explicit?: string | undefined): string | undefined;
+/** Rust-backed subprocess runner using one restartable, line-framed host. */
+export declare class NativeSandbox implements SandboxProvider {
+    readonly name = "native";
+    private readonly binaryPath;
+    private readonly workspaceRoot;
+    private readonly defaultTimeoutMs;
+    private readonly maxOutputBytes;
+    private readonly killGraceMs;
+    private readonly minPath;
+    private child;
+    private stdoutBuffer;
+    private stderrBuffer;
+    private queue;
+    private pending;
+    private closed;
+    constructor(options: NativeSandboxOptions);
+    run(cmd: readonly string[], opts: SandboxRunOptions): Promise<SandboxResult>;
+    close(): Promise<void>;
+    private send;
+    private ensureHost;
+    private consume;
+    private failHost;
+    private rejectPending;
+}
+/** Compatibility-safe backend selection: Rust by default when present, Node as rollback. */
+export declare function createSandboxProvider(options: CreateSandboxOptions): SandboxProvider;

package/dist/node_modules/@boombot/sandbox/native.js

@@ -0,0 +1,224 @@
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { assertNoShellMetacharacters, buildSandboxEnv, confineCwd, defaultMinPath, SubprocessSandbox, } from './sandbox.js';
+const PROTOCOL_VERSION = 1;
+const HOST_STDERR_LIMIT = 64 * 1024;
+function executableName() {
+    return process.platform === 'win32' ? 'boombot-native-host.exe' : 'boombot-native-host';
+}
+function packagedBinaryPath(root) {
+    return resolve(root, 'native', `${process.platform}-${process.arch}`, executableName());
+}
+/** Find an explicitly configured or repository-local release binary. */
+export function findNativeHostBinary(explicit = process.env['BOOMBOT_NATIVE_HOST']) {
+    const moduleDir = dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        explicit,
+        resolve(process.cwd(), 'native', 'host', 'target', 'release', executableName()),
+        packagedBinaryPath(resolve(process.cwd(), 'apps', 'cli', 'dist')),
+        resolve(moduleDir, '..', '..', '..', 'native', 'host', 'target', 'release', executableName()),
+        resolve(moduleDir, '..', '..', '..', '..', 'native', 'host', 'target', 'release', executableName()),
+        packagedBinaryPath(resolve(moduleDir, '..', '..', '..')),
+    ];
+    return candidates.find((candidate) => typeof candidate === 'string' && candidate.length > 0 && existsSync(candidate));
+}
+function readNativeResult(value) {
+    if (value.version !== PROTOCOL_VERSION) {
+        throw new Error(`NativeSandbox: unsupported host protocol ${String(value.version)}`);
+    }
+    if (value.ok !== true) {
+        throw new Error(`NativeSandbox: ${typeof value.error === 'string' ? value.error : 'native host failed'}`);
+    }
+    if (typeof value.stdout !== 'string' ||
+        typeof value.stderr !== 'string' ||
+        (typeof value.exitCode !== 'number' && value.exitCode !== null) ||
+        typeof value.timedOut !== 'boolean' ||
+        typeof value.truncated !== 'boolean') {
+        throw new Error('NativeSandbox: malformed host response');
+    }
+    return {
+        stdout: value.stdout,
+        stderr: value.stderr,
+        exitCode: value.exitCode,
+        timedOut: value.timedOut,
+        truncated: value.truncated,
+    };
+}
+/** Rust-backed subprocess runner using one restartable, line-framed host. */
+export class NativeSandbox {
+    name = 'native';
+    binaryPath;
+    workspaceRoot;
+    defaultTimeoutMs;
+    maxOutputBytes;
+    killGraceMs;
+    minPath;
+    child;
+    stdoutBuffer = '';
+    stderrBuffer = '';
+    queue = Promise.resolve();
+    pending;
+    closed = false;
+    constructor(options) {
+        if (typeof options.workspaceRoot !== 'string' || options.workspaceRoot.length === 0) {
+            throw new Error('NativeSandbox: workspaceRoot is required');
+        }
+        if (!existsSync(options.binaryPath)) {
+            throw new Error(`NativeSandbox: binary not found at ${options.binaryPath}`);
+        }
+        this.binaryPath = resolve(options.binaryPath);
+        this.workspaceRoot = resolve(options.workspaceRoot);
+        this.defaultTimeoutMs = options.defaultTimeoutMs ?? 30_000;
+        this.maxOutputBytes = options.maxOutputBytes ?? 1_048_576;
+        this.killGraceMs = options.killGraceMs ?? 2_000;
+        this.minPath = options.minPath ?? defaultMinPath();
+    }
+    async run(cmd, opts) {
+        if (this.closed)
+            throw new Error('NativeSandbox: closed');
+        if (cmd.length === 0 || cmd[0] === undefined || cmd[0].length === 0) {
+            throw new Error('NativeSandbox: cmd must contain a non-empty executable');
+        }
+        assertNoShellMetacharacters(cmd);
+        const timeoutMs = opts.timeoutMs > 0 ? opts.timeoutMs : this.defaultTimeoutMs;
+        const cwd = confineCwd(this.workspaceRoot, opts.cwd);
+        const request = JSON.stringify({
+            version: PROTOCOL_VERSION,
+            command: cmd,
+            workspaceRoot: this.workspaceRoot,
+            cwd,
+            timeoutMs,
+            killGraceMs: this.killGraceMs,
+            maxOutputBytes: this.maxOutputBytes,
+            env: buildSandboxEnv(opts.envAllowlist ?? [], this.minPath),
+        });
+        const result = this.queue.then(() => this.send(request, timeoutMs));
+        this.queue = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        await this.queue;
+        const child = this.child;
+        this.child = undefined;
+        if (child === undefined || child.exitCode !== null || child.signalCode !== null)
+            return;
+        await new Promise((resolveClose) => {
+            const timer = setTimeout(() => child.kill('SIGKILL'), this.killGraceMs);
+            timer.unref?.();
+            child.once('close', () => {
+                clearTimeout(timer);
+                resolveClose();
+            });
+            child.stdin.end();
+        });
+    }
+    send(request, timeoutMs) {
+        const child = this.ensureHost();
+        this.stderrBuffer = '';
+        return new Promise((resolveResult, rejectResult) => {
+            const watchdog = setTimeout(() => {
+                this.failHost(new Error('NativeSandbox: native host watchdog expired'));
+            }, timeoutMs + this.killGraceMs + 5_000);
+            watchdog.unref?.();
+            this.pending = { resolve: resolveResult, reject: rejectResult, watchdog };
+            child.stdin.write(`${request}\n`, (error) => {
+                if (error !== null && error !== undefined) {
+                    this.failHost(new Error(`NativeSandbox: ${error.message}`));
+                }
+            });
+        });
+    }
+    ensureHost() {
+        if (this.child !== undefined)
+            return this.child;
+        const child = spawn(this.binaryPath, [], {
+            shell: false,
+            stdio: ['pipe', 'pipe', 'pipe'],
+            windowsHide: true,
+        });
+        this.child = child;
+        child.stdout.setEncoding('utf8');
+        child.stdout.on('data', (chunk) => this.consume(chunk));
+        child.stderr.setEncoding('utf8');
+        child.stderr.on('data', (chunk) => {
+            this.stderrBuffer = (this.stderrBuffer + chunk).slice(-HOST_STDERR_LIMIT);
+        });
+        child.on('error', (error) => {
+            if (this.child === child)
+                this.failHost(new Error(`NativeSandbox: ${error.message}`));
+        });
+        child.on('close', () => {
+            if (this.child !== child)
+                return;
+            this.child = undefined;
+            if (this.pending !== undefined) {
+                this.rejectPending(new Error(`NativeSandbox: host exited without a result${this.stderrBuffer === '' ? '' : `: ${this.stderrBuffer}`}`));
+            }
+            this.stdoutBuffer = '';
+        });
+        return child;
+    }
+    consume(chunk) {
+        this.stdoutBuffer += chunk;
+        const limit = this.maxOutputBytes * 8 + 65_536;
+        if (Buffer.byteLength(this.stdoutBuffer) > limit && !this.stdoutBuffer.includes('\n')) {
+            this.failHost(new Error('NativeSandbox: host response exceeded protocol limit'));
+            return;
+        }
+        const newline = this.stdoutBuffer.indexOf('\n');
+        if (newline < 0)
+            return;
+        const line = this.stdoutBuffer.slice(0, newline).trim();
+        this.stdoutBuffer = this.stdoutBuffer.slice(newline + 1);
+        if (Buffer.byteLength(line) > limit) {
+            this.failHost(new Error('NativeSandbox: host response exceeded protocol limit'));
+            return;
+        }
+        const pending = this.pending;
+        if (pending === undefined || line === '') {
+            this.failHost(new Error('NativeSandbox: unexpected host response'));
+            return;
+        }
+        this.pending = undefined;
+        clearTimeout(pending.watchdog);
+        try {
+            pending.resolve(readNativeResult(JSON.parse(line)));
+        }
+        catch (error) {
+            pending.reject(error instanceof Error ? error : new Error('NativeSandbox: invalid host response'));
+            this.child?.kill('SIGKILL');
+            this.child = undefined;
+        }
+    }
+    failHost(error) {
+        this.rejectPending(error);
+        this.child?.kill('SIGKILL');
+        this.child = undefined;
+        this.stdoutBuffer = '';
+    }
+    rejectPending(error) {
+        const pending = this.pending;
+        if (pending === undefined)
+            return;
+        this.pending = undefined;
+        clearTimeout(pending.watchdog);
+        pending.reject(error);
+    }
+}
+/** Compatibility-safe backend selection: Rust by default when present, Node as rollback. */
+export function createSandboxProvider(options) {
+    if (options.backend === 'subprocess')
+        return new SubprocessSandbox(options);
+    const binaryPath = findNativeHostBinary(options.nativeHostPath);
+    if (binaryPath !== undefined)
+        return new NativeSandbox({ ...options, binaryPath });
+    if (options.backend === 'native') {
+        throw new Error('NativeSandbox: native backend requested but binary is missing; run `pnpm native:build` or set BOOMBOT_NATIVE_HOST');
+    }
+    return new SubprocessSandbox(options);
+}

package/dist/node_modules/@boombot/sandbox/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@boombot/sandbox",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "./index.js",
+  "exports": {
+    ".": "./index.js"
+  }
+}

package/dist/node_modules/@boombot/sandbox/sandbox.d.ts

@@ -0,0 +1,92 @@
+/** Options for a single sandboxed run. */
+export interface SandboxRunOptions {
+    /** Working directory. Must resolve inside the sandbox's workspaceRoot. */
+    cwd: string;
+    /** Kill the process if it runs longer than this (ms). */
+    timeoutMs: number;
+    /** Env var names to pass through. Everything else is scrubbed. */
+    envAllowlist?: readonly string[];
+}
+/** Result of a sandboxed run. */
+export interface SandboxResult {
+    stdout: string;
+    stderr: string;
+    /** Process exit code, or null when killed by a signal. */
+    exitCode: number | null;
+    /** True when the run was killed because it exceeded timeoutMs. */
+    timedOut: boolean;
+    /** True when stdout/stderr exceeded maxOutputBytes and was cut. */
+    truncated: boolean;
+}
+/**
+ * Swappable sandbox backend. Hosts select the backend via config;
+ * callers only depend on this interface.
+ */
+export interface SandboxProvider {
+    readonly name: string;
+    run(cmd: readonly string[], opts: SandboxRunOptions): Promise<SandboxResult>;
+    close?(): Promise<void>;
+}
+export interface SubprocessSandboxOptions {
+    /** Root the child cwd may never escape. */
+    workspaceRoot: string;
+    /** Default timeout when the call omits timeoutMs. Default 30_000. */
+    defaultTimeoutMs?: number;
+    /** Max bytes kept per stream (stdout/stderr). Default 1 MiB. */
+    maxOutputBytes?: number;
+    /**
+     * Delay between SIGTERM and SIGKILL. Default 2000.
+     * Windows note: Node maps both signals to TerminateProcess, so there is
+     * no graceful phase on win32 — the first kill already terminates.
+     */
+    killGraceMs?: number;
+    /**
+     * Minimal PATH given to the child. Default '/usr/bin:/bin'.
+     * The default is POSIX-only: on Windows pass an explicit Windows-style
+     * PATH (e.g. `C:\Windows\System32`) or the child will not resolve
+     * executables by name.
+     */
+    minPath?: string;
+}
+export declare function assertNoShellMetacharacters(cmd: readonly string[]): void;
+/** Resolve `cwd` and prove it stays inside `root`. Throws on escape. */
+export declare function confineCwd(root: string, cwd: string): string;
+export declare function buildSandboxEnv(allowlist: readonly string[], minPath: string): Record<string, string>;
+/**
+ * Platform-aware default for `minPath`. The POSIX value cannot work on
+ * Windows: `spawn` resolves bare executables via PATH, and without
+ * System32 even `where`/built-ins fail. The running Node's own directory
+ * is appended so `node` itself is spawnable by name (the gateway's own
+ * runtime — scripts the agent runs usually want it).
+ */
+export declare function defaultMinPath(): string;
+/**
+ * Subprocess sandbox: `spawn` WITHOUT a shell, timeout kill
+ * (SIGTERM → SIGKILL after grace, delivered to the whole process group on
+ * POSIX), cwd confinement, env allowlist-only, and per-stream output caps.
+ *
+ * Known limitations: on POSIX the child is spawned detached as a process
+ * group leader, so the timeout kill reaches grandchildren — unless a
+ * grandchild calls setsid() to escape into its own group. On Windows Node
+ * cannot signal a process group, so the kill stays single-process and
+ * grandchildren may survive. Neither is a container/VM boundary: use a
+ * container backend when that matters.
+ *
+ * Windows behavior: Node maps both SIGTERM and SIGKILL to TerminateProcess,
+ * so the two-phase kill has no graceful phase on win32 — the process dies on
+ * the first kill and the grace timer is cleared by `close`. `kill()` on an
+ * already-exited process is a safe no-op (returns false, never throws), and
+ * a group kill whose members are all gone throws ESRCH which is swallowed,
+ * so a grace timer racing the process's natural exit cannot throw or hang
+ * the promise: `finish()` is idempotent and `close` always clears the timer.
+ */
+export declare class SubprocessSandbox implements SandboxProvider {
+    readonly name = "subprocess";
+    private readonly workspaceRoot;
+    private readonly defaultTimeoutMs;
+    private readonly maxOutputBytes;
+    private readonly killGraceMs;
+    private readonly minPath;
+    constructor(options: SubprocessSandboxOptions);
+    run(cmd: readonly string[], opts: SandboxRunOptions): Promise<SandboxResult>;
+}