@b4run/sandbox 0.8.28

package/dist/docker/docker-sandbox.js

@@ -0,0 +1,267 @@
+import { createHash } from "node:crypto";
+import { sandboxUnavailable } from "../errors.js";
+import { createDocker } from "./docker-cli.js";
+import { dockerExec } from "./docker-exec.js";
+import { dockerFilesystem } from "./docker-filesystem.js";
+import { createThreadLifecycleCoordinator } from "./thread-lifecycle.js";
+const ROOT = "/workspace";
+const sanitize = (s) => s.replaceAll(/[^a-zA-Z0-9_.-]/g, "_");
+const containerName = (threadId) => `b4-sbx-${sanitize(threadId)}`;
+const volumeName = (threadId) => `b4-sbx-vol-${sanitize(threadId)}`;
+const recoveryAttempt = Symbol("dockerRecoveryAttempt");
+function resolveLaunchConfig(policy) {
+    const sec = policy.security ?? {};
+    const user = sec.runAsNonRoot === false
+        ? null
+        : typeof sec.runAsNonRoot === "object" && sec.runAsNonRoot !== null
+            ? Object.freeze({ uid: sec.runAsNonRoot.uid, gid: sec.runAsNonRoot.gid })
+            : Object.freeze({ uid: 1000, gid: 1000 });
+    const effectiveEnv = new Map(Object.entries(policy.env ?? {}));
+    if (user !== null)
+        effectiveEnv.set("HOME", ROOT);
+    const env = Object.freeze([...effectiveEnv.entries()]
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([key, value]) => Object.freeze([key, value])));
+    // timeoutMs is intentionally handle-local: it changes exec cancellation,
+    // not the keeper container that is shared by every handle for a thread.
+    return Object.freeze({
+        networkMode: policy.network.mode === "deny" ? "none" : "bridge",
+        env,
+        memoryMb: policy.resources?.memoryMb ? policy.resources.memoryMb : null,
+        cpus: policy.resources?.cpus ? policy.resources.cpus : null,
+        dropAllCapabilities: sec.dropAllCapabilities ?? true,
+        noNewPrivileges: sec.noNewPrivileges ?? true,
+        readOnlyRootFilesystem: sec.readOnlyRootFilesystem ?? true,
+        pidsLimit: sec.pidsLimit ?? 512,
+        user,
+    });
+}
+const launchConfigKey = (config) => JSON.stringify(config);
+const keeperIdentity = (image, config) => createHash("sha256")
+    .update(JSON.stringify({ image, launchConfig: config }))
+    .digest("hex");
+const isB4CodedError = (error) => error instanceof Error &&
+    typeof error.code === "string" &&
+    /^B4_E\d{4}$/.test(error.code);
+/**
+ * Docker reference SandboxProvider. Per thread: a persistent container
+ * `b4-sbx-<threadId>` (sleep infinity) with a named volume mounted at
+ * /workspace. acquire() reuses only a keeper owned by this provider lifecycle
+ * with a matching persisted identity; otherwise it replaces the keeper while
+ * preserving the volume. release() removes the container but KEEPS the volume;
+ * destroy() removes both. Network: deny → --network none (exact); allow →
+ * bridge (denylist is best-effort and NOT enforced here — see the spec's
+ * honest-scope note). Host env is never inherited; only policy.env is passed.
+ */
+export function dockerSandbox(opts) {
+    const docker = opts.docker ?? createDocker();
+    const lifecycleStates = new Map();
+    const lifecycle = createThreadLifecycleCoordinator();
+    const createLifecycleState = (launchConfig) => ({
+        generation: 0,
+        recoverySignal: new AbortController().signal,
+        launchConfig,
+        launchConfigKey: launchConfigKey(launchConfig),
+        keeperIdentity: keeperIdentity(opts.image, launchConfig),
+    });
+    const isRecoveryAttempt = (token) => typeof token === "object" && token !== null && recoveryAttempt in token;
+    const recoveryError = (threadId, phase, error) => {
+        if (isB4CodedError(error))
+            return error;
+        const detail = error instanceof Error ? error.message : String(error);
+        const wrapped = sandboxUnavailable(`Sandbox unavailable: Docker PID recovery ${phase} failed for thread "${threadId}": ${detail || "unknown error"}. Run \`b4 check\`.`);
+        Object.defineProperty(wrapped, "cause", { value: error, configurable: true });
+        return wrapped;
+    };
+    const ensureContainer = async (threadId, launchConfig, expectedIdentity, signal, reuseExisting) => {
+        const name = containerName(threadId);
+        const running = await docker.run(["ps", "-q", "--filter", `name=^${name}$`], { signal });
+        const runningId = running.stdout.trim();
+        const existing = runningId
+            ? running
+            : await docker.run(["ps", "-aq", "--filter", `name=^${name}$`], { signal });
+        if (existing.stdout.trim()) {
+            if (reuseExisting) {
+                const inspected = await docker.run(["inspect", "--format", '{{ index .Config.Labels "b4.sandbox.identity" }}', name], { signal });
+                if (inspected.exitCode === 0 && inspected.stdout.trim() === expectedIdentity) {
+                    if (runningId)
+                        return name;
+                    const started = await docker.run(["start", name], { signal });
+                    if (started.exitCode !== 0) {
+                        throw sandboxUnavailable(`Sandbox unavailable: could not start keeper for thread "${threadId}": ${started.stderr.trim() || "unknown error"}. Run \`b4 check\`.`);
+                    }
+                    return name;
+                }
+            }
+            const removed = await docker.run(["rm", "-f", name], { signal });
+            if (removed.exitCode !== 0) {
+                throw sandboxUnavailable(`Sandbox unavailable: could not replace stale keeper for thread "${threadId}": ${removed.stderr.trim() || "unknown error"}. Run \`b4 check\`.`);
+            }
+        }
+        const net = ["--network", launchConfig.networkMode];
+        const envArgs = launchConfig.env.flatMap(([key, value]) => ["-e", `${key}=${value}`]);
+        const limits = [
+            ...(launchConfig.memoryMb !== null ? ["--memory", `${launchConfig.memoryMb}m`] : []),
+            ...(launchConfig.cpus !== null ? ["--cpus", String(launchConfig.cpus)] : []),
+        ];
+        const user = launchConfig.user;
+        const hardening = [
+            ...(launchConfig.dropAllCapabilities ? ["--cap-drop", "ALL"] : []),
+            ...(launchConfig.noNewPrivileges ? ["--security-opt", "no-new-privileges"] : []),
+            "--pids-limit",
+            String(launchConfig.pidsLimit),
+            ...(launchConfig.readOnlyRootFilesystem
+                ? ["--read-only", "--tmpfs", "/tmp", "--tmpfs", "/run"]
+                : []),
+            ...(user !== null ? ["--user", `${user.uid}:${user.gid}`] : []),
+        ];
+        // Architecture B (no steady-state root): a fresh named volume mounts
+        // root:root, so a non-root keeper cannot write /workspace. Fix it with a
+        // CREATE-ONLY, VOLUME-ABSENCE-CHECKED, ephemeral (`--rm`) root chown — the
+        // only root that ever runs, and it takes no agent input. On reattach (the
+        // volume already exists) this is skipped so a populated volume is never
+        // re-chowned. Skipped entirely when runAsNonRoot:false (`user` is null).
+        // The inspect→chown is not atomic, but chown is idempotent, so two racing
+        // acquires for the same fresh thread both converge on the same ownership.
+        if (user !== null) {
+            const volExists = await docker.run(["volume", "inspect", volumeName(threadId)], { signal });
+            if (volExists.exitCode !== 0) {
+                const init = await docker.run([
+                    "run",
+                    "--rm",
+                    "--user",
+                    "0:0",
+                    "-v",
+                    `${volumeName(threadId)}:${ROOT}`,
+                    opts.image,
+                    "sh",
+                    "-c",
+                    `mkdir -p ${ROOT} && chown ${user.uid}:${user.gid} ${ROOT}`,
+                ], { signal });
+                if (init.exitCode !== 0) {
+                    throw sandboxUnavailable(`Sandbox unavailable: could not initialize workspace ownership for thread "${threadId}": ${init.stderr.trim() || "unknown error"}. Run \`b4 check\`.`);
+                }
+            }
+        }
+        const created = await docker.run([
+            "run",
+            "-d",
+            "--name",
+            name,
+            "--label",
+            `b4.sandbox=${sanitize(threadId)}`,
+            "--label",
+            `b4.sandbox.identity=${expectedIdentity}`,
+            "-v",
+            `${volumeName(threadId)}:${ROOT}`,
+            ...net,
+            ...envArgs,
+            ...limits,
+            ...hardening,
+            opts.image,
+            "sleep",
+            "infinity",
+        ], { signal });
+        if (created.exitCode !== 0) {
+            throw sandboxUnavailable(`Sandbox unavailable: docker run failed for thread "${threadId}": ${created.stderr.trim() || "unknown error"}. Run \`b4 check\`.`);
+        }
+        return name;
+    };
+    const recoverAndRetry = async (threadId, token, retry) => lifecycle.runExclusive(threadId, async () => {
+        if (!isRecoveryAttempt(token))
+            return undefined;
+        const { state, generation } = token;
+        if (lifecycleStates.get(threadId) !== state || generation > state.generation) {
+            return undefined;
+        }
+        if (generation === state.generation) {
+            // Removal and recreation are provider lifecycle work. They use a
+            // provider-owned non-aborted signal so cancellation of one caller
+            // cannot strand the shared thread without a keeper.
+            const signal = state.recoverySignal;
+            try {
+                const removed = await docker
+                    .run(["rm", "-f", containerName(threadId)], { signal })
+                    .catch((error) => {
+                    throw recoveryError(threadId, "removal", error);
+                });
+                if (removed.exitCode !== 0) {
+                    throw sandboxUnavailable(`Sandbox unavailable: could not remove PID-exhausted container for thread "${threadId}": ${removed.stderr.trim() || "unknown error"}. Run \`b4 check\`.`);
+                }
+                await ensureContainer(threadId, state.launchConfig, state.keeperIdentity, signal, false).catch((error) => {
+                    throw recoveryError(threadId, "recreation", error);
+                });
+                state.generation = generation + 1;
+            }
+            catch (error) {
+                if (lifecycleStates.get(threadId) === state)
+                    lifecycleStates.delete(threadId);
+                throw error;
+            }
+        }
+        return retry();
+    });
+    return {
+        name: "docker",
+        acquire({ threadId, policy, signal }) {
+            return lifecycle.runExclusive(threadId, async () => {
+                const requestedLaunchConfig = resolveLaunchConfig(policy);
+                const requestedLaunchConfigKey = launchConfigKey(requestedLaunchConfig);
+                const existingState = lifecycleStates.get(threadId);
+                if (existingState !== undefined &&
+                    existingState.launchConfigKey !== requestedLaunchConfigKey) {
+                    throw sandboxUnavailable(`Sandbox unavailable: thread "${threadId}" already has a different keeper configuration. Release the thread sandbox first, then acquire it with a different policy.`);
+                }
+                const launchConfig = existingState?.launchConfig ?? requestedLaunchConfig;
+                const state = existingState ?? createLifecycleState(launchConfig);
+                const container = await ensureContainer(threadId, launchConfig, state.keeperIdentity, signal, existingState !== undefined);
+                lifecycleStates.set(threadId, state);
+                const pidExhaustionRecovery = {
+                    captureToken: () => ({
+                        [recoveryAttempt]: true,
+                        state,
+                        generation: state.generation,
+                    }),
+                    recoverAndRetry: (token, retry) => recoverAndRetry(threadId, token, retry),
+                };
+                return {
+                    threadId,
+                    filesystem: dockerFilesystem(docker, container, {
+                        runWithExecLease: (operation) => lifecycle.runShared(threadId, operation),
+                        pidExhaustionRecovery,
+                    }),
+                    exec: dockerExec(docker, container, {
+                        runWithExecLease: (operation) => lifecycle.runShared(threadId, operation),
+                        ...(policy.resources?.timeoutMs !== undefined
+                            ? { timeoutMs: policy.resources.timeoutMs }
+                            : {}),
+                        pidExhaustionRecovery,
+                    }),
+                    workspaceRoot: ROOT,
+                };
+            });
+        },
+        release(threadId) {
+            return lifecycle.runExclusive(threadId, async () => {
+                lifecycleStates.delete(threadId);
+                await docker.run(["rm", "-f", containerName(threadId)]).catch(() => { });
+            });
+        },
+        destroy(threadId) {
+            return lifecycle.runExclusive(threadId, async () => {
+                lifecycleStates.delete(threadId);
+                await docker.run(["rm", "-f", containerName(threadId)]).catch(() => { });
+                await docker.run(["volume", "rm", volumeName(threadId)]).catch(() => { });
+            });
+        },
+        async preflight() {
+            const v = await docker
+                .run(["version", "--format", "{{.Server.Version}}"])
+                .catch(() => undefined);
+            if (!v || v.exitCode !== 0) {
+                return { ok: false, detail: "Docker daemon not reachable (`docker version` failed)." };
+            }
+            return { ok: true, detail: `Docker ${v.stdout.trim()}` };
+        },
+    };
+}

