@checkstack/backend-api 0.20.0 → 0.21.1

package/src/script-sandbox/env-guard.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, it } from "bun:test";
+import {
+  buildSubprocessEnv,
+  FORBIDDEN_ENV_KEYS,
+  isForbiddenEnvKey,
+  pickSafeEnv,
+  SAFE_ENV_VARS,
+} from "./env-guard";
+
+describe("pickSafeEnv", () => {
+  it("only forwards keys in the safe whitelist", () => {
+    process.env.TEST_LEAK_SECRET = "DO_NOT_LEAK";
+    process.env.PATH = process.env.PATH ?? "/usr/bin";
+    const env = pickSafeEnv();
+    delete process.env.TEST_LEAK_SECRET;
+
+    expect(env.TEST_LEAK_SECRET).toBeUndefined();
+    expect(env.PATH).toBeDefined();
+    for (const key of Object.keys(env)) {
+      expect(SAFE_ENV_VARS).toContain(key as (typeof SAFE_ENV_VARS)[number]);
+    }
+  });
+});
+
+describe("isForbiddenEnvKey", () => {
+  it("flags the exact-match denylist keys", () => {
+    for (const key of FORBIDDEN_ENV_KEYS) {
+      expect(isForbiddenEnvKey(key)).toBe(true);
+    }
+  });
+
+  it("flags BUN_CONFIG_* by prefix", () => {
+    expect(isForbiddenEnvKey("BUN_CONFIG_REGISTRY")).toBe(true);
+    expect(isForbiddenEnvKey("BUN_CONFIG_")).toBe(true);
+  });
+
+  it("does not flag ordinary keys", () => {
+    expect(isForbiddenEnvKey("PAYLOAD_ID")).toBe(false);
+    expect(isForbiddenEnvKey("API_TOKEN")).toBe(false);
+  });
+});
+
+describe("buildSubprocessEnv", () => {
+  const base = { PATH: "/safe/bin", HOME: "/home/u" };
+
+  it("drops forbidden override keys when the denylist is applied", () => {
+    const { env, dropped } = buildSubprocessEnv({
+      base,
+      overrides: {
+        LD_PRELOAD: "/evil.so",
+        NODE_OPTIONS: "--require /evil.js",
+        API_TOKEN: "ok",
+      },
+      applyDenylist: true,
+    });
+
+    expect(env.LD_PRELOAD).toBeUndefined();
+    expect(env.NODE_OPTIONS).toBeUndefined();
+    expect(env.API_TOKEN).toBe("ok");
+    // base survives
+    expect(env.PATH).toBe("/safe/bin");
+    expect(dropped.sort()).toEqual(["LD_PRELOAD", "NODE_OPTIONS"]);
+  });
+
+  it("a PATH override is dropped but the safe-base PATH is retained", () => {
+    const { env, dropped } = buildSubprocessEnv({
+      base,
+      overrides: { PATH: "/attacker/bin" },
+      applyDenylist: true,
+    });
+    expect(env.PATH).toBe("/safe/bin");
+    expect(dropped).toEqual(["PATH"]);
+  });
+
+  it("passes forbidden keys through when the denylist is NOT applied (back-compat)", () => {
+    const { env, dropped } = buildSubprocessEnv({
+      base,
+      overrides: { LD_PRELOAD: "/x.so", NODE_OPTIONS: "--y" },
+      applyDenylist: false,
+    });
+    expect(env.LD_PRELOAD).toBe("/x.so");
+    expect(env.NODE_OPTIONS).toBe("--y");
+    expect(dropped).toEqual([]);
+  });
+
+  it("merges overrides over base with override winning on non-forbidden keys", () => {
+    const { env } = buildSubprocessEnv({
+      base: { HOME: "/home/u", TZ: "UTC" },
+      overrides: { TZ: "Europe/Berlin", EXTRA: "1" },
+      applyDenylist: true,
+    });
+    expect(env.TZ).toBe("Europe/Berlin");
+    expect(env.HOME).toBe("/home/u");
+    expect(env.EXTRA).toBe("1");
+  });
+});
+
+describe("PATH override hardening", () => {
+  it("PATH is a forbidden caller-override key (curated base PATH survives)", () => {
+    expect((FORBIDDEN_ENV_KEYS as readonly string[]).includes("PATH")).toBe(
+      true,
+    );
+    expect(isForbiddenEnvKey("PATH")).toBe(true);
+  });
+});

