@vinhnt-sdk/sandbox 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nguyen Thanh Vinh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,36 @@
+# @vinhnt-sdk/sandbox
+
+Sandbox primitives + fail-closed factory for isolated tool/command execution.
+
+```typescript
+import { createSandbox, SandboxUnavailableError } from "@vinhnt-sdk/sandbox";
+import { createHostSandbox } from "@vinhnt-sdk/sandbox-host";
+import { createProcessSandbox } from "@vinhnt-sdk/sandbox-process";
+
+const sandbox = createSandbox({ defaultTimeoutMs: 30_000, scope: "process" }, {
+  host: createHostSandbox,
+  process: createProcessSandbox,
+});
+
+const result = await sandbox.execute({
+  command: "node ./script.js",
+  cwd: "/workspace",
+  timeoutMs: 30_000,
+});
+```
+
+## Fail-closed by default
+
+Requesting a sandbox scope that has no registered backend throws
+`SandboxUnavailableError` — it never silently downgrades to a weaker sandbox.
+Wire only the backends your application actually supports.
+
+## Contents
+
+- `ProcessSandbox` interface — `execute()` / `destroy()` contract.
+- `SandboxConfig`, `SandboxResult`, `SandboxScope`, `KNOWN_SANDBOX_SCOPES`.
+- `SandboxUnavailableError` — fail-closed error carrying the missing scope.
+- `createSandbox(config, backends)` — fail-closed factory.
+- `parseCommand` — shell command tokenizer.
+- `killProcessTree` / `isPidAlive` / `treeKillSpawnOptions` — tree-scoped termination.
+- Backend packages: `@vinhnt-sdk/sandbox-host`, `@vinhnt-sdk/sandbox-process`, `@vinhnt-sdk/sandbox-container`.

package/dist/backends/host.d.ts

@@ -0,0 +1,4 @@
+import type { SandboxConfig, ProcessSandbox } from "../types.js";
+/** Create a host (no-isolation) sandbox backend. */
+export declare function createHostSandbox(_config?: SandboxConfig): ProcessSandbox;
+//# sourceMappingURL=host.d.ts.map

package/dist/backends/host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../../src/backends/host.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAiB,cAAc,EAAgC,MAAM,aAAa,CAAC;AA8D9G,oDAAoD;AACpD,wBAAgB,iBAAiB,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,cAAc,CAEzE"}

package/dist/backends/host.js

@@ -0,0 +1,57 @@
+import { execFile } from "node:child_process";
+import { parseCommand } from "../shell-parser.js";
+import { treeKillSpawnOptions } from "../kill-tree.js";
+import { withTimeoutAndAbort } from "../timeout.js";
+import { sanitizeEnv } from "@vinhnt-sdk/security";
+class HostSandbox {
+    scope = "host";
+    async execute(options) {
+        const start = Date.now();
+        return new Promise((resolve) => {
+            const parsed = parseCommand(options.command);
+            const child = execFile(parsed.file, parsed.args, {
+                cwd: options.cwd,
+                maxBuffer: 10 * 1024 * 1024,
+                encoding: "utf-8",
+                windowsHide: true,
+                ...treeKillSpawnOptions(),
+                env: options.env && Object.keys(options.env).length > 0
+                    ? { ...sanitizeEnv(), ...options.env }
+                    : sanitizeEnv(),
+            }, (err, stdout, stderr) => {
+                const durationMs = Date.now() - start;
+                if (err) {
+                    const exitCode = typeof err.code === "number" ? err.code : 1;
+                    resolve({
+                        result: { stdout: String(stdout ?? ""), stderr: String(stderr ?? ""), exitCode },
+                        exitCode,
+                        durationMs,
+                        timedOut: handle.timedOut,
+                    });
+                }
+                else {
+                    resolve({
+                        result: { stdout: String(stdout ?? ""), stderr: String(stderr ?? ""), exitCode: 0 },
+                        exitCode: 0,
+                        durationMs,
+                        timedOut: false,
+                    });
+                }
+            });
+            const handle = withTimeoutAndAbort(child, options.timeoutMs, options.signal, (reason) => {
+                resolve({
+                    result: { stdout: "", stderr: reason, exitCode: 1 },
+                    exitCode: 1,
+                    durationMs: Date.now() - start,
+                    timedOut: handle.timedOut,
+                });
+            });
+        });
+    }
+    async destroy() { }
+}
+/** Create a host (no-isolation) sandbox backend. */
+export function createHostSandbox(_config) {
+    return new HostSandbox();
+}
+//# sourceMappingURL=host.js.map

package/dist/backends/host.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.js","sourceRoot":"","sources":["../../src/backends/host.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAE9C,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAEnD,MAAM,WAAW;IACN,KAAK,GAAG,MAAe,CAAC;IAEjC,KAAK,CAAC,OAAO,CAAC,OAAqC;QACjD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAEzB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;YAC7B,MAAM,MAAM,GAAG,YAAY,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;YAC7C,MAAM,KAAK,GAAG,QAAQ,CACpB,MAAM,CAAC,IAAI,EACX,MAAM,CAAC,IAAI,EACX;gBACE,GAAG,EAAE,OAAO,CAAC,GAAG;gBAChB,SAAS,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI;gBAC3B,QAAQ,EAAE,OAAgB;gBAC1B,WAAW,EAAE,IAAI;gBACjB,GAAG,oBAAoB,EAAE;gBACzB,GAAG,EAAE,OAAO,CAAC,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,GAAG,CAAC;oBACrD,CAAC,CAAC,EAAE,GAAG,WAAW,EAAE,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE;oBACtC,CAAC,CAAC,WAAW,EAAE;aAClB,EACD,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE;gBACtB,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC;gBACtC,IAAI,GAAG,EAAE,CAAC;oBACR,MAAM,QAAQ,GAAG,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;oBAC7D,OAAO,CAAC;wBACN,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE;wBAChF,QAAQ;wBACR,UAAU;wBACV,QAAQ,EAAE,MAAM,CAAC,QAAQ;qBAC1B,CAAC,CAAC;gBACL,CAAC;qBAAM,CAAC;oBACN,OAAO,CAAC;wBACN,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE;wBACnF,QAAQ,EAAE,CAAC;wBACX,UAAU;wBACV,QAAQ,EAAE,KAAK;qBAChB,CAAC,CAAC;gBACL,CAAC;YACH,CAAC,CACF,CAAC;YAEF,MAAM,MAAM,GAAG,mBAAmB,CAAC,KAAK,EAAE,OAAO,CAAC,SAAS,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,EAAE;gBACtF,OAAO,CAAC;oBACN,MAAM,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,EAAE;oBACnD,QAAQ,EAAE,CAAC;oBACX,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK;oBAC9B,QAAQ,EAAE,MAAM,CAAC,QAAQ;iBAC1B,CAAC,CAAC;YACL,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,OAAO,KAAmB,CAAC;CAClC;AAED,oDAAoD;AACpD,MAAM,UAAU,iBAAiB,CAAC,OAAuB;IACvD,OAAO,IAAI,WAAW,EAAE,CAAC;AAC3B,CAAC"}

