@checkstack/backend-api 0.19.0 → 0.21.0

package/src/script-sandbox/global-default.test.ts

@@ -0,0 +1,161 @@
+import { describe, expect, it } from "bun:test";
+import type { z } from "zod";
+import type { ConfigService } from "../config-service";
+import type { Migration } from "../config-versioning";
+import {
+  GLOBAL_SANDBOX_DEFAULT_CONFIG_ID,
+  readGlobalSandboxDefault,
+  writeGlobalSandboxDefault,
+} from "./global-default";
+import {
+  resolveDefaultSandboxProfile,
+  SANDBOX_UID_ENV,
+} from "./policy";
+
+/**
+ * In-memory ConfigService over a SHARED backing store, simulating the durable
+ * Postgres `plugin_configs` table. Two instances built over the SAME `store`
+ * stand in for two pods reading the one durable row — the scale-correctness
+ * guard (`.claude/rules/state-and-scale.md` Q2: same answer on every pod).
+ */
+function fakeConfigService(store: Map<string, unknown>): ConfigService {
+  return {
+    async set<T>(
+      configId: string,
+      _schema: z.ZodType<T>,
+      _version: number,
+      data: T,
+      _migrations?: Migration<unknown, unknown>[],
+    ): Promise<void> {
+      store.set(configId, data);
+    },
+    async get<T>(
+      configId: string,
+      _schema: z.ZodType<T>,
+      _version: number,
+      _migrations?: Migration<unknown, unknown>[],
+    ): Promise<T | undefined> {
+      return store.has(configId) ? (store.get(configId) as T) : undefined;
+    },
+    async getRedacted<T>(): Promise<Partial<T> | undefined> {
+      throw new Error("not used in these tests");
+    },
+    async delete(configId: string): Promise<void> {
+      store.delete(configId);
+    },
+    async list(): Promise<string[]> {
+      return [...store.keys()];
+    },
+  };
+}
+
+describe("readGlobalSandboxDefault", () => {
+  it("falls back to the shipped safe default when no row exists (on-by-default holds)", async () => {
+    delete process.env[SANDBOX_UID_ENV];
+    const configService = fakeConfigService(new Map());
+    const policy = await readGlobalSandboxDefault({ configService });
+    expect(policy).toEqual(resolveDefaultSandboxProfile());
+    expect(policy.enabled).toBe(true);
+    expect(policy.filesystem.mode).toBe("scratch-plus-ro");
+  });
+
+  it("returns the stored durable policy when present", async () => {
+    const store = new Map<string, unknown>();
+    const configService = fakeConfigService(store);
+    await writeGlobalSandboxDefault({
+      configService,
+      policy: { enabled: false },
+    });
+    const policy = await readGlobalSandboxDefault({ configService });
+    expect(policy.enabled).toBe(false);
+  });
+});
+
+describe("global default is shared, not pod-local (scale-correctness)", () => {
+  it("a write on one pod is visible identically on another pod", async () => {
+    // ONE shared backing store = the durable Postgres row both pods read.
+    const store = new Map<string, unknown>();
+    const podA = fakeConfigService(store);
+    const podB = fakeConfigService(store);
+
+    // Admin configures the global default via pod A.
+    const written = await writeGlobalSandboxDefault({
+      configService: podA,
+      policy: { network: { mode: "deny" }, resources: { cpuSeconds: 30 } },
+    });
+
+    // Pod B reads the SAME value (not a pod-local copy / default).
+    const onB = await readGlobalSandboxDefault({ configService: podB });
+    expect(onB).toEqual(written);
+    expect(onB.network.mode).toBe("deny");
+    expect(onB.resources.cpuSeconds).toBe(30);
+  });
+
+  it("stores under the well-known, stable config id", async () => {
+    const store = new Map<string, unknown>();
+    const configService = fakeConfigService(store);
+    await writeGlobalSandboxDefault({
+      configService,
+      policy: { enabled: false },
+    });
+    expect(store.has(GLOBAL_SANDBOX_DEFAULT_CONFIG_ID)).toBe(true);
+  });
+});
+
+describe("writeGlobalSandboxDefault", () => {
+  it("merges a partial input over the safe default before storing", async () => {
+    const store = new Map<string, unknown>();
+    const configService = fakeConfigService(store);
+    const resolved = await writeGlobalSandboxDefault({
+      configService,
+      policy: { network: { mode: "deny" } },
+    });
+    expect(resolved.enabled).toBe(true);
+    // An unspecified onUnavailable inherits the shipped safe default, which is
+    // now fail-closed.
+    expect(resolved.onUnavailable).toBe("fail");
+    expect(resolved.network.mode).toBe("deny");
+  });
+
+  it("a PARTIAL global write does NOT reset the unspecified layers (MINOR fix)", async () => {
+    const store = new Map<string, unknown>();
+    const configService = fakeConfigService(store);
+    // Admin loosens only memory; everything else must keep the safe default,
+    // NOT collapse to the bare zod field defaults (filesystem off, etc.).
+    const resolved = await writeGlobalSandboxDefault({
+      configService,
+      policy: { resources: { memoryBytes: 2 * 1024 * 1024 * 1024 } },
+    });
+    expect(resolved.resources.memoryBytes).toBe(2 * 1024 * 1024 * 1024);
+    // Unspecified layers preserved from the safe default profile:
+    expect(resolved.filesystem.mode).toBe("scratch-plus-ro");
+    expect(resolved.privilege.mode).toBe("drop-to-uid");
+    expect(resolved.network.denyLinkLocalAndMetadata).toBe(true);
+    // Other resource caps from the default profile are preserved too.
+    expect(resolved.resources.cpuSeconds).toBe(60);
+  });
+
+  it("a global { enabled: false } persists as a disable while keeping the rest", async () => {
+    const store = new Map<string, unknown>();
+    const configService = fakeConfigService(store);
+    const resolved = await writeGlobalSandboxDefault({
+      configService,
+      policy: { enabled: false },
+    });
+    expect(resolved.enabled).toBe(false);
+    // The merge keeps the safe default for the (now-inert) layers.
+    expect(resolved.filesystem.mode).toBe("scratch-plus-ro");
+  });
+
+  it("rejects an invalid policy (bad bounds) instead of persisting garbage", async () => {
+    const store = new Map<string, unknown>();
+    const configService = fakeConfigService(store);
+    await expect(
+      writeGlobalSandboxDefault({
+        configService,
+        policy: { resources: { cpuSeconds: -1 } },
+      }),
+    ).rejects.toThrow();
+    expect(store.size).toBe(0);
+  });
+});

