@b4run/sandbox 0.8.28

package/dist/kubernetes/kube-sandbox.js

@@ -0,0 +1,278 @@
+import { createHash } from "node:crypto";
+import { sandboxUnavailable } from "../errors.js";
+import { createDefaultKubeClient } from "./default-kube-client.js";
+import { KubeAuthorizationReviewError, REQUIRED_KUBE_PERMISSIONS, } from "./kube-client.js";
+import { kubeExec } from "./kube-exec.js";
+import { kubeFilesystem } from "./kube-filesystem.js";
+const ROOT = "/workspace";
+// Linear leading/trailing '-' trim. Avoids anchored `-+`/`^-+` regexes, which are a
+// polynomial-ReDoS pattern (O(n^2) backtracking on adversarial dash runs) when run on
+// an uncontrolled thread id.
+const trimDashes = (s) => {
+    let start = 0;
+    let end = s.length;
+    while (start < end && s[start] === "-")
+        start++;
+    while (end > start && s[end - 1] === "-")
+        end--;
+    return s.slice(start, end);
+};
+// DNS-1123 label: lowercase alphanumeric + '-', <=63 chars. Bare truncation to 40
+// chars would collide two thread IDs sharing a 40-char prefix onto one sandbox, so
+// append a stable content hash when (and only when) the cleaned id exceeds the limit
+// — short ids are returned verbatim, keeping existing names churn-free.
+const sanitize = (s) => {
+    const clean = trimDashes(s.toLowerCase().replaceAll(/[^a-z0-9-]/g, "-")) || "x";
+    if (clean.length <= 40)
+        return clean;
+    const hash = createHash("sha256").update(s).digest("hex").slice(0, 8);
+    return `${trimDashes(clean.slice(0, 31))}-${hash}`;
+};
+const podName = (t) => `b4-sbx-${sanitize(t)}`;
+const pvcName = (t) => `b4-sbx-vol-${sanitize(t)}`;
+const netpolName = (t) => `b4-sbx-net-${sanitize(t)}`;
+const permissionLabel = (permission) => `${permission.verb} ${permission.apiGroup || "core"}/${permission.resource}${permission.subresource === undefined ? "" : `/${permission.subresource}`}`;
+export function resolveSecurity(policy) {
+    const sec = policy.security ?? {};
+    const dropCaps = sec.dropAllCapabilities ?? true;
+    const noNewPriv = sec.noNewPrivileges ?? true;
+    const readOnly = sec.readOnlyRootFilesystem ?? true;
+    const user = sec.runAsNonRoot === false
+        ? undefined
+        : // `typeof null === "object"`, so guard against it explicitly — a raw-parsed
+            // config could carry null (the TS type excludes it); fail SAFE to the
+            // hardened non-root default rather than silently running as the image's root.
+            typeof sec.runAsNonRoot === "object" && sec.runAsNonRoot !== null
+                ? sec.runAsNonRoot
+                : { uid: 1000, gid: 1000 };
+    const podSecurityContext = {
+        seccompProfile: { type: "RuntimeDefault" },
+        ...(user
+            ? {
+                runAsNonRoot: true,
+                runAsUser: user.uid,
+                runAsGroup: user.gid,
+                fsGroup: user.gid,
+                fsGroupChangePolicy: "OnRootMismatch",
+            }
+            : {}),
+    };
+    const containerSecurityContext = {
+        ...(noNewPriv ? { allowPrivilegeEscalation: false } : {}),
+        ...(readOnly ? { readOnlyRootFilesystem: true } : {}),
+        ...(dropCaps ? { capabilities: { drop: ["ALL"] } } : {}),
+    };
+    return { podSecurityContext, containerSecurityContext, readOnly, user };
+}
+/** Kubernetes SandboxProvider. Per thread: a keeper Pod `b4-sbx-<t>` (sleep
+ * infinity) + a PVC `b4-sbx-vol-<t>` at /workspace. acquire = create-or-reattach;
+ * release deletes the Pod (keeps the PVC); destroy deletes both. Hardening maps to
+ * SecurityContext; fsGroup chowns the PVC (no chown-init); the pod mounts no SA token. */
+export function kubernetesSandbox(opts) {
+    const ns = opts.namespace ?? "b4-sandboxes";
+    const startupTimeoutMs = opts.startupTimeoutMs ?? 60_000;
+    const client = opts.client ?? createDefaultKubeClient();
+    const ensurePod = async (threadId, policy, signal) => {
+        const name = podName(threadId);
+        const labels = { "app.kubernetes.io/managed-by": "b4", "b4.run/thread": sanitize(threadId) };
+        await client.createNamespacedPvcIfAbsent(ns, {
+            name: pvcName(threadId),
+            labels,
+            storageGi: policy.resources?.diskGb ?? 1,
+            ...(opts.storageClass ? { storageClass: opts.storageClass } : {}),
+        });
+        const phase = await client.readNamespacedPodPhase(ns, name);
+        if (phase === "Running") {
+            // Already running: fall through to the netpol block below, no recreate.
+        }
+        else if (phase === "Pending") {
+            // The keeper pod already exists but hasn't scheduled yet (slow scheduling,
+            // image pull, PVC binding, or a reattach mid-startup). Recreating it 409s on
+            // a real cluster, so wait it out rather than issue a duplicate create.
+            await waitForRunning(client, ns, name, startupTimeoutMs, signal);
+        }
+        else {
+            if (phase === "Failed" || phase === "Succeeded" || phase === "Unknown") {
+                // A crashed/completed keeper: delete and wait for the name to free up. Real
+                // K8s deletion is async (the pod lingers Terminating holding its name), so
+                // recreating the same name immediately would 409.
+                await client.deleteNamespacedPod(ns, name);
+                await waitForGone(client, ns, name, startupTimeoutMs, signal);
+            }
+            const { podSecurityContext, containerSecurityContext, readOnly, user } = resolveSecurity(policy);
+            const res = policy.resources;
+            const limits = {
+                ...(res?.memoryMb ? { memory: `${res.memoryMb}Mi` } : {}),
+                ...(res?.cpus ? { cpu: String(res.cpus) } : {}),
+            };
+            const env = [
+                ...Object.entries(policy.env ?? {}).map(([name, value]) => ({ name, value })),
+                ...(user ? [{ name: "HOME", value: ROOT }] : []),
+            ];
+            const spec = {
+                name,
+                image: opts.image,
+                labels,
+                pvcName: pvcName(threadId),
+                env,
+                limits,
+                podSecurityContext,
+                containerSecurityContext,
+                readOnlyRootFilesystem: readOnly,
+                automountServiceAccountToken: false,
+            };
+            await client.createNamespacedPod(ns, spec);
+            await waitForRunning(client, ns, name, startupTimeoutMs, signal);
+        }
+        // Egress policy (best-effort — depends on a policy-capable CNI; preflight warns).
+        // SandboxPolicy["network"]: mode "deny" is default-closed (an optional `allowlist`
+        // carves out exceptions); mode "allow" is default-open (a `denylist` would carve
+        // out exceptions, but KubeNetworkPolicySpec doesn't model that yet — out of scope,
+        // matching Docker's bare-allow-is-open baseline).
+        const wantsPolicy = policy.network.mode === "deny";
+        if (wantsPolicy) {
+            await client.upsertNamespacedNetworkPolicy(ns, {
+                name: netpolName(threadId),
+                labels,
+                threadLabelValue: sanitize(threadId),
+                mode: policy.network.mode,
+                ...(policy.network.allowlist ? { allowlist: policy.network.allowlist } : {}),
+            });
+        }
+        return name;
+    };
+    return {
+        name: "kubernetes",
+        async acquire({ threadId, policy, signal }) {
+            const pod = await ensurePod(threadId, policy, signal);
+            return {
+                threadId,
+                filesystem: kubeFilesystem(client, ns, pod),
+                exec: kubeExec(client, ns, pod, policy.resources?.timeoutMs !== undefined
+                    ? { timeoutMs: policy.resources.timeoutMs }
+                    : {}),
+                workspaceRoot: ROOT,
+            };
+        },
+        async release(threadId) {
+            await client.deleteNamespacedNetworkPolicy(ns, netpolName(threadId)).catch(() => { });
+            await client
+                .deleteNamespacedPod(ns, podName(threadId), { gracePeriodSeconds: 0 })
+                .catch(() => { });
+        },
+        async destroy(threadId) {
+            await client.deleteNamespacedNetworkPolicy(ns, netpolName(threadId)).catch(() => { });
+            await client
+                .deleteNamespacedPod(ns, podName(threadId), { gracePeriodSeconds: 0 })
+                .catch(() => { });
+            await client.deleteNamespacedPvc(ns, pvcName(threadId)).catch(() => { });
+            await waitForPvcGone(client, ns, pvcName(threadId), 30_000);
+        },
+        async preflight() {
+            const warnings = [];
+            const denied = [];
+            const apiFailures = [];
+            const transportFailures = [];
+            const labels = REQUIRED_KUBE_PERMISSIONS.map(permissionLabel);
+            const reviews = await Promise.allSettled(REQUIRED_KUBE_PERMISSIONS.map((permission) => client.canI(ns, permission)));
+            for (const [index, review] of reviews.entries()) {
+                const label = labels[index];
+                if (label === undefined)
+                    continue;
+                if (review.status === "fulfilled") {
+                    if (!review.value)
+                        denied.push(label);
+                }
+                else if (review.reason instanceof KubeAuthorizationReviewError &&
+                    review.reason.kind === "api") {
+                    apiFailures.push(label);
+                }
+                else {
+                    transportFailures.push(label);
+                }
+            }
+            denied.sort();
+            apiFailures.sort();
+            transportFailures.sort();
+            const failureDetails = [
+                ...(transportFailures.length > 0
+                    ? [
+                        `Kubernetes API not reachable while reviewing permissions in namespace "${ns}": ${transportFailures.join(", ")}.`,
+                    ]
+                    : []),
+                ...(apiFailures.length > 0
+                    ? [
+                        `Kubernetes authorization review failed in namespace "${ns}": ${apiFailures.join(", ")}.`,
+                    ]
+                    : []),
+                ...(denied.length > 0
+                    ? [`Missing Kubernetes permissions in namespace "${ns}": ${denied.join(", ")}.`]
+                    : []),
+            ];
+            if (failureDetails.length > 0) {
+                return { ok: false, detail: failureDetails.join(" ") };
+            }
+            const enforced = await client.networkPolicyEnforced(ns).catch(() => "unknown");
+            if (enforced !== true) {
+                warnings.push(`NetworkPolicy enforcement could not be confirmed in namespace "${ns}" (no policy-capable CNI detected). network:deny/allow egress control is best-effort until a CNI like Calico/Cilium is installed.`);
+            }
+            return {
+                ok: true,
+                detail: `Kubernetes reachable; required permissions granted in "${ns}".`,
+                ...(warnings.length > 0 ? { warnings } : {}),
+            };
+        },
+    };
+}
+async function waitForRunning(client, ns, name, timeoutMs, signal) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        if (signal.aborted)
+            throw new Error(`Sandbox acquire aborted for pod "${name}".`);
+        const phase = await client.readNamespacedPodPhase(ns, name);
+        if (phase === "Running")
+            return;
+        if (phase === null) {
+            throw sandboxUnavailable(`Sandbox unavailable: pod "${name}" disappeared while starting. Run \`b4 check\`.`);
+        }
+        if (phase === "Failed" || phase === "Succeeded") {
+            // A SIGTERM'd `sleep infinity` exits 0 → Succeeded; treat it as a dead keeper
+            // rather than polling out the full timeout waiting for a Running it'll never reach.
+            throw sandboxUnavailable(`Sandbox unavailable: pod "${name}" entered ${phase}. Run \`b4 check\`.`);
+        }
+        if (Date.now() > deadline) {
+            throw sandboxUnavailable(`Sandbox unavailable: pod "${name}" not Running within ${timeoutMs}ms. Run \`b4 check\`.`);
+        }
+        await new Promise((r) => setTimeout(r, 250));
+    }
+}
+async function waitForGone(client, ns, name, timeoutMs, signal) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        if (signal.aborted) {
+            throw new Error(`Sandbox acquire aborted while awaiting pod "${name}" deletion.`);
+        }
+        if ((await client.readNamespacedPodPhase(ns, name)) === null)
+            return;
+        if (Date.now() > deadline) {
+            throw sandboxUnavailable(`Sandbox unavailable: pod "${name}" still terminating after ${timeoutMs}ms. Run \`b4 check\`.`);
+        }
+        await new Promise((r) => setTimeout(r, 250));
+    }
+}
+/** PVC deletion on a real cluster is async (pvc-protection finalizer + storage
+ * backend teardown), so destroy() polls until the PVC is actually gone before
+ * returning — otherwise an immediate re-acquire's createNamespacedPvcIfAbsent
+ * sees the still-existing (Terminating) PVC and rebinds the old data. Best-effort:
+ * destroy has no AbortSignal, so this is bounded by a plain time budget rather than
+ * a cancellation signal; giving up rather than throwing keeps cleanup non-fatal. */
+async function waitForPvcGone(client, ns, name, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        if (!(await client.pvcExists(ns, name).catch(() => false)))
+            return;
+        if (Date.now() > deadline)
+            return; // best-effort cleanup: give up rather than throw
+        await new Promise((r) => setTimeout(r, 250));
+    }
+}