package/dist/backends/process.d.ts

@@ -0,0 +1,4 @@
+import type { SandboxConfig, ProcessSandbox } from "../types.js";
+/** Create a process-isolation sandbox backend. */
+export declare function createProcessSandbox(config: SandboxConfig): ProcessSandbox;
+//# sourceMappingURL=process.d.ts.map

package/dist/backends/process.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process.d.ts","sourceRoot":"","sources":["../../src/backends/process.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAiB,cAAc,EAAgC,MAAM,aAAa,CAAC;AAyJ9G,kDAAkD;AAClD,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,aAAa,GAAG,cAAc,CAE1E"}

package/dist/backends/process.js

@@ -0,0 +1,150 @@
+import { execFile } from "node:child_process";
+import { realpath } from "node:fs/promises";
+import { relative, isAbsolute } from "node:path";
+import { parseCommand } from "../shell-parser.js";
+import { treeKillSpawnOptions } from "../kill-tree.js";
+import { withTimeoutAndAbort } from "../timeout.js";
+const DEFAULT_ALLOWED_COMMANDS = new Set([
+    "node", "npm", "npx", "pnpm", "git",
+    "ls", "cat", "grep", "find", "head", "tail", "wc", "sort", "uniq", "diff",
+    "echo", "pwd", "whoami", "date",
+]);
+const BLOCKED_COMMAND_PATTERNS = [
+    /\brm\s+-rf\s+\/(?:[^a-z]|$)/i,
+    /\bmkfs\b/i,
+    /\bdd\b.*of=\/dev/i,
+    /\bformat\b/i,
+    /\bshutdown\b/i,
+    /\breboot\b/i,
+    /\bkill\s+-9\s+1\b/i,
+    /\bcurl\b.*\|\s*sh/i,
+    /\bwget\b.*\|\s*sh/i,
+];
+function extractBaseName(file) {
+    const name = file.split("/").pop()?.split("\\").pop() ?? file;
+    return process.platform === "win32" ? name.toLowerCase().replace(/\.exe$/, "") : name;
+}
+function isCommandAllowed(command, allowedCommands) {
+    const parsed = parseCommand(command);
+    const baseCommand = extractBaseName(parsed.file);
+    for (const pattern of BLOCKED_COMMAND_PATTERNS) {
+        if (pattern.test(command))
+            return false;
+    }
+    const allowlist = allowedCommands ?? DEFAULT_ALLOWED_COMMANDS;
+    return allowlist.has(baseCommand);
+}
+function isPathWithin(target, roots) {
+    for (const root of roots) {
+        const rel = relative(root, target);
+        if (rel === "")
+            return true;
+        if (rel.startsWith(".."))
+            continue;
+        if (isAbsolute(rel))
+            continue;
+        return true;
+    }
+    return false;
+}
+function createEmptyEnv(allowedVars) {
+    const env = {};
+    if (allowedVars) {
+        for (const key of allowedVars) {
+            const value = process.env[key];
+            if (value !== undefined)
+                env[key] = value;
+        }
+    }
+    return env;
+}
+class ProcessSandboxImpl {
+    scope = "process";
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async execute(options) {
+        const start = Date.now();
+        if (!isCommandAllowed(options.command, this.config.allowedCommands)) {
+            return {
+                result: { stdout: "", stderr: `Command not allowed: ${options.command.split(" ")[0]}`, exitCode: 126 },
+                exitCode: 126, durationMs: Date.now() - start, timedOut: false,
+            };
+        }
+        if (this.config.allowedPaths && this.config.allowedPaths.length > 0) {
+            let cwdReal;
+            const allowedReal = [];
+            try {
+                cwdReal = await realpath(options.cwd);
+            }
+            catch {
+                cwdReal = options.cwd;
+            }
+            for (const p of this.config.allowedPaths) {
+                let rootReal = p;
+                try {
+                    rootReal = await realpath(p);
+                }
+                catch { /* fall back to lexical path */ }
+                allowedReal.push(rootReal);
+            }
+            if (!isPathWithin(cwdReal, allowedReal)) {
+                return {
+                    result: { stdout: "", stderr: `Working directory outside allowed paths: ${options.cwd}`, exitCode: 126 },
+                    exitCode: 126, durationMs: Date.now() - start, timedOut: false,
+                };
+            }
+        }
+        const secureEnv = this.config.allowedEnvVars
+            ? createEmptyEnv(this.config.allowedEnvVars)
+            : createEmptyEnv();
+        const parsed = parseCommand(options.command);
+        const execArgs = [];
+        if (this.config.enablePermissionModel && extractBaseName(parsed.file) === "node") {
+            execArgs.push("--permission");
+            execArgs.push(`--allow-fs-read=${options.cwd}`);
+            execArgs.push("--allow-fs-read=/tmp");
+            execArgs.push("--allow-fs-write=/tmp");
+        }
+        const maxBuffer = 10 * 1024 * 1024;
+        return new Promise((resolve) => {
+            const child = execFile(parsed.file, [...execArgs, ...parsed.args], {
+                cwd: options.cwd,
+                maxBuffer,
+                encoding: "utf-8",
+                windowsHide: true,
+                ...treeKillSpawnOptions(),
+                env: secureEnv,
+                ...(process.platform !== "win32" ? { uid: process.getuid?.(), gid: process.getgid?.() } : {}),
+            }, (err, stdout, stderr) => {
+                const durationMs = Date.now() - start;
+                if (err) {
+                    const exitCode = typeof err.code === "number" ? err.code : 1;
+                    resolve({
+                        result: { stdout: String(stdout ?? ""), stderr: String(stderr ?? ""), exitCode },
+                        exitCode, durationMs, timedOut: handle.timedOut,
+                    });
+                }
+                else {
+                    resolve({
+                        result: { stdout: String(stdout ?? ""), stderr: String(stderr ?? ""), exitCode: 0 },
+                        exitCode: 0, durationMs, timedOut: false,
+                    });
+                }
+            });
+            const handle = withTimeoutAndAbort(child, options.timeoutMs, options.signal, (reason) => {
+                resolve({
+                    result: { stdout: "", stderr: reason, exitCode: 1 },
+                    exitCode: 1, durationMs: Date.now() - start, timedOut: handle.timedOut,
+                });
+            });
+        });
+    }
+    async destroy() { }
+}
+/** Create a process-isolation sandbox backend. */
+export function createProcessSandbox(config) {
+    return new ProcessSandboxImpl(config);
+}
+//# sourceMappingURL=process.js.map