package/src/script-sandbox/global-default.ts

@@ -0,0 +1,100 @@
+import type { ConfigService } from "../config-service";
+import {
+  mergeSandboxPolicy,
+  resolveDefaultSandboxProfile,
+  sandboxPolicySchema,
+  type SandboxPolicy,
+  type SandboxPolicyInput,
+} from "./policy";
+
+/**
+ * Durable, cluster-wide global default sandbox policy (plan §5.8).
+ *
+ * State-and-scale (`.claude/rules/state-and-scale.md`):
+ *  1. WHERE IT LIVES: the existing plugin-scoped {@link ConfigService}, which
+ *     persists to the shared Postgres `plugin_configs` table. NOT pod-local,
+ *     NOT an env var that could differ per pod.
+ *  2. SAME ANSWER ON EVERY POD: every pod/satellite reads the same row, so the
+ *     resolved global default is identical everywhere it is read. The dedicated
+ *     low-priv UID/GID seed (from `CHECKSTACK_SANDBOX_UID/GID`) is genuinely
+ *     per-host infrastructure (a host without that user cannot drop to it), and
+ *     that divergence is surfaced per run in the EffectiveSandbox report — it
+ *     is not the queryable global policy.
+ *  3. NOT DUPLICATED: this is the single writer of the logical "global default
+ *     sandbox policy"; the per-item `sandbox` config field is a separate,
+ *     narrower override applied ON TOP of this value.
+ *
+ * The shipped, code-level safe default ({@link resolveDefaultSandboxProfile})
+ * is the value used when no row exists yet (a fresh install, or before an
+ * operator ever touches the setting), so on-by-default holds even with an empty
+ * settings table. An operator opts out globally by storing `{ enabled: false }`
+ * (or any partial override) here.
+ */
+
+/**
+ * Config key under which the global default sandbox policy is stored. Scoped to
+ * the writing plugin by {@link ConfigService}, so each script plugin keeps its
+ * own row; the read-side {@link readGlobalSandboxDefault} resolves the same key.
+ */
+export const GLOBAL_SANDBOX_DEFAULT_CONFIG_ID = "script-sandbox:global-default";
+
+/** Schema version for the stored policy (bump + add a migration on change). */
+export const GLOBAL_SANDBOX_DEFAULT_VERSION = 1;
+
+/**
+ * Read the durable global default sandbox policy, falling back to the shipped
+ * safe default when nothing has been stored.
+ *
+ * Returns a fully-resolved {@link SandboxPolicy} suitable to pass straight to a
+ * runner's `sandbox` option (the runner merges it over its own default profile
+ * idempotently) or to merge a per-item override on top of via
+ * `mergeSandboxPolicy`.
+ */
+export async function readGlobalSandboxDefault({
+  configService,
+}: {
+  configService: ConfigService;
+}): Promise<SandboxPolicy> {
+  const stored = await configService.get<SandboxPolicy>(
+    GLOBAL_SANDBOX_DEFAULT_CONFIG_ID,
+    sandboxPolicySchema,
+    GLOBAL_SANDBOX_DEFAULT_VERSION,
+  );
+  // No row yet → the shipped safe default (with the dedicated UID/GID seeded
+  // from this host's env). On-by-default holds even on an empty settings table.
+  return stored ?? resolveDefaultSandboxProfile();
+}
+
+/**
+ * Persist the global default sandbox policy.
+ *
+ * The input is treated as a PARTIAL override merged over the shipped safe
+ * default profile ({@link resolveDefaultSandboxProfile} via
+ * {@link mergeSandboxPolicy}), so an admin loosening a single layer (e.g. just
+ * `{ resources: { memoryBytes } }`) does NOT silently reset the unspecified
+ * layers (filesystem → off, privilege → inherit, ...) cluster-wide. Only the
+ * fields the admin actually set change; everything else keeps the safe default.
+ * Use `{ enabled: false }` to globally opt out.
+ */
+export async function writeGlobalSandboxDefault({
+  configService,
+  policy,
+}: {
+  configService: ConfigService;
+  policy: SandboxPolicyInput;
+}): Promise<SandboxPolicy> {
+  // Validate the partial first (bounds + .strict), then overlay only the
+  // provided fields onto the safe default so unspecified layers are preserved.
+  sandboxPolicySchema.parse(policy);
+  const resolved = mergeSandboxPolicy({
+    base: resolveDefaultSandboxProfile(),
+    override: policy,
+  });
+  await configService.set<SandboxPolicy>(
+    GLOBAL_SANDBOX_DEFAULT_CONFIG_ID,
+    sandboxPolicySchema,
+    GLOBAL_SANDBOX_DEFAULT_VERSION,
+    resolved,
+  );
+  return resolved;
+}