package/dist/testing/conformance.d.ts

@@ -0,0 +1,13 @@
+import type { SandboxProvider } from "@b4run/workspace";
+export declare function runProviderConformanceCase<T>(provider: Pick<SandboxProvider, "destroy">, threadIds: readonly string[], body: () => T | Promise<T>): Promise<T>;
+/**
+ * The contract every SandboxProvider must satisfy. Reused by fakeSandbox (CI)
+ * and dockerSandbox (gated Docker lane) so the fake cannot drift from reality.
+ * Pass vitest's `describe` so the kit can group under any runner.
+ */
+export declare function runProviderConformance(opts: {
+    readonly name: string;
+    readonly makeProvider: () => SandboxProvider;
+    readonly describe: (name: string, fn: () => void) => void;
+}): void;
+//# sourceMappingURL=conformance.d.ts.map

package/dist/testing/conformance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conformance.d.ts","sourceRoot":"","sources":["../../src/testing/conformance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AAMvD,wBAAsB,0BAA0B,CAAC,CAAC,EAChD,QAAQ,EAAE,IAAI,CAAC,eAAe,EAAE,SAAS,CAAC,EAC1C,SAAS,EAAE,SAAS,MAAM,EAAE,EAC5B,IAAI,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GACzB,OAAO,CAAC,CAAC,CAAC,CA+BZ;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,YAAY,EAAE,MAAM,eAAe,CAAA;IAC5C,QAAQ,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,IAAI,KAAK,IAAI,CAAA;CAC1D,GAAG,IAAI,CAmDP"}