package/dist/backends/process.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"process.js","sourceRoot":"","sources":["../../src/backends/process.ts"],"names":[],"mappings":"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"}

package/dist/error.d.ts

@@ -0,0 +1,16 @@
+import { VntError } from "@vinhnt-sdk/schema";
+/**
+ * Thrown when a sandbox scope is requested but no backend is available for it.
+ *
+ * Sandboxes are **fail-closed**: requesting an unsupported/unavailable scope
+ * never silently downgrades to a weaker sandbox. Instead this error makes the
+ * gap explicit, listing the scopes that ARE wired.
+ */
+export declare class SandboxUnavailableError extends VntError {
+    readonly scope: string;
+    readonly availableScopes: readonly string[];
+    readonly code: "ERR_SANDBOX_UNAVAILABLE";
+    readonly retryable = false;
+    constructor(scope: string, availableScopes?: readonly string[]);
+}
+//# sourceMappingURL=error.d.ts.map

package/dist/error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAE9C;;;;;;GAMG;AACH,qBAAa,uBAAwB,SAAQ,QAAQ;aAKjC,KAAK,EAAE,MAAM;aACb,eAAe,EAAE,SAAS,MAAM,EAAE;IALpD,SAAyB,IAAI,EAAG,yBAAyB,CAAU;IACnE,SAAyB,SAAS,SAAS;gBAGzB,KAAK,EAAE,MAAM,EACb,eAAe,GAAE,SAAS,MAAM,EAAO;CAU1D"}

package/dist/error.js

@@ -0,0 +1,24 @@
+import { VntError } from "@vinhnt-sdk/schema";
+/**
+ * Thrown when a sandbox scope is requested but no backend is available for it.
+ *
+ * Sandboxes are **fail-closed**: requesting an unsupported/unavailable scope
+ * never silently downgrades to a weaker sandbox. Instead this error makes the
+ * gap explicit, listing the scopes that ARE wired.
+ */
+export class SandboxUnavailableError extends VntError {
+    scope;
+    availableScopes;
+    code = "ERR_SANDBOX_UNAVAILABLE";
+    retryable = false;
+    constructor(scope, availableScopes = []) {
+        super(`Sandbox scope "${scope}" is not available` +
+            (availableScopes.length > 0
+                ? ` (available: ${availableScopes.join(", ")})`
+                : " — no sandbox backends registered; wire a backend package like @vinhnt-sdk/sandbox-host or @vinhnt-sdk/sandbox-process"));
+        this.scope = scope;
+        this.availableScopes = availableScopes;
+        this.name = "SandboxUnavailableError";
+    }
+}
+//# sourceMappingURL=error.js.map

package/dist/error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.js","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAE9C;;;;;;GAMG;AACH,MAAM,OAAO,uBAAwB,SAAQ,QAAQ;IAKjC;IACA;IALO,IAAI,GAAG,yBAAkC,CAAC;IAC1C,SAAS,GAAG,KAAK,CAAC;IAE3C,YACkB,KAAa,EACb,kBAAqC,EAAE;QAEvD,KAAK,CACH,kBAAkB,KAAK,oBAAoB;YAC3C,CAAC,eAAe,CAAC,MAAM,GAAG,CAAC;gBACzB,CAAC,CAAC,gBAAgB,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;gBAC/C,CAAC,CAAC,wHAAwH,CAAC,CAC9H,CAAC;QARc,UAAK,GAAL,KAAK,CAAQ;QACb,oBAAe,GAAf,eAAe,CAAwB;QAQvD,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACxC,CAAC;CACF"}

package/dist/factory.d.ts