package/dist/docker/thread-lifecycle.d.ts

@@ -0,0 +1,15 @@
+export interface ThreadLifecycleCoordinator {
+    readonly pendingThreadCount: number;
+    runShared<T>(threadId: string, operation: () => Promise<T>): Promise<T>;
+    runExclusive<T>(threadId: string, operation: () => Promise<T>): Promise<T>;
+}
+/**
+ * Keyed fair shared/exclusive gate for Docker container access.
+ *
+ * Exec and filesystem operations share the keeper concurrently. Lifecycle
+ * mutations are exclusive: they wait for admitted container operations to
+ * drain, and their queue position prevents later operations from starting.
+ * Idle thread state is discarded.
+ */
+export declare function createThreadLifecycleCoordinator(): ThreadLifecycleCoordinator;
+//# sourceMappingURL=thread-lifecycle.d.ts.map

package/dist/docker/thread-lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"thread-lifecycle.d.ts","sourceRoot":"","sources":["../../src/docker/thread-lifecycle.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAA;IACnC,SAAS,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;IACvE,YAAY,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;CAC3E;AAaD;;;;;;;GAOG;AACH,wBAAgB,gCAAgC,IAAI,0BAA0B,CAmF7E"}

package/dist/docker/thread-lifecycle.js

@@ -0,0 +1,85 @@
+/**
+ * Keyed fair shared/exclusive gate for Docker container access.
+ *
+ * Exec and filesystem operations share the keeper concurrently. Lifecycle
+ * mutations are exclusive: they wait for admitted container operations to
+ * drain, and their queue position prevents later operations from starting.
+ * Idle thread state is discarded.
+ */
+export function createThreadLifecycleCoordinator() {
+    const states = new Map();
+    const drain = (threadId, state) => {
+        if (state.exclusiveActive || state.activeShared > 0)
+            return;
+        const first = state.queue[0];
+        if (first === undefined) {
+            if (states.get(threadId) === state)
+                states.delete(threadId);
+            return;
+        }
+        if (first.kind === "exclusive") {
+            state.queue.shift();
+            state.exclusiveActive = true;
+            first.start();
+            return;
+        }
+        while (state.queue[0]?.kind === "shared") {
+            const entry = state.queue.shift();
+            if (entry === undefined)
+                break;
+            state.activeShared += 1;
+            entry.start();
+        }
+    };
+    const enqueue = (threadId, kind, operation) => {
+        let state = states.get(threadId);
+        if (state === undefined) {
+            state = { activeShared: 0, exclusiveActive: false, queue: [] };
+            states.set(threadId, state);
+        }
+        const threadState = state;
+        return new Promise((resolve, reject) => {
+            const entry = {
+                kind,
+                start: () => {
+                    void Promise.resolve()
+                        .then(operation)
+                        .then((value) => {
+                        if (kind === "shared")
+                            threadState.activeShared -= 1;
+                        else
+                            threadState.exclusiveActive = false;
+                        drain(threadId, threadState);
+                        resolve(value);
+                    }, (error) => {
+                        if (kind === "shared")
+                            threadState.activeShared -= 1;
+                        else
+                            threadState.exclusiveActive = false;
+                        drain(threadId, threadState);
+                        reject(error);
+                    });
+                },
+            };
+            if (kind === "shared" && !threadState.exclusiveActive && threadState.queue.length === 0) {
+                threadState.activeShared += 1;
+                entry.start();
+            }
+            else {
+                threadState.queue.push(entry);
+                drain(threadId, threadState);
+            }
+        });
+    };
+    return {
+        get pendingThreadCount() {
+            return states.size;
+        },
+        runShared(threadId, operation) {
+            return enqueue(threadId, "shared", operation);
+        },
+        runExclusive(threadId, operation) {
+            return enqueue(threadId, "exclusive", operation);
+        },
+    };
+}