package/src/script-sandbox/env-guard.ts

@@ -0,0 +1,129 @@
+/**
+ * Centralized environment hardening for the shared script runners.
+ *
+ * Two responsibilities:
+ *  1. The `SAFE_ENV_VARS` whitelist + `pickSafeEnv()` (moved here from the two
+ *     runners, which previously each had an identical copy). This is the
+ *     curated subset forwarded to user scripts so backend secrets never leak.
+ *  2. A forbidden-key DENYLIST applied to the merged env when the sandbox is
+ *     enabled. This closes the known env-injection escape: a caller/operator
+ *     supplying `LD_PRELOAD` / `NODE_OPTIONS` / `PATH`-override etc. could
+ *     otherwise subvert the child process. When the sandbox is disabled the
+ *     denylist is NOT applied, preserving the exact pre-hardening behavior.
+ */
+
+/**
+ * Vars passed through to the subprocess. We intentionally do NOT forward the
+ * satellite's full env so backend secrets (DB URLs, API tokens, signing keys)
+ * never reach user-authored scripts. PATH / HOME / LANG / ... are kept so
+ * `node:child_process`, `node:fs`, locale-sensitive APIs, and ordinary CLI
+ * tools behave normally.
+ */
+export const SAFE_ENV_VARS = [
+  "PATH",
+  "HOME",
+  "USER",
+  "LANG",
+  "LC_ALL",
+  "LC_CTYPE",
+  "TZ",
+  "TMPDIR",
+  "HOSTNAME",
+  "SHELL",
+] as const;
+
+/**
+ * Forbidden env keys dropped from the merged env when the sandbox is enabled.
+ *
+ * These either alter the dynamic loader (`LD_*` / `DYLD_*`), inject code into
+ * the Node/Bun runtime (`NODE_OPTIONS`), or repoint Bun's install/config
+ * behavior (`BUN_INSTALL`, `BUN_CONFIG_*`). A user/operator must not be able
+ * to set them; the legitimate safe vars (`PATH`, etc.) are still forwarded via
+ * `SAFE_ENV_VARS`, but a caller cannot OVERRIDE `PATH` to a malicious dir
+ * because `PATH` is on the denylist for caller-supplied overrides.
+ *
+ * `BUN_CONFIG_` is a prefix match (any key starting with it is dropped).
+ */
+export const FORBIDDEN_ENV_KEYS = [
+  "LD_PRELOAD",
+  "LD_LIBRARY_PATH",
+  "LD_AUDIT",
+  "DYLD_INSERT_LIBRARIES",
+  "DYLD_LIBRARY_PATH",
+  "NODE_OPTIONS",
+  "BUN_INSTALL",
+  // PATH is a safe-base var (the curated one is always forwarded), but a
+  // caller-supplied PATH OVERRIDE could repoint binary resolution at a
+  // malicious directory, so caller overrides of PATH are dropped (the
+  // curated base PATH survives). Closes the PATH-override escape (§1/§5.6).
+  "PATH",
+] as const;
+
+/** Key prefixes that are forbidden (any matching key is dropped). */
+export const FORBIDDEN_ENV_PREFIXES = ["BUN_CONFIG_"] as const;
+
+/**
+ * Build the curated safe-env base from the current process environment.
+ * Identical behavior to the per-runner copies this replaces.
+ */
+export function pickSafeEnv(): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const key of SAFE_ENV_VARS) {
+    const value = process.env[key];
+    if (value !== undefined) {
+      env[key] = value;
+    }
+  }
+  return env;
+}
+
+/** True when `key` is forbidden by the denylist (exact or prefix match). */
+export function isForbiddenEnvKey(key: string): boolean {
+  if ((FORBIDDEN_ENV_KEYS as readonly string[]).includes(key)) {
+    return true;
+  }
+  return FORBIDDEN_ENV_PREFIXES.some((prefix) => key.startsWith(prefix));
+}
+
+export interface FilterEnvResult {
+  /** The merged env with forbidden keys removed (when enabled). */
+  env: Record<string, string>;
+  /** Keys that were dropped by the denylist. Empty when none / disabled. */
+  dropped: string[];
+}
+
+/**
+ * Build the final subprocess env: the safe-env base overlaid with the
+ * caller-supplied `overrides`. When `applyDenylist` is true, any caller
+ * override whose key is on the forbidden denylist is dropped (the safe-env
+ * base value, if any, is retained — e.g. the real `PATH` survives, but a
+ * caller's attempt to REPLACE it does not).
+ *
+ * When `applyDenylist` is false the behavior is exactly the prior
+ * `{ ...pickSafeEnv(), ...overrides }` merge (back-compat for disabled
+ * sandbox / opted-out runs).
+ */
+export function buildSubprocessEnv({
+  base,
+  overrides,
+  applyDenylist,
+}: {
+  base: Record<string, string>;
+  overrides?: Record<string, string>;
+  applyDenylist: boolean;
+}): FilterEnvResult {
+  const env: Record<string, string> = { ...base };
+  const dropped: string[] = [];
+
+  if (overrides !== undefined) {
+    for (const [key, value] of Object.entries(overrides)) {
+      if (applyDenylist && isForbiddenEnvKey(key)) {
+        dropped.push(key);
+        continue;
+      }
+      env[key] = value;
+    }
+  }
+
+  return { env, dropped };
+}