@@ -0,0 +1,20 @@
+import type { SandboxConfig, ProcessSandbox, SandboxScope } from "./types.js";
+/** Factory that builds a `ProcessSandbox` for a scope from a config. */
+export type SandboxBackendFactory = (config: SandboxConfig) => ProcessSandbox;
+/**
+ * Backend registry passed to `createSandbox`. Keys are sandbox scopes; values
+ * are factories (or undefined if the scope is not wired).
+ */
+export type SandboxBackends = Record<SandboxScope, SandboxBackendFactory | undefined>;
+/**
+ * Build a sandbox for the configured scope.
+ *
+ * **Fail-closed**: if the requested scope has no registered backend this throws
+ * `SandboxUnavailableError` — it never silently downgrades to a weaker sandbox.
+ *
+ * @param config - Sandbox configuration.
+ * @param backends - Map of scope → backend factory. Wire only what you support.
+ * @returns ProcessSandbox instance for the requested scope.
+ */
+export declare function createSandbox(config: SandboxConfig, backends?: SandboxBackends): ProcessSandbox;
+//# sourceMappingURL=factory.d.ts.map

package/dist/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../src/factory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAG9E,wEAAwE;AACxE,MAAM,MAAM,qBAAqB,GAAG,CAAC,MAAM,EAAE,aAAa,KAAK,cAAc,CAAC;AAE9E;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,YAAY,EAAE,qBAAqB,GAAG,SAAS,CAAC,CAAC;AAEtF;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,EAAE,QAAQ,GAAE,eAAoB,GAAG,cAAc,CAQnG"}

package/dist/factory.js

@@ -0,0 +1,21 @@
+import { SandboxUnavailableError } from "./error.js";
+/**
+ * Build a sandbox for the configured scope.
+ *
+ * **Fail-closed**: if the requested scope has no registered backend this throws
+ * `SandboxUnavailableError` — it never silently downgrades to a weaker sandbox.
+ *
+ * @param config - Sandbox configuration.
+ * @param backends - Map of scope → backend factory. Wire only what you support.
+ * @returns ProcessSandbox instance for the requested scope.
+ */
+export function createSandbox(config, backends = {}) {
+    const scope = config.scope ?? "host";
+    const factory = backends[scope];
+    if (!factory) {
+        const availableScopes = Object.keys(backends).filter((s) => backends[s] !== undefined);
+        throw new SandboxUnavailableError(scope, availableScopes);
+    }
+    return factory(config);
+}
+//# sourceMappingURL=factory.js.map

package/dist/factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.js","sourceRoot":"","sources":["../src/factory.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAWrD;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAAC,MAAqB,EAAE,WAA4B,EAAE;IACjF,MAAM,KAAK,GAAiB,MAAM,CAAC,KAAK,IAAI,MAAM,CAAC;IACnD,MAAM,OAAO,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAChC,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,eAAe,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC;QACvF,MAAM,IAAI,uBAAuB,CAAC,KAAK,EAAE,eAAe,CAAC,CAAC;IAC5D,CAAC;IACD,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC;AACzB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export type { SandboxScope, SandboxConfig, SandboxResult, ProcessSandbox, ProcessSandboxExecuteOptions } from "./types.js";
+export { KNOWN_SANDBOX_SCOPES } from "./types.js";
+export { SandboxUnavailableError } from "./error.js";
+export { createSandbox } from "./factory.js";
+export type { SandboxBackendFactory, SandboxBackends } from "./factory.js";
+export { parseCommand } from "./shell-parser.js";
+export { killProcessTree, killProcessTreeAndWait, killTreeTrackedPids, isPidAlive, pruneKillTreeState, resetKillTreeState, treeKillSpawnOptions } from "./kill-tree.js";
+export { withTimeoutAndAbort } from "./timeout.js";
+export { createHostSandbox } from "./backends/host.js";
+export { createProcessSandbox } from "./backends/process.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,cAAc,EAAE,4BAA4B,EAAE,MAAM,YAAY,CAAC;AAC3H,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,YAAY,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC3E,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,UAAU,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AACxK,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAInD,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/index.js

@@ -0,0 +1,11 @@
+export { KNOWN_SANDBOX_SCOPES } from "./types.js";
+export { SandboxUnavailableError } from "./error.js";
+export { createSandbox } from "./factory.js";
+export { parseCommand } from "./shell-parser.js";
+export { killProcessTree, killProcessTreeAndWait, killTreeTrackedPids, isPidAlive, pruneKillTreeState, resetKillTreeState, treeKillSpawnOptions } from "./kill-tree.js";
+export { withTimeoutAndAbort } from "./timeout.js";
+// Re-export backend factories for backward compatibility
+// These were previously in separate packages (sandbox-host, sandbox-process)
+export { createHostSandbox } from "./backends/host.js";
+export { createProcessSandbox } from "./backends/process.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,UAAU,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AACxK,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAEnD,yDAAyD;AACzD,6EAA6E;AAC7E,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/kill-tree.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Tree-scoped process termination.
+ *
+ * `child.kill()` only terminates the direct child; grandchild processes keep
+ * running (orphaned). This module kills the whole process tree:
+ * - POSIX: child is spawned `detached` (own process group) → `kill(-pid)`
+ * - Windows: `taskkill /pid <pid> /T /F`
+ *
+ * Termination is idempotent: repeated kills for the same pid are no-ops while
+ * the kill is still in-flight. The registry is pruned once the tracked process
+ * exits (or its TTL elapses) so an OS pid reuse is not silently swallowed.
+ *
+ * @module sandbox/kill-tree
+ * @packageDocumentation
+ */
+import { type ChildProcess } from "node:child_process";
+/** Clear the idempotency registry (used by tests). */
+export declare function resetKillTreeState(): void;
+/**
+ * Pids currently tracked as "kill already issued".
+ *
+ * Exposed for observability/tests so a caller can confirm that a terminated
+ * pid is no longer held (i.e. it is safe to kill again after reuse).
+ */
+export declare function killTreeTrackedPids(): number[];
+/**
+ * Prune the idempotency registry: drop pids whose process has exited or whose
+ * kill is older than the TTL. Without pruning the registry grows forever and a
+ * reused pid is treated as "already killed" — a silent no-op (RV-11).
+ *
+ * @param now - Clock value to compare the TTL against (injectable for tests).
+ */
+export declare function pruneKillTreeState(now?: number): void;
+/** True when the process (or its process group) is still alive. */
+export declare function isPidAlive(pid: number): boolean;
+/**
+ * Kill a child process and its whole subtree. Idempotent per pid while the
+ * kill is in-flight (the registry is pruned once the process exits).
+ *
+ * @param child - The spawned child process.
+ * @param signal - POSIX signal for the direct kill (default "SIGTERM").
+ *   Windows always uses `taskkill /T /F`.
+ * @returns `true` when the kill was issued (or already issued), `false` when
+ *   there is no pid yet (child not spawned).
+ */
+export declare function killProcessTree(child: ChildProcess, signal?: NodeJS.Signals): boolean;
+/**
+ * Kill a child process and its whole subtree, then await its exit.
+ *
+ * This is the awaited form of {@link killProcessTree} (RV-11): on Windows the
+ * `taskkill /T` spawn is no longer fire-and-forget — the returned promise
+ * resolves only after the child has actually exited, or the given timeout
+ * elapses.
+ *
+ * @param child - The spawned child process.
+ * @param signal - POSIX signal for the direct kill (default "SIGTERM").
+ * @param timeoutMs - How long to wait for the child to exit (default 5000).
+ * @returns `true` when the kill was issued (or already issued), `false` when
+ *   there is no pid yet (child not spawned).
+ */
+export declare function killProcessTreeAndWait(child: ChildProcess, signal?: NodeJS.Signals, timeoutMs?: number): Promise<boolean>;
+/**
+ * Cross-platform spawn option that makes `killProcessTree` reach the whole
+ * tree. On Windows no extra flag is needed (taskkill walks the tree).
+ */
+export declare function treeKillSpawnOptions(): {
+    detached: boolean;
+};
+//# sourceMappingURL=kill-tree.d.ts.map