package/dist/testing/conformance.js

@@ -0,0 +1,75 @@
+import { expect, test } from "vitest";
+const ctx = (workspaceRoot) => ({ signal: new AbortController().signal, workspaceRoot });
+const policy = { network: { mode: "allow" } };
+export async function runProviderConformanceCase(provider, threadIds, body) {
+    let bodyResult;
+    let bodyFailure;
+    let bodyPassed = false;
+    try {
+        bodyResult = await body();
+        bodyPassed = true;
+    }
+    catch (error) {
+        bodyFailure = error;
+    }
+    const cleanupResults = await Promise.allSettled(threadIds.map((threadId) => Promise.resolve().then(() => provider.destroy(threadId))));
+    const cleanupFailures = cleanupResults.flatMap((result) => result.status === "rejected" ? [result.reason] : []);
+    if (!bodyPassed) {
+        if (cleanupFailures.length > 0) {
+            throw new AggregateError([bodyFailure, ...cleanupFailures], "SandboxProvider conformance body and cleanup failed");
+        }
+        throw bodyFailure;
+    }
+    if (cleanupFailures.length > 0) {
+        throw new AggregateError(cleanupFailures, "SandboxProvider conformance cleanup failed");
+    }
+    return bodyResult;
+}
+/**
+ * The contract every SandboxProvider must satisfy. Reused by fakeSandbox (CI)
+ * and dockerSandbox (gated Docker lane) so the fake cannot drift from reality.
+ * Pass vitest's `describe` so the kit can group under any runner.
+ */
+export function runProviderConformance(opts) {
+    opts.describe(`SandboxProvider conformance: ${opts.name}`, () => {
+        test("acquire is idempotent per thread and reattaches the workspace", async () => {
+            const p = opts.makeProvider();
+            await runProviderConformanceCase(p, ["t1"], async () => {
+                const a = await p.acquire({ threadId: "t1", policy, signal: ctx("/").signal });
+                await a.filesystem.writeFile(`${a.workspaceRoot}/x`, "1", ctx(a.workspaceRoot));
+                const b = await p.acquire({ threadId: "t1", policy, signal: ctx("/").signal });
+                expect(await b.filesystem.readFile(`${b.workspaceRoot}/x`, ctx(b.workspaceRoot))).toBe("1");
+            });
+        });
+        test("threads are isolated", async () => {
+            const p = opts.makeProvider();
+            await runProviderConformanceCase(p, ["a", "b"], async () => {
+                const a = await p.acquire({ threadId: "a", policy, signal: ctx("/").signal });
+                await a.filesystem.writeFile(`${a.workspaceRoot}/secret`, "s", ctx(a.workspaceRoot));
+                const b = await p.acquire({ threadId: "b", policy, signal: ctx("/").signal });
+                expect(await b.filesystem.listDir(b.workspaceRoot, ctx(b.workspaceRoot))).not.toContain("secret");
+            });
+        });
+        test("release keeps the volume, destroy clears it", async () => {
+            const p = opts.makeProvider();
+            await runProviderConformanceCase(p, ["t"], async () => {
+                const a = await p.acquire({ threadId: "t", policy, signal: ctx("/").signal });
+                await a.filesystem.writeFile(`${a.workspaceRoot}/keep`, "1", ctx(a.workspaceRoot));
+                await p.release("t");
+                const r = await p.acquire({ threadId: "t", policy, signal: ctx("/").signal });
+                expect(await r.filesystem.readFile(`${r.workspaceRoot}/keep`, ctx(r.workspaceRoot))).toBe("1");
+                await p.destroy("t");
+                const d = await p.acquire({ threadId: "t", policy, signal: ctx("/").signal });
+                expect(await d.filesystem.listDir(d.workspaceRoot, ctx(d.workspaceRoot))).not.toContain("keep");
+            });
+        });
+        test("exec returns a numeric exit code", async () => {
+            const p = opts.makeProvider();
+            await runProviderConformanceCase(p, ["t"], async () => {
+                const a = await p.acquire({ threadId: "t", policy, signal: ctx("/").signal });
+                const r = await a.exec.runCommand({ command: "true" }, ctx(a.workspaceRoot));
+                expect(typeof r.exitCode).toBe("number");
+            });
+        });
+    });
+}