package/src/script-sandbox/index.ts

@@ -0,0 +1,14 @@
+export * from "./policy";
+export * from "./report";
+export * from "./env-guard";
+export * from "./capabilities";
+export * from "./wrapper";
+export * from "./output-truncation";
+export * from "./capped-output";
+export * from "./filesystem";
+export * from "./network";
+export * from "./rootless-egress";
+export * from "./provider";
+export * from "./global-default";
+export * from "./observability";
+export * from "./readiness";

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

@@ -0,0 +1,356 @@
+import { describe, expect, it } from "bun:test";
+import type { SandboxCapabilities } from "./capabilities";
+import {
+  ALWAYS_BLOCKED_CIDRS,
+  buildEgressNftRules,
+  buildNetworkLayer,
+} from "./network";
+import { networkPolicySchema } from "./policy";
+
+// nsjail host that CAN plumb real egress (root + a usable uplink iface): the
+// ONLY configuration where allowlist / the metadata block are deliverable.
+const LINUX_NSJAIL_PLUMBED: SandboxCapabilities = {
+  platform: "linux",
+  euidIsRoot: true,
+  hasPrlimit: true,
+  rlimitNative: true,
+  wrapper: "nsjail",
+  userNamespaces: true,
+  userNsCreatable: true,
+  netNamespaces: true,
+  netEgressIface: "eth0",
+  netEgressAddressing: {
+    ip: "10.0.0.2",
+    netmask: "255.255.255.0",
+    gateway: "10.0.0.1",
+  },
+  netEgressRootless: false,
+};
+
+// nsjail present, namespace creatable, but egress CANNOT be plumbed (non-root /
+// no uplink): deny still works (routeless), allowlist + metadata block degrade.
+const LINUX_NSJAIL_NO_PLUMB: SandboxCapabilities = {
+  ...LINUX_NSJAIL_PLUMBED,
+  euidIsRoot: false,
+  netEgressIface: null,
+  netEgressAddressing: null,
+};
+
+// nsjail + root + uplink, but NO static macvlan addressing configured: the
+// macvlan would be routeless, so allowlist / metadata block degrade-and-surface.
+const LINUX_NSJAIL_NO_ADDRESSING: SandboxCapabilities = {
+  ...LINUX_NSJAIL_PLUMBED,
+  netEgressAddressing: null,
+};
+
+const LINUX_BWRAP: SandboxCapabilities = {
+  ...LINUX_NSJAIL_PLUMBED,
+  wrapper: "bwrap",
+  netEgressIface: null, // macvlan egress plumbing is nsjail-only
+  netEgressAddressing: null,
+};
+
+// bwrap host with the ROOTLESS slirp4netns path available (no privileged
+// macvlan): the common rootless-container case. allowlist + metadata block are
+// deliverable here without root / an uplink / operator addressing.
+const LINUX_BWRAP_ROOTLESS: SandboxCapabilities = {
+  ...LINUX_BWRAP,
+  netEgressRootless: true,
+};
+
+// A host where BOTH paths are present: macvlan (nsjail+root+uplink+addressing)
+// AND rootless. Used to assert the macvlan path is PREFERRED.
+const LINUX_BOTH_PATHS: SandboxCapabilities = {
+  ...LINUX_NSJAIL_PLUMBED,
+  netEgressRootless: true,
+};
+
+const LINUX_NO_NETNS: SandboxCapabilities = {
+  ...LINUX_NSJAIL_PLUMBED,
+  wrapper: null,
+  netNamespaces: false,
+  netEgressIface: null,
+  netEgressAddressing: null,
+};
+
+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,
+};
+
+function net(input: unknown) {
+  return networkPolicySchema.parse(input);
+}
+
+describe("buildEgressNftRules — always-on metadata/link-local block", () => {
+  it("drops the metadata/link-local ranges in allowlist mode", () => {
+    const rules = buildEgressNftRules({
+      mode: "allowlist",
+      allow: ["10.0.0.0/8"],
+      denyMetadata: true,
+    });
+    // The block is emitted BEFORE any accept so it cannot be re-opened.
+    expect(rules).toContain("169.254.0.0/16");
+    expect(rules).toContain("fe80::/10");
+    expect(rules).toContain("fc00::/7");
+    const dropIdx = rules.indexOf("169.254.0.0/16");
+    const allowIdx = rules.indexOf("10.0.0.0/8");
+    expect(dropIdx).toBeLessThan(allowIdx);
+    // Allowed CIDR + a final default drop.
+    expect(rules).toContain("ip daddr { 10.0.0.0/8 } accept");
+    expect(rules.trimEnd().split("\n").some((l) => l.trim() === "drop")).toBe(
+      true,
+    );
+  });
+
+  it("separates IPv4 and IPv6 allow entries onto ip / ip6 rules", () => {
+    const rules = buildEgressNftRules({
+      mode: "allowlist",
+      allow: ["10.0.0.0/8", "2001:db8::/32"],
+      denyMetadata: true,
+    });
+    expect(rules).toContain("ip daddr { 10.0.0.0/8 } accept");
+    expect(rules).toContain("ip6 daddr { 2001:db8::/32 } accept");
+  });
+
+  it("metadata-only mode default-accepts but still drops the blocked ranges", () => {
+    const rules = buildEgressNftRules({
+      mode: "metadata-only",
+      allow: [],
+      denyMetadata: true,
+    });
+    expect(rules).toContain("policy accept");
+    expect(rules).toContain("169.254.0.0/16");
+    // No final default drop — everything except the blocked ranges is allowed.
+    expect(rules.trimEnd().split("\n").some((l) => l.trim() === "drop")).toBe(
+      false,
+    );
+  });
+
+  it("the always-blocked set covers IPv4 link-local + IPv6 link/unique-local", () => {
+    expect(ALWAYS_BLOCKED_CIDRS).toContain("169.254.0.0/16");
+    expect(ALWAYS_BLOCKED_CIDRS).toContain("fe80::/10");
+    expect(ALWAYS_BLOCKED_CIDRS).toContain("fc00::/7");
+  });
+});
+
+describe("buildNetworkLayer — deny (routeless netns is the goal)", () => {
+  it("takes a fresh routeless namespace, no ruleset, no iface (bwrap)", () => {
+    const d = buildNetworkLayer({ policy: net({ mode: "deny" }), caps: LINUX_BWRAP });
+    expect(d.kind).toBe("namespaced");
+    if (d.kind !== "namespaced") throw new Error("expected namespaced");
+    expect(d.mode).toBe("deny");
+    expect(d.nftRuleset).toBeUndefined();
+    expect(d.egressIface).toBeUndefined(); // routeless: no uplink
+  });
+
+  it("deny works on an nsjail host that cannot plumb egress (still routeless)", () => {
+    const d = buildNetworkLayer({
+      policy: net({ mode: "deny" }),
+      caps: LINUX_NSJAIL_NO_PLUMB,
+    });
+    expect(d.kind).toBe("namespaced");
+    if (d.kind !== "namespaced") throw new Error("expected namespaced");
+    expect(d.mode).toBe("deny");
+    expect(d.egressIface).toBeUndefined();
+  });
+
+  it("degrades deny on a host without net namespaces", () => {
+    const d = buildNetworkLayer({
+      policy: net({ mode: "deny" }),
+      caps: LINUX_NO_NETNS,
+    });
+    expect(d.kind).toBe("degrade");
+  });
+
+  it("degrades deny on macOS", () => {
+    const d = buildNetworkLayer({ policy: net({ mode: "deny" }), caps: MACOS });
+    expect(d.kind).toBe("degrade");
+    if (d.kind !== "degrade") throw new Error("expected degrade");
+    expect(d.reason).toContain("platform=darwin");
+  });
+});
+
+describe("buildNetworkLayer — EMPTY allowlist == deny (routeless, no plumbing)", () => {
+  it("resolves the secure-default empty allowlist to a routeless deny netns", () => {
+    // The shipped secure default: `allowlist` with an EMPTY allow list = no
+    // egress at all. It must take the routeless deny path (loopback only), which
+    // needs NO macvlan/slirp4netns plumbing and NO nftables ruleset, so it
+    // enforces on any netns-capable host - even where in-namespace nft is denied.
+    for (const caps of [LINUX_BWRAP, LINUX_BWRAP_ROOTLESS, LINUX_NSJAIL_PLUMBED]) {
+      const d = buildNetworkLayer({
+        policy: net({ mode: "allowlist", allow: [] }),
+        caps,
+      });
+      expect(d.kind).toBe("namespaced");
+      if (d.kind !== "namespaced") throw new Error("expected namespaced");
+      expect(d.mode).toBe("deny");
+      expect(d.nftRuleset).toBeUndefined();
+      expect(d.egressIface).toBeUndefined();
+      expect(d.egressPath).toBeUndefined();
+    }
+  });
+
+  it("still degrades an empty allowlist where no netns wrapper exists", () => {
+    const d = buildNetworkLayer({
+      policy: net({ mode: "allowlist", allow: [] }),
+      caps: MACOS,
+    });
+    expect(d.kind).toBe("degrade");
+  });
+});
+
+describe("buildNetworkLayer — allowlist (needs plumbed egress, never blackhole)", () => {
+  it("plumbs a macvlan uplink + nftables ruleset when egress is plumbable", () => {
+    const d = buildNetworkLayer({
+      policy: net({ mode: "allowlist", allow: ["10.0.0.0/8"] }),
+      caps: LINUX_NSJAIL_PLUMBED,
+    });
+    expect(d.kind).toBe("namespaced");
+    if (d.kind !== "namespaced") throw new Error("expected namespaced");
+    expect(d.mode).toBe("allowlist");
+    expect(d.egressIface).toBe("eth0"); // real uplink → allowed CIDR reachable
+    expect(d.egressAddressing).toEqual({
+      ip: "10.0.0.2",
+      netmask: "255.255.255.0",
+      gateway: "10.0.0.1",
+    });
+    expect(d.nftRuleset).toContain("10.0.0.0/8");
+    expect(d.nftRuleset).toContain("169.254.0.0/16"); // metadata still blocked
+  });
+
+  it("degrades (surfaced) when the macvlan endpoint has no static addressing", () => {
+    // The iface is plumbable but no CHECKSTACK_SANDBOX_MACVLAN_* addressing is
+    // configured → an unaddressed macvlan has no route, so the allowlist would
+    // blackhole. Must degrade-and-surface, never blackhole.
+    const d = buildNetworkLayer({
+      policy: net({ mode: "allowlist", allow: ["10.0.0.0/8"] }),
+      caps: LINUX_NSJAIL_NO_ADDRESSING,
+    });
+    expect(d.kind).toBe("degrade");
+    if (d.kind !== "degrade") throw new Error("expected degrade");
+    // Neither path is deliverable (macvlan lacks addressing; not rootless) →
+    // the unified degrade reason names the addressing requirement + blackhole.
+    expect(d.reason).toContain("macvlan");
+    expect(d.reason).toContain("addressing");
+    expect(d.reason).toContain("blackhole");
+  });
+
+  it("degrades (surfaced) when egress cannot be plumbed — NOT a blackhole", () => {
+    const d = buildNetworkLayer({
+      policy: net({ mode: "allowlist", allow: ["10.0.0.0/8"] }),
+      caps: LINUX_NSJAIL_NO_PLUMB,
+    });
+    expect(d.kind).toBe("degrade");
+    if (d.kind !== "degrade") throw new Error("expected degrade");
+    expect(d.reason).toContain("blackhole");
+    expect(d.reason).toContain("unrestricted");
+  });
+
+  it("degrades on bwrap with NEITHER macvlan NOR rootless egress available", () => {
+    const d = buildNetworkLayer({
+      policy: net({ mode: "allowlist", allow: ["10.0.0.0/8"] }),
+      caps: LINUX_BWRAP,
+    });
+    expect(d.kind).toBe("degrade");
+    if (d.kind !== "degrade") throw new Error("expected degrade");
+    expect(d.reason).toContain("rootless");
+    expect(d.reason).toContain("slirp4netns");
+  });
+
+  it("plumbs the ROOTLESS slirp4netns path on a rootless bwrap host", () => {
+    const d = buildNetworkLayer({
+      policy: net({ mode: "allowlist", allow: ["10.0.0.0/8"] }),
+      caps: LINUX_BWRAP_ROOTLESS,
+    });
+    expect(d.kind).toBe("namespaced");
+    if (d.kind !== "namespaced") throw new Error("expected namespaced");
+    expect(d.mode).toBe("allowlist");
+    expect(d.egressPath).toBe("rootless");
+    // No macvlan iface / addressing on the rootless path (slirp4netns supplies
+    // a deterministic userspace stack).
+    expect(d.egressIface).toBeUndefined();
+    expect(d.egressAddressing).toBeUndefined();
+    // The SAME nftables filter applies (allowed CIDR + metadata block).
+    expect(d.nftRuleset).toContain("10.0.0.0/8");
+    expect(d.nftRuleset).toContain("169.254.0.0/16");
+  });
+
+  it("PREFERS the privileged macvlan path when BOTH are available", () => {
+    const d = buildNetworkLayer({
+      policy: net({ mode: "allowlist", allow: ["10.0.0.0/8"] }),
+      caps: LINUX_BOTH_PATHS,
+    });
+    expect(d.kind).toBe("namespaced");
+    if (d.kind !== "namespaced") throw new Error("expected namespaced");
+    expect(d.egressPath).toBe("macvlan");
+    expect(d.egressIface).toBe("eth0");
+    expect(d.egressAddressing).not.toBeUndefined();
+  });
+});
+
+describe("buildNetworkLayer — unrestricted + metadata block (never sever egress)", () => {
+  it("enforces the block in a PLUMBED namespace when egress is available", () => {
+    const d = buildNetworkLayer({
+      policy: net({ mode: "unrestricted", denyLinkLocalAndMetadata: true }),
+      caps: LINUX_NSJAIL_PLUMBED,
+    });
+    expect(d.kind).toBe("namespaced");
+    if (d.kind !== "namespaced") throw new Error("expected namespaced");
+    expect(d.egressIface).toBe("eth0"); // ordinary traffic still flows
+    expect(d.nftRuleset).toContain("169.254.0.0/16");
+  });
+
+  it("does NOT engage a routeless netns when egress is unplumbable (nsjail no-plumb)", () => {
+    // BLOCKER guard: a routeless netns here would sever ALL egress. Must keep
+    // host net and surface the block as unenforceable, never blackhole.
+    const d = buildNetworkLayer({
+      policy: net({ mode: "unrestricted", denyLinkLocalAndMetadata: true }),
+      caps: LINUX_NSJAIL_NO_PLUMB,
+    });
+    expect(d.kind).toBe("host");
+    if (d.kind !== "host") throw new Error("expected host");
+    expect(d.metadataBlockUnenforceable).toBe(true);
+  });
+
+  it("reports the metadata block unenforceable on bwrap with no egress path", () => {
+    const d = buildNetworkLayer({
+      policy: net({ mode: "unrestricted", denyLinkLocalAndMetadata: true }),
+      caps: LINUX_BWRAP,
+    });
+    expect(d.kind).toBe("host");
+    if (d.kind !== "host") throw new Error("expected host");
+    expect(d.metadataBlockUnenforceable).toBe(true);
+  });
+
+  it("enforces the metadata block via the ROOTLESS path when available", () => {
+    const d = buildNetworkLayer({
+      policy: net({ mode: "unrestricted", denyLinkLocalAndMetadata: true }),
+      caps: LINUX_BWRAP_ROOTLESS,
+    });
+    expect(d.kind).toBe("namespaced");
+    if (d.kind !== "namespaced") throw new Error("expected namespaced");
+    expect(d.egressPath).toBe("rootless");
+    expect(d.egressIface).toBeUndefined(); // ordinary egress still flows via slirp4netns
+    expect(d.nftRuleset).toContain("169.254.0.0/16");
+  });
+
+  it("stays on the host net with nothing to do when the block is disabled", () => {
+    const d = buildNetworkLayer({
+      policy: net({ mode: "unrestricted", denyLinkLocalAndMetadata: false }),
+      caps: LINUX_NSJAIL_PLUMBED,
+    });
+    expect(d.kind).toBe("host");
+    if (d.kind !== "host") throw new Error("expected host");
+    expect(d.metadataBlockUnenforceable).toBe(false);
+  });
+});