package/dist/kill-tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kill-tree.d.ts","sourceRoot":"","sources":["../src/kill-tree.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAS,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAK9D,sDAAsD;AACtD,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,EAAE,CAE9C;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,GAAE,MAAmB,GAAG,IAAI,CAMjE;AAED,mEAAmE;AACnE,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAQ/C;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,YAAY,EAAE,MAAM,GAAE,MAAM,CAAC,OAAmB,GAAG,OAAO,CA8BhG;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,YAAY,EACnB,MAAM,GAAE,MAAM,CAAC,OAAmB,EAClC,SAAS,SAAQ,GAChB,OAAO,CAAC,OAAO,CAAC,CAclB;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI;IAAE,QAAQ,EAAE,OAAO,CAAA;CAAE,CAE5D"}

package/dist/kill-tree.js

@@ -0,0 +1,138 @@
+/**
+ * Tree-scoped process termination.
+ *
+ * `child.kill()` only terminates the direct child; grandchild processes keep
+ * running (orphaned). This module kills the whole process tree:
+ * - POSIX: child is spawned `detached` (own process group) → `kill(-pid)`
+ * - Windows: `taskkill /pid <pid> /T /F`
+ *
+ * Termination is idempotent: repeated kills for the same pid are no-ops while
+ * the kill is still in-flight. The registry is pruned once the tracked process
+ * exits (or its TTL elapses) so an OS pid reuse is not silently swallowed.
+ *
+ * @module sandbox/kill-tree
+ * @packageDocumentation
+ */
+import { spawn } from "node:child_process";
+const terminatedPids = new Map();
+const KILL_TTL_MS = 30_000;
+/** Clear the idempotency registry (used by tests). */
+export function resetKillTreeState() {
+    terminatedPids.clear();
+}
+/**
+ * Pids currently tracked as "kill already issued".
+ *
+ * Exposed for observability/tests so a caller can confirm that a terminated
+ * pid is no longer held (i.e. it is safe to kill again after reuse).
+ */
+export function killTreeTrackedPids() {
+    return [...terminatedPids.keys()];
+}
+/**
+ * Prune the idempotency registry: drop pids whose process has exited or whose
+ * kill is older than the TTL. Without pruning the registry grows forever and a
+ * reused pid is treated as "already killed" — a silent no-op (RV-11).
+ *
+ * @param now - Clock value to compare the TTL against (injectable for tests).
+ */
+export function pruneKillTreeState(now = Date.now()) {
+    for (const [pid, killedAt] of terminatedPids) {
+        if (!isPidAlive(pid) || now - killedAt > KILL_TTL_MS) {
+            terminatedPids.delete(pid);
+        }
+    }
+}
+/** True when the process (or its process group) is still alive. */
+export function isPidAlive(pid) {
+    if (!pid || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code !== "ESRCH";
+    }
+}
+/**
+ * Kill a child process and its whole subtree. Idempotent per pid while the
+ * kill is in-flight (the registry is pruned once the process exits).
+ *
+ * @param child - The spawned child process.
+ * @param signal - POSIX signal for the direct kill (default "SIGTERM").
+ *   Windows always uses `taskkill /T /F`.
+ * @returns `true` when the kill was issued (or already issued), `false` when
+ *   there is no pid yet (child not spawned).
+ */
+export function killProcessTree(child, signal = "SIGTERM") {
+    const pid = child.pid;
+    if (!pid || pid <= 0)
+        return false;
+    pruneKillTreeState();
+    if (terminatedPids.has(pid))
+        return true;
+    terminatedPids.set(pid, Date.now());
+    if (process.platform === "win32") {
+        spawn("taskkill", ["/pid", String(pid), "/T", "/F"], {
+            windowsHide: true,
+            stdio: "ignore",
+        }).unref();
+        return true;
+    }
+    // POSIX: the child was spawned detached → kill the whole process group.
+    try {
+        process.kill(-pid, signal);
+    }
+    catch (err) {
+        if (err.code === "ESRCH") {
+            // Already gone — group kill is best-effort.
+            return true;
+        }
+        try {
+            process.kill(pid, signal);
+        }
+        catch {
+            // Already gone.
+        }
+    }
+    return true;
+}
+/**
+ * Kill a child process and its whole subtree, then await its exit.
+ *
+ * This is the awaited form of {@link killProcessTree} (RV-11): on Windows the
+ * `taskkill /T` spawn is no longer fire-and-forget — the returned promise
+ * resolves only after the child has actually exited, or the given timeout
+ * elapses.
+ *
+ * @param child - The spawned child process.
+ * @param signal - POSIX signal for the direct kill (default "SIGTERM").
+ * @param timeoutMs - How long to wait for the child to exit (default 5000).
+ * @returns `true` when the kill was issued (or already issued), `false` when
+ *   there is no pid yet (child not spawned).
+ */
+export function killProcessTreeAndWait(child, signal = "SIGTERM", timeoutMs = 5_000) {
+    const issued = killProcessTree(child, signal);
+    if (!issued)
+        return Promise.resolve(false);
+    if (child.exitCode !== null || child.signalCode !== null)
+        return Promise.resolve(true);
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => resolve(true), timeoutMs);
+        const done = () => {
+            clearTimeout(timer);
+            resolve(true);
+        };
+        child.once("exit", done);
+        child.once("error", done);
+    });
+}
+/**
+ * Cross-platform spawn option that makes `killProcessTree` reach the whole
+ * tree. On Windows no extra flag is needed (taskkill walks the tree).
+ */
+export function treeKillSpawnOptions() {
+    return { detached: process.platform !== "win32" };
+}
+//# sourceMappingURL=kill-tree.js.map