package/dist/testing/fake-sandbox.d.ts

@@ -0,0 +1,16 @@
+import type { BackendContext, SandboxProvider } from "@b4run/workspace";
+type ExecFn = (args: {
+    readonly command: string;
+    readonly cwd?: string;
+    readonly env?: Readonly<Record<string, string>>;
+}, ctx: BackendContext) => Promise<{
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly exitCode: number;
+}>;
+/** In-memory SandboxProvider for unit + wiring tests. No Docker. */
+export declare function fakeSandbox(opts?: {
+    readonly exec?: ExecFn;
+}): SandboxProvider;
+export {};
+//# sourceMappingURL=fake-sandbox.d.ts.map

package/dist/testing/fake-sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fake-sandbox.d.ts","sourceRoot":"","sources":["../../src/testing/fake-sandbox.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EAId,eAAe,EAChB,MAAM,kBAAkB,CAAA;AAEzB,KAAK,MAAM,GAAG,CACZ,IAAI,EAAE;IACJ,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CAChD,EACD,GAAG,EAAE,cAAc,KAChB,OAAO,CAAC;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAAA;AAI7F,oEAAoE;AACpE,wBAAgB,WAAW,CAAC,IAAI,GAAE;IAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,eAAe,CA4DlF"}

package/dist/testing/fake-sandbox.js