package/src/script-sandbox/filesystem.test.ts

@@ -0,0 +1,437 @@
+import { describe, expect, it } from "bun:test";
+import type { SandboxCapabilities } from "./capabilities";
+import { buildFilesystemLayer } from "./filesystem";
+import { filesystemPolicySchema } from "./policy";
+
+const LINUX_BWRAP: SandboxCapabilities = {
+  platform: "linux",
+  euidIsRoot: false,
+  hasPrlimit: true,
+  rlimitNative: true,
+  wrapper: "bwrap",
+  userNamespaces: true,
+  userNsCreatable: true,
+  netNamespaces: true,
+  netEgressIface: null,
+  netEgressAddressing: null,
+  netEgressRootless: false,
+};
+
+const LINUX_NSJAIL: SandboxCapabilities = {
+  ...LINUX_BWRAP,
+  wrapper: "nsjail",
+  netEgressIface: "eth0",
+  netEgressAddressing: {
+    ip: "10.0.0.2",
+    netmask: "255.255.255.0",
+    gateway: "10.0.0.1",
+  },
+};
+
+const LINUX_NO_WRAPPER: SandboxCapabilities = {
+  ...LINUX_BWRAP,
+  wrapper: null,
+  netNamespaces: false,
+};
+
+const LINUX_FIREJAIL: SandboxCapabilities = {
+  ...LINUX_BWRAP,
+  wrapper: "firejail",
+};
+
+const LINUX_NO_USERNS: SandboxCapabilities = {
+  ...LINUX_BWRAP,
+  userNamespaces: false,
+  userNsCreatable: false,
+  netNamespaces: false,
+};
+
+const MACOS: SandboxCapabilities = {
+  platform: "darwin",
+  euidIsRoot: false,
+  hasPrlimit: false,
+  rlimitNative: false,
+  wrapper: null,
+  userNamespaces: false,
+  userNsCreatable: false,
+  netNamespaces: false,
+  netEgressIface: null,
+  netEgressAddressing: null,
+  netEgressRootless: false,
+};
+
+// All paths exist by default; tests override per-case.
+const allExist = () => true;
+
+function fsPolicy(input: unknown) {
+  return filesystemPolicySchema.parse(input);
+}
+
+describe("buildFilesystemLayer — off", () => {
+  it("returns off (no prelude) for mode=off regardless of host", () => {
+    const r = buildFilesystemLayer({
+      policy: fsPolicy({ mode: "off" }),
+      caps: MACOS,
+      inputs: {},
+      pathExists: allExist,
+    });
+    expect(r.kind).toBe("off");
+  });
+});
+
+describe("buildFilesystemLayer — bwrap scratch-only", () => {
+  const r = buildFilesystemLayer({
+    policy: fsPolicy({ mode: "scratch-only" }),
+    caps: LINUX_BWRAP,
+    inputs: { scratchDir: "/tmp/run-1" },
+    pathExists: allExist,
+  });
+
+  it("builds a bwrap prelude", () => {
+    expect(r.kind).toBe("enforced");
+    if (r.kind !== "enforced") throw new Error("expected enforced");
+    expect(r.prelude[0]).toBe("bwrap");
+    expect(r.prelude).toContain("--unshare-all");
+    // Network is a SEPARATE layer; FS isolation must keep host net.
+    expect(r.prelude).toContain("--share-net");
+  });
+
+  it("binds the scratch dir read-write and chdirs into it", () => {
+    if (r.kind !== "enforced") throw new Error("expected enforced");
+    const joined = r.prelude.join(" ");
+    expect(joined).toContain("--bind /tmp/run-1 /tmp/run-1");
+    expect(joined).toContain("--chdir /tmp/run-1");
+    expect(r.prelude[r.prelude.length - 1]).toBe("--");
+  });
+
+  it("ro-binds the base system but NOT node_modules under scratch-only", () => {
+    if (r.kind !== "enforced") throw new Error("expected enforced");
+    const joined = r.prelude.join(" ");
+    expect(joined).toContain("--ro-bind /usr /usr");
+    expect(joined).not.toContain("node_modules");
+  });
+});
+
+describe("buildFilesystemLayer — privilege drop carried by the wrapper", () => {
+  it("emits bwrap --uid/--gid when a drop target is supplied", () => {
+    const r = buildFilesystemLayer({
+      policy: fsPolicy({ mode: "scratch-only" }),
+      caps: LINUX_BWRAP,
+      inputs: { scratchDir: "/tmp/run-uid", dropUid: 65532, dropGid: 65532 },
+      pathExists: allExist,
+    });
+    if (r.kind !== "enforced") throw new Error("expected enforced");
+    const joined = r.prelude.join(" ");
+    expect(joined).toContain("--uid 65532");
+    expect(joined).toContain("--gid 65532");
+  });
+
+  it("emits nsjail --user/--group when a drop target is supplied", () => {
+    const r = buildFilesystemLayer({
+      policy: fsPolicy({ mode: "scratch-only" }),
+      caps: LINUX_NSJAIL,
+      inputs: { scratchDir: "/tmp/run-uid2", dropUid: 65532, dropGid: 65532 },
+      pathExists: allExist,
+    });
+    if (r.kind !== "enforced") throw new Error("expected enforced");
+    const joined = r.prelude.join(" ");
+    expect(joined).toContain("--user 65532");
+    expect(joined).toContain("--group 65532");
+  });
+
+  it("omits the uid drop when no target is supplied", () => {
+    const r = buildFilesystemLayer({
+      policy: fsPolicy({ mode: "scratch-only" }),
+      caps: LINUX_BWRAP,
+      inputs: { scratchDir: "/tmp/run-nouid" },
+      pathExists: allExist,
+    });
+    if (r.kind !== "enforced") throw new Error("expected enforced");
+    expect(r.prelude).not.toContain("--uid");
+  });
+});
+
+describe("buildFilesystemLayer — bwrap scratch-plus-ro", () => {
+  it("ro-binds the reconciled node_modules tree", () => {
+    const r = buildFilesystemLayer({
+      policy: fsPolicy({ mode: "scratch-plus-ro" }),
+      caps: LINUX_BWRAP,
+      inputs: {
+        scratchDir: "/tmp/run-2",
+        nodeModulesDir: "/store/current/node_modules",
+      },
+      pathExists: allExist,
+    });
+    expect(r.kind).toBe("enforced");
+    if (r.kind !== "enforced") throw new Error("expected enforced");
+    expect(r.prelude.join(" ")).toContain(
+      "--ro-bind /store/current/node_modules /store/current/node_modules",
+    );
+  });
+
+  it("skips the node_modules bind when the tree does not exist on disk", () => {
+    const r = buildFilesystemLayer({
+      policy: fsPolicy({ mode: "scratch-plus-ro" }),
+      caps: LINUX_BWRAP,
+      inputs: {
+        scratchDir: "/tmp/run-3",
+        nodeModulesDir: "/store/missing/node_modules",
+      },
+      pathExists: (p) => p !== "/store/missing/node_modules",
+    });
+    expect(r.kind).toBe("enforced");
+    if (r.kind !== "enforced") throw new Error("expected enforced");
+    expect(r.prelude.join(" ")).not.toContain("/store/missing/node_modules");
+  });
+
+  it("skips a base path that is absent on this distro (e.g. /lib64)", () => {
+    const r = buildFilesystemLayer({
+      policy: fsPolicy({ mode: "scratch-only" }),
+      caps: LINUX_BWRAP,
+      inputs: { scratchDir: "/tmp/run-4" },
+      pathExists: (p) => p !== "/lib64",
+    });
+    if (r.kind !== "enforced") throw new Error("expected enforced");
+    expect(r.prelude.join(" ")).not.toContain("--ro-bind /lib64");
+  });
+});
+
+describe("buildFilesystemLayer — interpreter bind (P2 fix)", () => {
+  it("ro-binds the realpath-resolved interpreter when outside the base paths", () => {
+    const r = buildFilesystemLayer({
+      policy: fsPolicy({ mode: "scratch-only" }),
+      caps: LINUX_BWRAP,
+      inputs: {
+        scratchDir: "/tmp/run-int",
+        interpreterPath: "/home/u/.bun/bin/bun",
+      },
+      pathExists: allExist,
+      realpath: (p) => p, // identity for the test
+    });
+    if (r.kind !== "enforced") throw new Error("expected enforced");
+    expect(r.prelude.join(" ")).toContain(
+      "--ro-bind /home/u/.bun/bin/bun /home/u/.bun/bin/bun",
+    );
+  });
+
+  it("does NOT double-bind an interpreter already under a base path", () => {
+    const r = buildFilesystemLayer({
+      policy: fsPolicy({ mode: "scratch-only" }),
+      caps: LINUX_BWRAP,
+      inputs: {
+        scratchDir: "/tmp/run-int2",
+        interpreterPath: "/usr/local/bin/bun",
+      },
+      pathExists: allExist,
+      realpath: (p) => p,
+    });
+    if (r.kind !== "enforced") throw new Error("expected enforced");
+    // /usr/local/bin/bun is under /usr (a RO base path) → no extra bind.
+    const joined = r.prelude.join(" ");
+    expect(joined).not.toContain("--ro-bind /usr/local/bin/bun");
+  });
+
+  it("nsjail ro-binds the interpreter too", () => {
+    const r = buildFilesystemLayer({
+      policy: fsPolicy({ mode: "scratch-only" }),
+      caps: LINUX_NSJAIL,
+      inputs: {
+        scratchDir: "/tmp/run-int3",
+        interpreterPath: "/opt/bun/bin/bun",
+      },
+      pathExists: allExist,
+      realpath: (p) => p,
+    });
+    if (r.kind !== "enforced") throw new Error("expected enforced");
+    expect(r.prelude.join(" ")).toContain(
+      "--bindmount_ro /opt/bun/bin/bun:/opt/bun/bin/bun",
+    );
+  });
+});
+
+describe("buildFilesystemLayer — network composition (Phase 3)", () => {
+  it("emits --unshare-net when the network decision is namespaced (bwrap)", () => {
+    const r = buildFilesystemLayer({
+      policy: fsPolicy({ mode: "scratch-only" }),
+      caps: LINUX_BWRAP,
+      inputs: { scratchDir: "/tmp/run-net1" },
+      network: { kind: "namespaced", mode: "deny" },
+      pathExists: allExist,
+    });
+    if (r.kind !== "enforced") throw new Error("expected enforced");
+    expect(r.prelude).toContain("--unshare-net");
+    expect(r.prelude).not.toContain("--share-net");
+  });
+
+  it("emits --share-net when the network decision keeps the host net", () => {
+    const r = buildFilesystemLayer({
+      policy: fsPolicy({ mode: "scratch-only" }),
+      caps: LINUX_BWRAP,
+      inputs: { scratchDir: "/tmp/run-net2" },
+      network: { kind: "host", metadataBlockUnenforceable: false },
+      pathExists: allExist,
+    });
+    if (r.kind !== "enforced") throw new Error("expected enforced");
+    expect(r.prelude).toContain("--share-net");
+  });
+
+  it("nsjail plumbs macvlan + installs the nftables ruleset for a namespaced allowlist", () => {
+    const r = buildFilesystemLayer({
+      policy: fsPolicy({ mode: "off" }),
+      caps: LINUX_NSJAIL,
+      inputs: {},
+      network: {
+        kind: "namespaced",
+        mode: "allowlist",
+        egressIface: "eth0",
+        egressAddressing: {
+          ip: "10.0.0.2",
+          netmask: "255.255.255.0",
+          gateway: "10.0.0.1",
+        },
+        nftRuleset: "table inet ...",
+      },
+      nftRulesetPath: "/tmp/egress.nft",
+      pathExists: allExist,
+    });
+    if (r.kind !== "enforced") throw new Error("expected enforced");
+    expect(r.prelude).toContain("--clone_newnet");
+    // Real uplink plumbed in so the allowed CIDR is reachable, not blackholed.
+    expect(r.prelude).toContain("--macvlan_iface");
+    expect(r.prelude).toContain("eth0");
+    // The endpoint must be ADDRESSED or the macvlan still blackholes (P3 NIT).
+    expect(r.prelude).toContain("--macvlan_vs_ip");
+    expect(r.prelude).toContain("10.0.0.2");
+    expect(r.prelude).toContain("--macvlan_vs_nm");
+    expect(r.prelude).toContain("255.255.255.0");
+    expect(r.prelude).toContain("--macvlan_vs_gw");
+    expect(r.prelude).toContain("10.0.0.1");
+    expect(r.prelude).toContain("--nftables_file");
+    expect(r.prelude).toContain("/tmp/egress.nft");
+    // FS off → host root bound so binaries still resolve.
+    expect(r.prelude.join(" ")).toContain("--bindmount /:/");
+  });
+
+  it("deny is routeless: clone_newnet but NO macvlan uplink, NO ruleset", () => {
+    const r = buildFilesystemLayer({
+      policy: fsPolicy({ mode: "off" }),
+      caps: LINUX_NSJAIL,
+      inputs: {},
+      network: { kind: "namespaced", mode: "deny" },
+      pathExists: allExist,
+    });
+    if (r.kind !== "enforced") throw new Error("expected enforced");
+    expect(r.prelude).toContain("--clone_newnet");
+    expect(r.prelude).not.toContain("--macvlan_iface");
+    expect(r.prelude).not.toContain("--nftables_file");
+  });
+
+  it("builds a network-only bwrap wrapper (FS off) binding the host root", () => {
+    const r = buildFilesystemLayer({
+      policy: fsPolicy({ mode: "off" }),
+      caps: LINUX_BWRAP,
+      inputs: {},
+      network: { kind: "namespaced", mode: "deny" },
+      pathExists: allExist,
+    });
+    if (r.kind !== "enforced") throw new Error("expected enforced");
+    expect(r.prelude.join(" ")).toContain("--bind / /");
+    expect(r.prelude).toContain("--unshare-net");
+  });
+
+  it("returns off when neither FS nor network needs a wrapper", () => {
+    const r = buildFilesystemLayer({
+      policy: fsPolicy({ mode: "off" }),
+      caps: LINUX_BWRAP,
+      inputs: {},
+      network: { kind: "host", metadataBlockUnenforceable: false },
+      pathExists: allExist,
+    });
+    expect(r.kind).toBe("off");
+  });
+});
+
+describe("buildFilesystemLayer — nsjail", () => {
+  it("builds an nsjail prelude with the equivalent bind set", () => {
+    const r = buildFilesystemLayer({
+      policy: fsPolicy({ mode: "scratch-plus-ro" }),
+      caps: LINUX_NSJAIL,
+      inputs: {
+        scratchDir: "/tmp/run-5",
+        nodeModulesDir: "/store/current/node_modules",
+      },
+      pathExists: allExist,
+    });
+    expect(r.kind).toBe("enforced");
+    if (r.kind !== "enforced") throw new Error("expected enforced");
+    expect(r.prelude[0]).toBe("nsjail");
+    const joined = r.prelude.join(" ");
+    expect(joined).toContain("--bindmount /tmp/run-5:/tmp/run-5");
+    expect(joined).toContain(
+      "--bindmount_ro /store/current/node_modules:/store/current/node_modules",
+    );
+    expect(joined).toContain("--cwd /tmp/run-5");
+  });
+});
+
+describe("buildFilesystemLayer — degrade paths", () => {
+  it("degrades on macOS (no Linux namespaces)", () => {
+    const r = buildFilesystemLayer({
+      policy: fsPolicy({ mode: "scratch-only" }),
+      caps: MACOS,
+      inputs: { scratchDir: "/tmp/x" },
+      pathExists: allExist,
+    });
+    expect(r.kind).toBe("degrade");
+    if (r.kind !== "degrade") throw new Error("expected degrade");
+    expect(r.reason).toContain("platform=darwin");
+  });
+
+  it("degrades when unprivileged user namespaces are disabled", () => {
+    const r = buildFilesystemLayer({
+      policy: fsPolicy({ mode: "scratch-only" }),
+      caps: LINUX_NO_USERNS,
+      inputs: { scratchDir: "/tmp/x" },
+      pathExists: allExist,
+    });
+    expect(r.kind).toBe("degrade");
+    if (r.kind !== "degrade") throw new Error("expected degrade");
+    expect(r.reason).toContain("user namespaces");
+  });
+
+  it("degrades when no namespace wrapper is on PATH", () => {
+    const r = buildFilesystemLayer({
+      policy: fsPolicy({ mode: "scratch-only" }),
+      caps: LINUX_NO_WRAPPER,
+      inputs: { scratchDir: "/tmp/x" },
+      pathExists: allExist,
+    });
+    expect(r.kind).toBe("degrade");
+    if (r.kind !== "degrade") throw new Error("expected degrade");
+    expect(r.reason).toContain("bwrap/nsjail");
+  });
+
+  it("degrades on a firejail-only host (profile model unsupported)", () => {
+    const r = buildFilesystemLayer({
+      policy: fsPolicy({ mode: "scratch-only" }),
+      caps: LINUX_FIREJAIL,
+      inputs: { scratchDir: "/tmp/x" },
+      pathExists: allExist,
+    });
+    expect(r.kind).toBe("degrade");
+    if (r.kind !== "degrade") throw new Error("expected degrade");
+    expect(r.reason).toContain("firejail");
+  });
+
+  it("degrades when the runner supplies no scratch dir", () => {
+    const r = buildFilesystemLayer({
+      policy: fsPolicy({ mode: "scratch-only" }),
+      caps: LINUX_BWRAP,
+      inputs: {},
+      pathExists: allExist,
+    });
+    expect(r.kind).toBe("degrade");
+    if (r.kind !== "degrade") throw new Error("expected degrade");
+    expect(r.reason).toContain("scratch dir");
+  });
+});