package/dist/kill-tree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kill-tree.js","sourceRoot":"","sources":["../src/kill-tree.ts"],"names":[],"mappings":"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"}

package/dist/shell-parser.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Shell command parsing utility.
+ * Extracts file and args from a command string, handling quotes and escapes.
+ */
+export declare function parseCommand(cmd: string): {
+    file: string;
+    args: string[];
+};
+//# sourceMappingURL=shell-parser.d.ts.map

package/dist/shell-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell-parser.d.ts","sourceRoot":"","sources":["../src/shell-parser.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,CAiC1E"}

package/dist/shell-parser.js

@@ -0,0 +1,69 @@
+/**
+ * Shell command parsing utility.
+ * Extracts file and args from a command string, handling quotes and escapes.
+ */
+export function parseCommand(cmd) {
+    const trimmed = cmd.trim();
+    if (!trimmed)
+        return { file: "", args: [] };
+    const tokens = [];
+    let i = 0;
+    let current = "";
+    let inSingle = false;
+    let inDouble = false;
+    while (i < trimmed.length) {
+        const ch = trimmed[i] ?? "";
+        if (inSingle) {
+            if (ch === "'") {
+                inSingle = false;
+            }
+            else {
+                current += ch;
+            }
+            i++;
+        }
+        else if (inDouble) {
+            if (ch === '"') {
+                inDouble = false;
+                i++;
+            }
+            else if (ch === "\\" && i + 1 < trimmed.length) {
+                current += trimmed[i + 1];
+                i += 2;
+            }
+            else {
+                current += ch;
+                i++;
+            }
+        }
+        else if (ch === "'") {
+            inSingle = true;
+            i++;
+        }
+        else if (ch === '"') {
+            inDouble = true;
+            i++;
+        }
+        else if (ch === "\\" && i + 1 < trimmed.length) {
+            current += trimmed[i + 1];
+            i += 2;
+        }
+        else if (/\s/.test(ch)) {
+            if (current) {
+                tokens.push(current);
+                current = "";
+            }
+            i++;
+        }
+        else {
+            current += ch;
+            i++;
+        }
+    }
+    if (current)
+        tokens.push(current);
+    if (tokens.length === 0)
+        return { file: "", args: [] };
+    return { file: tokens[0], args: tokens.slice(1) };
+}
+//# sourceMappingURL=shell-parser.js.map

package/dist/shell-parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell-parser.js","sourceRoot":"","sources":["../src/shell-parser.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAC3B,IAAI,CAAC,OAAO;QAAE,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;IAE5C,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,IAAI,OAAO,GAAG,EAAE,CAAC;IACjB,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,IAAI,QAAQ,GAAG,KAAK,CAAC;IAErB,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;QAC1B,MAAM,EAAE,GAAG,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAC5B,IAAI,QAAQ,EAAE,CAAC;YACb,IAAI,EAAE,KAAK,GAAG,EAAE,CAAC;gBAAC,QAAQ,GAAG,KAAK,CAAC;YAAC,CAAC;iBAChC,CAAC;gBAAC,OAAO,IAAI,EAAE,CAAC;YAAC,CAAC;YACvB,CAAC,EAAE,CAAC;QACN,CAAC;aAAM,IAAI,QAAQ,EAAE,CAAC;YACpB,IAAI,EAAE,KAAK,GAAG,EAAE,CAAC;gBAAC,QAAQ,GAAG,KAAK,CAAC;gBAAC,CAAC,EAAE,CAAC;YAAC,CAAC;iBACrC,IAAI,EAAE,KAAK,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;gBAAC,OAAO,IAAI,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;gBAAC,CAAC,IAAI,CAAC,CAAC;YAAC,CAAC;iBACjF,CAAC;gBAAC,OAAO,IAAI,EAAE,CAAC;gBAAC,CAAC,EAAE,CAAC;YAAC,CAAC;QAC9B,CAAC;aAAM,IAAI,EAAE,KAAK,GAAG,EAAE,CAAC;YAAC,QAAQ,GAAG,IAAI,CAAC;YAAC,CAAC,EAAE,CAAC;QAAC,CAAC;aAC3C,IAAI,EAAE,KAAK,GAAG,EAAE,CAAC;YAAC,QAAQ,GAAG,IAAI,CAAC;YAAC,CAAC,EAAE,CAAC;QAAC,CAAC;aACzC,IAAI,EAAE,KAAK,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;YAAC,OAAO,IAAI,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YAAC,CAAC,IAAI,CAAC,CAAC;QAAC,CAAC;aACjF,IAAI,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;YACvB,IAAI,OAAO,EAAE,CAAC;gBAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;YAAC,CAAC;YACpD,CAAC,EAAE,CAAC;QACN,CAAC;aACI,CAAC;YAAC,OAAO,IAAI,EAAE,CAAC;YAAC,CAAC,EAAE,CAAC;QAAC,CAAC;IAC9B,CAAC;IACD,IAAI,OAAO;QAAE,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAElC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;IACvD,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC,CAAE,EAAE,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;AACrD,CAAC"}