package/dist/errors.d.ts

@@ -0,0 +1,12 @@
+import type { B4ErrorCode } from "@b4run/sdk";
+/** An `Error` tagged with a stable B4.run registry code so surfaces can link docs. */
+export interface B4CodedError extends Error {
+    readonly code: B4ErrorCode;
+}
+/**
+ * Construct a "sandbox unavailable" error carrying the `B4_E2001` code. The
+ * code rides on the error object so an HTTP/SSE error body (or any caught-error
+ * surface) can attach the docs link without re-deriving it from the message.
+ */
+export declare function sandboxUnavailable(message: string): B4CodedError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAE7C,sFAAsF;AACtF,MAAM,WAAW,YAAa,SAAQ,KAAK;IACzC,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAC3B;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,CAIhE"}

package/dist/errors.js

@@ -0,0 +1,10 @@
+/**
+ * Construct a "sandbox unavailable" error carrying the `B4_E2001` code. The
+ * code rides on the error object so an HTTP/SSE error body (or any caught-error
+ * surface) can attach the docs link without re-deriving it from the message.
+ */
+export function sandboxUnavailable(message) {
+    const error = new Error(message);
+    error.code = "B4_E2001";
+    return error;
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export type { SandboxConfig, SandboxHandle, SandboxPolicy, SandboxProvider, } from "@b4run/workspace";
+export { type DockerSandboxOptions, dockerSandbox } from "./docker/docker-sandbox.js";
+export { KubeAuthorizationReviewError, type KubeClient, type KubePermission, } from "./kubernetes/kube-client.js";
+export { type KubernetesSandboxOptions, kubernetesSandbox } from "./kubernetes/kube-sandbox.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,EACV,aAAa,EACb,aAAa,EACb,aAAa,EACb,eAAe,GAChB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,KAAK,oBAAoB,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAA;AACrF,OAAO,EACL,4BAA4B,EAC5B,KAAK,UAAU,EACf,KAAK,cAAc,GACpB,MAAM,6BAA6B,CAAA;AACpC,OAAO,EAAE,KAAK,wBAAwB,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAA"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { dockerSandbox } from "./docker/docker-sandbox.js";
+export { KubeAuthorizationReviewError, } from "./kubernetes/kube-client.js";
+export { kubernetesSandbox } from "./kubernetes/kube-sandbox.js";

package/dist/kubernetes/default-kube-client.d.ts

@@ -0,0 +1,6 @@
+/** Default KubeClient backed by the real @kubernetes/client-node (v1.x) API.
+ * KubeConfig.loadFromDefault() auto-detects in-cluster ServiceAccount token vs
+ * ~/.kube/config. Unit tests never construct this — they inject a fake KubeClient. */
+import { type KubeClient } from "./kube-client.js";
+export declare function createDefaultKubeClient(): KubeClient;
+//# sourceMappingURL=default-kube-client.d.ts.map

package/dist/kubernetes/default-kube-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-kube-client.d.ts","sourceRoot":"","sources":["../../src/kubernetes/default-kube-client.ts"],"names":[],"mappings":"AAAA;;sFAEsF;AAiBtF,OAAO,EAEL,KAAK,UAAU,EAKhB,MAAM,kBAAkB,CAAA;AA4IzB,wBAAgB,uBAAuB,IAAI,UAAU,CAoNpD"}