@@ -0,0 +1,61 @@
+const ROOT = "/workspace";
+/** In-memory SandboxProvider for unit + wiring tests. No Docker. */
+export function fakeSandbox(opts = {}) {
+    const volumes = new Map();
+    const liveThreads = new Set();
+    const volumeFor = (threadId) => {
+        let v = volumes.get(threadId);
+        if (!v) {
+            v = new Map();
+            volumes.set(threadId, v);
+        }
+        return v;
+    };
+    const makeFilesystem = (vol) => ({
+        async readFile(path) {
+            const v = vol.get(path);
+            if (v === undefined)
+                throw new Error(`ENOENT: ${path}`);
+            return v;
+        },
+        async writeFile(path, content) {
+            vol.set(path, content);
+            return { bytesWritten: Buffer.byteLength(content) };
+        },
+        async listDir(path) {
+            const prefix = path.endsWith("/") ? path : `${path}/`;
+            const names = new Set();
+            for (const key of vol.keys()) {
+                if (key.startsWith(prefix)) {
+                    const part = key.slice(prefix.length).split("/")[0];
+                    if (part !== undefined)
+                        names.add(part);
+                }
+            }
+            return [...names].sort();
+        },
+        async realPath(path) {
+            return path;
+        },
+    });
+    const defaultExec = async () => ({ stdout: "", stderr: "", exitCode: 0 });
+    return {
+        name: "fake",
+        async acquire({ threadId }) {
+            liveThreads.add(threadId);
+            const vol = volumeFor(threadId);
+            const exec = { runCommand: (args, ctx) => (opts.exec ?? defaultExec)(args, ctx) };
+            return { threadId, filesystem: makeFilesystem(vol), exec, workspaceRoot: ROOT };
+        },
+        async release(threadId) {
+            liveThreads.delete(threadId);
+        },
+        async destroy(threadId) {
+            liveThreads.delete(threadId);
+            volumes.delete(threadId);
+        },
+        async preflight() {
+            return { ok: true };
+        },
+    };
+}

package/dist/testing/index.d.ts

@@ -0,0 +1,3 @@
+export { runProviderConformance } from "./conformance.js";
+export { fakeSandbox } from "./fake-sandbox.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/testing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAA;AACzD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA"}

package/dist/testing/index.js

@@ -0,0 +1,2 @@
+export { runProviderConformance } from "./conformance.js";
+export { fakeSandbox } from "./fake-sandbox.js";