package/dist/timeout.d.ts

@@ -0,0 +1,31 @@
+import type { ChildProcess } from "node:child_process";
+/**
+ * Attach timeout + abort handling to a child process.
+ *
+ * This is the shared pattern used by all sandbox backends (host, process,
+ * container) to enforce execution timeouts and abort signals. It replaces
+ * the duplicated `setTimeout` + `killProcessTree` + abort listener logic
+ * that was previously copy-pasted across backends.
+ *
+ * RV-11: the timeout must kill the whole tree, not just the direct child.
+ * `execFile`'s built-in `timeout` option only SIGTERMs the spawned pid,
+ * orphaning grandchildren — so the timeout is handled here instead.
+ *
+ * @param child - The spawned child process
+ * @param timeoutMs - Maximum execution time in milliseconds
+ * @param signal - Optional abort signal
+ * @param onAbort - Callback when timeout or abort fires (resolves the promise)
+ *
+ * @example
+ * ```ts
+ * const child = execFile(file, args, options, callback);
+ * withTimeoutAndAbort(child, 30_000, signal, () => {
+ *   resolve({ result: { stdout: "", stderr: "Aborted", exitCode: 1 }, exitCode: 1, durationMs: Date.now() - start, timedOut: false });
+ * });
+ * ```
+ */
+export declare function withTimeoutAndAbort(child: ChildProcess, timeoutMs: number, signal: AbortSignal | undefined, onAbort: (reason: string) => void): {
+    timedOut: boolean;
+    clearTimer: () => void;
+};
+//# sourceMappingURL=timeout.d.ts.map

package/dist/timeout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeout.d.ts","sourceRoot":"","sources":["../src/timeout.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGvD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,YAAY,EACnB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,WAAW,GAAG,SAAS,EAC/B,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,GAChC;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,MAAM,IAAI,CAAA;CAAE,CAgC/C"}

package/dist/timeout.js

@@ -0,0 +1,57 @@
+import { killProcessTree } from "./kill-tree.js";
+/**
+ * Attach timeout + abort handling to a child process.
+ *
+ * This is the shared pattern used by all sandbox backends (host, process,
+ * container) to enforce execution timeouts and abort signals. It replaces
+ * the duplicated `setTimeout` + `killProcessTree` + abort listener logic
+ * that was previously copy-pasted across backends.
+ *
+ * RV-11: the timeout must kill the whole tree, not just the direct child.
+ * `execFile`'s built-in `timeout` option only SIGTERMs the spawned pid,
+ * orphaning grandchildren — so the timeout is handled here instead.
+ *
+ * @param child - The spawned child process
+ * @param timeoutMs - Maximum execution time in milliseconds
+ * @param signal - Optional abort signal
+ * @param onAbort - Callback when timeout or abort fires (resolves the promise)
+ *
+ * @example
+ * ```ts
+ * const child = execFile(file, args, options, callback);
+ * withTimeoutAndAbort(child, 30_000, signal, () => {
+ *   resolve({ result: { stdout: "", stderr: "Aborted", exitCode: 1 }, exitCode: 1, durationMs: Date.now() - start, timedOut: false });
+ * });
+ * ```
+ */
+export function withTimeoutAndAbort(child, timeoutMs, signal, onAbort) {
+    let timedOut = false;
+    // RV-11: kill the whole tree, not just the direct child
+    const timer = setTimeout(() => {
+        timedOut = true;
+        killProcessTree(child);
+        onAbort("Aborted");
+    }, timeoutMs);
+    const clearTimer = () => clearTimeout(timer);
+    child.once("exit", clearTimer);
+    child.once("error", clearTimer);
+    if (signal) {
+        if (signal.aborted) {
+            clearTimeout(timer);
+            killProcessTree(child);
+            onAbort(signal.reason ?? "Aborted");
+        }
+        else {
+            signal.addEventListener("abort", () => {
+                clearTimeout(timer);
+                killProcessTree(child);
+                onAbort(signal.reason ?? "Aborted");
+            }, { once: true });
+        }
+    }
+    return {
+        get timedOut() { return timedOut; },
+        clearTimer,
+    };
+}
+//# sourceMappingURL=timeout.js.map

package/dist/timeout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeout.js","sourceRoot":"","sources":["../src/timeout.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,mBAAmB,CACjC,KAAmB,EACnB,SAAiB,EACjB,MAA+B,EAC/B,OAAiC;IAEjC,IAAI,QAAQ,GAAG,KAAK,CAAC;IAErB,wDAAwD;IACxD,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;QAC5B,QAAQ,GAAG,IAAI,CAAC;QAChB,eAAe,CAAC,KAAK,CAAC,CAAC;QACvB,OAAO,CAAC,SAAS,CAAC,CAAC;IACrB,CAAC,EAAE,SAAS,CAAC,CAAC;IAEd,MAAM,UAAU,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;IAC7C,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAC/B,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;IAEhC,IAAI,MAAM,EAAE,CAAC;QACX,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,eAAe,CAAC,KAAK,CAAC,CAAC;YACvB,OAAO,CAAC,MAAM,CAAC,MAAM,IAAI,SAAS,CAAC,CAAC;QACtC,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,GAAG,EAAE;gBACpC,YAAY,CAAC,KAAK,CAAC,CAAC;gBACpB,eAAe,CAAC,KAAK,CAAC,CAAC;gBACvB,OAAO,CAAC,MAAM,CAAC,MAAM,IAAI,SAAS,CAAC,CAAC;YACtC,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QACrB,CAAC;IACH,CAAC;IAED,OAAO;QACL,IAAI,QAAQ,KAAK,OAAO,QAAQ,CAAC,CAAC,CAAC;QACnC,UAAU;KACsC,CAAC;AACrD,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,68 @@
+/** Sandbox execution scope — string type, NOT closed union */
+export type SandboxScope = string;
+/**
+ * Default sandbox scopes — exported for convenience.
+ * Backends register custom scopes via the `createSandbox` backends map.
+ */
+export declare const KNOWN_SANDBOX_SCOPES: readonly ["host", "process", "container"];
+/** Sandbox configuration */
+export interface SandboxConfig {
+    defaultTimeoutMs: number;
+    /** Execution scope (default: "host" — no isolation) */
+    scope?: SandboxScope;
+    /** Allowed filesystem paths (for "process" scope) */
+    allowedPaths?: string[];
+    /** Blocked filesystem paths */
+    blockedPaths?: string[];
+    /** Allow network access (default: true) */
+    allowNetwork?: boolean;
+    /** Allowed environment variables */
+    allowedEnvVars?: string[];
+    /** Allowed commands (for "process" scope) */
+    allowedCommands?: Set<string>;
+    /** Enable Node.js Permission Model (Node 22+) */
+    enablePermissionModel?: boolean;
+    readonly metadata?: Record<string, unknown>;
+}
+/** Result of a sandboxed execution */
+export interface SandboxResult<T = unknown> {
+    result: T;
+    exitCode: number;
+    durationMs: number;
+    timedOut: boolean;
+    /** Resources consumed during execution */
+    resources?: {
+        cpuTimeMs?: number;
+        memoryBytes?: number;
+    };
+    readonly metadata?: Record<string, unknown>;
+}
+/** Options for a sandboxed command execution */
+export interface ProcessSandboxExecuteOptions {
+    command: string;
+    cwd: string;
+    timeoutMs: number;
+    env?: Record<string, string>;
+    signal?: AbortSignal;
+}
+/**
+ * Interface for sandbox execution adapters.
+ *
+ * Implementations can provide different levels of isolation:
+ * - `host`: No isolation
+ * - `process`: Node.js Permission Model + empty env + command allowlist
+ * - `container`: Docker/Firecracker microVM
+ */
+export interface ProcessSandbox {
+    /** The scope this sandbox provides */
+    readonly scope: SandboxScope;
+    /** Execute a command in the sandbox */
+    execute(options: ProcessSandboxExecuteOptions): Promise<SandboxResult<{
+        stdout: string;
+        stderr: string;
+        exitCode: number;
+    }>>;
+    /** Clean up resources */
+    destroy(): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAC9D,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC;AAElC;;;GAGG;AACH,eAAO,MAAM,oBAAoB,2CAA4C,CAAC;AAE9E,4BAA4B;AAC5B,MAAM,WAAW,aAAa;IAC5B,gBAAgB,EAAE,MAAM,CAAC;IACzB,uDAAuD;IACvD,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,qDAAqD;IACrD,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,+BAA+B;IAC/B,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,2CAA2C;IAC3C,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,oCAAoC;IACpC,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,6CAA6C;IAC7C,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC9B,iDAAiD;IACjD,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC7C;AAED,sCAAsC;AACtC,MAAM,WAAW,aAAa,CAAC,CAAC,GAAG,OAAO;IACxC,MAAM,EAAE,CAAC,CAAC;IACV,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;IAClB,0CAA0C;IAC1C,SAAS,CAAC,EAAE;QACV,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC7C;AAED,gDAAgD;AAChD,MAAM,WAAW,4BAA4B;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,sCAAsC;IACtC,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAE7B,uCAAuC;IACvC,OAAO,CAAC,OAAO,EAAE,4BAA4B,GAAG,OAAO,CAAC,aAAa,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAC;IAE7H,yBAAyB;IACzB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B"}

package/dist/types.js

@@ -0,0 +1,6 @@
+/**
+ * Default sandbox scopes — exported for convenience.
+ * Backends register custom scopes via the `createSandbox` backends map.
+ */
+export const KNOWN_SANDBOX_SCOPES = ["host", "process", "container"];
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,MAAM,EAAE,SAAS,EAAE,WAAW,CAAU,CAAC"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@vinhnt-sdk/sandbox",
+  "version": "0.1.3",
+  "description": "Sandbox primitives for VNT Agent — ProcessSandbox interface, config/result types, fail-closed SandboxUnavailableError, command parsing and tree-scoped process termination",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vinhnt-develop/vinhnt-sdk.git",
+    "directory": "packages/sandbox"
+  },
+  "homepage": "https://github.com/vinhnt-develop/vinhnt-sdk/tree/main/packages/sandbox",
+  "bugs": {
+    "url": "https://github.com/vinhnt-develop/vinhnt-sdk/issues"
+  },
+  "keywords": [
+    "vnt",
+    "sandbox",
+    "process-isolation",
+    "security",
+    "shell"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@vinhnt-sdk/schema": "0.1.3",
+    "@vinhnt-sdk/security": "0.1.3"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc --noEmit",
+    "clean": "node -e \"try{require('fs').rmSync('dist',{recursive:true,force:true})}catch(e){}\" && node -e \"try{require('fs').rmSync('tsconfig.tsbuildinfo',{force:true})}catch(e){}\"",
+    "test": "vitest run",
+    "lint": "eslint ."
+  }
+}