@specific.dev/spectest 0.90.2 → 0.91.0

package/dist/harness/sticky-kubernetes.js

@@ -0,0 +1,163 @@
+/** Kubernetes owns a separate containerd store; Docker/BuildKit GC cannot
+ * collect it. Maintenance runs only on the isolated publication clone. */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readFile, readdir, rename, writeFile } from "node:fs/promises";
+import { STICKY_ROOT } from "./sticky-paths.js";
+const STORE_TARGET = "/var/lib/rancher/k3s/agent/containerd";
+const SOCKET = "/run/spectest-cache.sock";
+const ROOT = `${STICKY_ROOT}/kubernetes`;
+const IMAGE_ID = /^sha256:[a-f0-9]{64}$/;
+const SERVICE_NAME = /^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/;
+export function stickyKubernetesDirectory(service, version) {
+    // Version changes must not open old metadata with a different containerd.
+    const layout = createHash("sha256").update(`overlayfs-v1:${version}`).digest("hex").slice(0, 16);
+    return `${ROOT}/${service}/${layout}`;
+}
+const runCommand = async (program, args, timeout = 30_000) => (await promisify(execFile)(program, args, { timeout })).stdout.trim();
+export async function registerStickyKubernetesStore(service, version, run = runCommand) {
+    if (!SERVICE_NAME.test(service))
+        throw new Error(`invalid Kubernetes cache service name: ${service}`);
+    // Respect custom Dockerfile overrides of the component's image.
+    const image = (await run("docker", ["inspect", "--format", "{{.Image}}", service])).trim();
+    if (!IMAGE_ID.test(image))
+        throw new Error(`cannot identify Kubernetes runtime image for ${service}`);
+    const directory = stickyKubernetesDirectory(service, version);
+    await mkdir(directory, { recursive: true });
+    const temporary = `${directory}/store.${randomUUID()}.tmp`;
+    await writeFile(temporary, JSON.stringify({ schema: 1, image, updatedAt: Date.now() }));
+    await rename(temporary, `${directory}/store.json`);
+}
+/** Standalone containerd never starts CRI/kubelet or any inherited workload.
+ * Native API deletion preserves content and committed image snapshots while
+ * releasing sandbox, container, lease and writable snapshot references. */
+export const KUBERNETES_CACHE_MAINTENANCE_SH = `set -eu
+exec 2>&1
+cat > /run/cache.toml <<'CONFIG'
+version = 2
+disabled_plugins = ["io.containerd.grpc.v1.cri", "io.containerd.cri.v1.runtime", "io.containerd.cri.v1.images"]
+CONFIG
+containerd --config /run/cache.toml --root ${STORE_TARGET} --state /run/cache-state --address ${SOCKET} > /run/cache.log 2>&1 &
+pid=$!
+stop() { kill "$pid"; wait "$pid"; }
+trap 'stop; exit 0' TERM INT
+trap 'kill "$pid" 2>/dev/null || true' EXIT
+c() { ctr --address ${SOCKET} --namespace k8s.io "$@"; }
+i=0
+until c version >/dev/null 2>&1; do
+  kill -0 "$pid" || { cat /run/cache.log; exit 1; }
+  i=$((i+1)); [ "$i" -lt 300 ] || { cat /run/cache.log; exit 1; }
+  sleep 0.1
+done
+ids=$(c containers ls -q)
+if [ -n "$ids" ]; then c containers rm $ids; fi
+# 1.7 has no sandbox store; 2.x does.
+case "$(containerd --version)" in
+  *v1.*) ;;
+  *) sandboxes=$(c sandboxes ls)
+     ids=$(printf '%s\\n' "$sandboxes" | awk 'NR > 1 {print $1}')
+     if [ -n "$ids" ]; then c sandboxes rm --force $ids; fi ;;
+esac
+ids=$(c leases ls -q)
+if [ -n "$ids" ]; then c leases rm $ids; fi
+# Remove children before parents, and tolerate asynchronous GC winning a race.
+previous=''
+while :; do
+  snapshots=$(c snapshots --snapshotter overlayfs ls)
+  ids=$(printf '%s\\n' "$snapshots" | awk 'NR > 1 && $NF != "Committed" {print $1}')
+  [ -n "$ids" ] || break
+  [ "$ids" != "$previous" ] || { echo 'cannot clean Kubernetes writable snapshots' >&2; exit 1; }
+  previous="$ids"
+  for id in $ids; do c snapshots --snapshotter overlayfs rm "$id" >/dev/null 2>&1 || true; done
+done
+touch /run/cache-ready
+while :; do sleep 1 & wait $!; done
+`;
+export async function openKubernetesCacheMaintenance(run, root = ROOT) {
+    const stores = [];
+    const protectedImages = new Set();
+    const closeStore = async (store) => {
+        if (!store.active)
+            return;
+        await run("docker", ["stop", "--time", "30", store.container], 45_000);
+        const status = JSON.parse(await run("docker", ["inspect", "--format", "{{json .State}}", store.container]));
+        if (status.ExitCode !== 0 || status.OOMKilled)
+            throw new Error(`unclean Kubernetes cache shutdown: ${store.container}`);
+        await run("docker", ["rm", store.container]);
+        store.active = false;
+        if (!stores.some(other => other.active && other.descriptor.image === store.descriptor.image))
+            protectedImages.delete(store.descriptor.image);
+        // These contain runtime state, not image content or unpacked layers.
+        await run("rm", ["-rf", ...["io.containerd.runtime.v2.task", "io.containerd.grpc.v1.cri", "io.containerd.cri.v1.runtime", "tmpmounts"]
+                .map(child => `${store.directory}/containerd/${child}`)]);
+    };
+    const close = async () => {
+        const failures = [];
+        for (const store of stores) {
+            try {
+                await closeStore(store);
+            }
+            catch (error) {
+                failures.push(error);
+            }
+        }
+        if (failures.length)
+            throw new AggregateError(failures, "Kubernetes cache shutdown failed");
+    };
+    const entries = await readdir(root, { withFileTypes: true }).catch((error) => {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    });
+    try {
+        for (const service of entries) {
+            if (!service.isDirectory() || !SERVICE_NAME.test(service.name))
+                continue;
+            for (const layout of await readdir(`${root}/${service.name}`, { withFileTypes: true })) {
+                if (!layout.isDirectory() || !/^[a-f0-9]{16}$/.test(layout.name))
+                    continue;
+                const directory = `${root}/${service.name}/${layout.name}`;
+                const descriptor = JSON.parse(await readFile(`${directory}/store.json`, "utf8"));
+                if (descriptor.schema !== 1 || !IMAGE_ID.test(descriptor.image) || !Number.isSafeInteger(descriptor.updatedAt)) {
+                    throw new Error(`invalid Kubernetes cache descriptor: ${directory}`);
+                }
+                const container = `spectest-k8s-cache-${randomUUID()}`;
+                await run("docker", ["run", "-d", "--name", container, "--network", "none", "--privileged", "--stop-signal", "SIGTERM", "--tmpfs", "/run", "--tmpfs", "/var/run",
+                    "--mount", `type=bind,source=${directory}/containerd,target=${STORE_TARGET}`,
+                    "--entrypoint", "/bin/sh", descriptor.image, "-c", KUBERNETES_CACHE_MAINTENANCE_SH]);
+                stores.push({ directory, descriptor, container, active: true });
+                protectedImages.add(descriptor.image);
+                try {
+                    await run("docker", ["exec", container, "sh", "-c", "i=0; until [ -f /run/cache-ready ]; do i=$((i+1)); [ $i -lt 900 ] || exit 1; sleep 0.1; done"], 100_000);
+                }
+                catch (error) {
+                    const logs = await run("docker", ["logs", "--tail", "40", container]).catch(() => "");
+                    throw new Error(`Kubernetes cache preparation failed for ${directory}: ${logs}`, { cause: error });
+                }
+            }
+        }
+        stores.sort((a, b) => a.descriptor.updatedAt - b.descriptor.updatedAt || a.directory.localeCompare(b.directory));
+        let next = 0;
+        const pruneOldest = async () => {
+            const store = stores[next++];
+            if (!store)
+                return false;
+            await run("docker", ["exec", store.container, "sh", "-ec",
+                `ids=$(ctr -a ${SOCKET} -n k8s.io images ls -q); if [ -n "$ids" ]; then ctr -a ${SOCKET} -n k8s.io images rm --sync $ids; fi`], 120_000);
+            await closeStore(store);
+            // No writer remains. Discard the now-empty cache and its descriptor so
+            // obsolete k3s binaries can also be collected by the outer Docker GC.
+            await run("rm", ["-rf", store.directory]);
+            return true;
+        };
+        // Abandoned services/versions should not occupy the disk indefinitely.
+        while (stores[next] && stores[next].descriptor.updatedAt < Date.now() - 7 * 24 * 60 * 60 * 1000)
+            await pruneOldest();
+        return { protectedImages, pruneOldest, close };
+    }
+    catch (error) {
+        await close().catch(() => { });
+        throw error;
+    }
+}

package/dist/harness/sticky-paths.d.ts

@@ -0,0 +1,5 @@
+export declare const STICKY_ROOT = "/var/lib/spectest-sticky";
+export declare const STICKY_RUNTIME = "/run/spectest-sticky";
+/** Written only after the supervisor mounts this project's private disk. */
+export declare function stickyDiskPathSync(manifest?: string): string | null;
+export declare function isOnStickyDisk(path: string, root?: string | null): boolean;

package/dist/harness/sticky-paths.js

@@ -0,0 +1,18 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+export const STICKY_ROOT = "/var/lib/spectest-sticky";
+export const STICKY_RUNTIME = "/run/spectest-sticky";
+/** Written only after the supervisor mounts this project's private disk. */
+export function stickyDiskPathSync(manifest = `${STICKY_RUNTIME}/consumer.json`) {
+    try {
+        const config = JSON.parse(readFileSync(manifest, "utf8"));
+        return config.path === STICKY_ROOT ? STICKY_ROOT : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function isOnStickyDisk(path, root = stickyDiskPathSync()) {
+    const absolute = resolve(path);
+    return root !== null && (absolute === root || absolute.startsWith(`${root}/`));
+}

package/dist/index.d.ts

@@ -74,6 +74,8 @@ export interface EnvironmentConfig<S extends ServicesMap = ServicesMap> {
 export interface ServiceConfig {
     /** Image definition: registry pull or inline build. */
     image: ServiceImage;
+    /** @internal Images built by the harness and loaded into this component. */
+    imageBuilds?: readonly ComponentImageBuild[];
     /**
      * Shell command to run (sh -c). Defaults to the image's CMD. NB: this
      * **replaces the image's entrypoint** with `/bin/sh -c` — an
@@ -741,11 +743,14 @@ export interface ServiceTls {
      * daemon forwards proxied requests here over `spectest-net`. */
     port: number;
 }
-export type ServiceImage = {
+/** @internal Normalized wire representation; legacy definitions remain accepted. */
+export type NormalizedServiceImage = {
     type: "registry";
     reference: string;
 } | {
     type: "dockerfile";
+    /** Optional full local image reference. */
+    reference?: string;
     /**
      * Path of a Dockerfile in your repo, relative to the project root
      * (where `spectest/` lives) — `"Dockerfile"`, `"apps/api/Dockerfile"`.
@@ -787,6 +792,8 @@ export type ServiceImage = {
     buildArgs?: Readonly<Record<string, string>>;
 } | {
     type: "dockerfile";
+    /** Optional full local image reference. */
+    reference?: string;
     /**
      * Dockerfile contents, built as if the file sat outside the build
      * context (it is never written into your repo). The context is the
@@ -815,6 +822,29 @@ export type ServiceImage = {
      */
     buildArgs?: Readonly<Record<string, string>>;
 };
+/** Dockerfile build options shared by services and Kubernetes images. */
+export type BuildImage = (Omit<Extract<NormalizedServiceImage, {
+    type: "dockerfile";
+    path: string;
+}>, "type"> | Omit<Extract<NormalizedServiceImage, {
+    type: "dockerfile";
+    content: string;
+}>, "type">) & {
+    /** Full image reference, e.g. "k8s.internal:5000/runtime:spectest".
+     * Optional for a service; required for a Kubernetes build. This names a
+     * local image and does not publish it to a registry. */
+    reference?: string;
+};
+/** A registry reference or Dockerfile build. Tagged objects from older SDKs
+ * remain accepted for compatibility; new definitions do not need `type`. */
+export type ServiceImage = string | BuildImage | NormalizedServiceImage;
+/** @internal Keep the wire format compatible with existing control planes. */
+export declare function normalizeServiceImage(image: ServiceImage): NormalizedServiceImage;
+/** @internal Serializes build-only work with the owning component. */
+export interface ComponentImageBuild {
+    reference: string;
+    image: BuildImage;
+}
 /**
  * Check a service's `image` at config time, so a mistake fails the
  * environment load with a message that names it, instead of a build
@@ -831,7 +861,7 @@ export type ServiceImage = {
  * checks go through the project-file resolver, so the same rules as
  * `ctx.readProjectFile` apply.
  */
-export declare function validateServiceImage(serviceName: string, image: ServiceImage): ServiceImage;
+export declare function validateServiceImage(serviceName: string, input: ServiceImage): NormalizedServiceImage;
 export interface VolumeMount {
     /**
      * Named shared volume. Two services mounting the same `name` share one

package/dist/index.js

@@ -220,6 +220,19 @@ function expandServiceGroups(input) {
     }
     return out;
 }
+/** @internal Keep the wire format compatible with existing control planes. */
+export function normalizeServiceImage(image) {
+    if (typeof image === "string")
+        return { type: "registry", reference: image };
+    if (!image || typeof image !== "object" || Array.isArray(image))
+        throw new Error("image must be a registry reference or Dockerfile build");
+    if ("type" in image) {
+        if (image.type !== "registry" && image.type !== "dockerfile")
+            throw new Error("unsupported image type");
+        return image;
+    }
+    return { ...image, type: "dockerfile" };
+}
 /** A Dockerfile `ARG` name: what `docker build --build-arg` accepts as a key. */
 const BUILD_ARG_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
 function validateBuildArgs(serviceName, buildArgs) {
@@ -255,9 +268,17 @@ const BUILD_TARGET_RE = /^[^\s]+$/;
  * checks go through the project-file resolver, so the same rules as
  * `ctx.readProjectFile` apply.
  */
-export function validateServiceImage(serviceName, image) {
+export function validateServiceImage(serviceName, input) {
+    const image = normalizeServiceImage(input);
+    const reference = typeof input === "string" ? input : "reference" in input ? input.reference : undefined;
+    if (reference !== undefined && (typeof reference !== "string" || !reference || reference.startsWith("-") || /[\s\x00]/.test(reference)))
+        throw new Error(`service "${serviceName}" image reference must be a non-empty image name without whitespace`);
     if (image.type !== "dockerfile")
         return image;
+    if (reference?.includes("@"))
+        throw new Error(`service "${serviceName}" build reference must be an image name/tag, not a digest`);
+    if (image.exclude !== undefined && (!Array.isArray(image.exclude) || image.exclude.some(e => typeof e !== "string")))
+        throw new Error(`service "${serviceName}" image exclude must be an array of glob patterns`);
     validateBuildArgs(serviceName, image.buildArgs);
     const hasPath = typeof image.path === "string";
     const hasContent = typeof image.content === "string";
@@ -265,7 +286,7 @@ export function validateServiceImage(serviceName, image) {
         throw new Error(`service "${serviceName}" image sets both \`path\` and \`content\` — point at the Dockerfile in your repo with \`path\`, or inline it with \`content\`, not both`);
     }
     if (!hasPath && !hasContent) {
-        throw new Error(`service "${serviceName}" image { type: "dockerfile" } needs \`path\` (a Dockerfile in your repo, relative to the project root) or \`content\``);
+        throw new Error(`service "${serviceName}" image build needs \`path\` (a Dockerfile in your repo, relative to the project root) or \`content\``);
     }
     if (hasPath) {
         const file = resolveExistingProjectPath(image.path, `service "${serviceName}" Dockerfile`);
@@ -403,6 +424,8 @@ export function defineEnvironment(input) {
     const { fakes, services: rawServices, ...rest } = input;
     const expanded = expandServiceGroups(rawServices);
     for (const [key, svc] of Object.entries(expanded)) {
+        for (const build of svc.imageBuilds ?? [])
+            validateServiceImage(`${key} image ${build.reference}`, build.image);
         expanded[key] = applyCoverageAdapters(key, {
             ...svc,
             image: validateServiceImage(key, svc.image),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.90.2",
+  "version": "0.91.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",

package/src/browser-coverage.ts

@@ -12,8 +12,8 @@
 //
 // Harvest runs before every browser step (a click that navigates
 // cross-site replaces the renderer, and the old counters with it) and at
-// every coverage capture. `browserCoverageReports` renders the totals as
-// one lcov per service for the `case-coverage` bundle.
+// every coverage capture. `takeBrowserCoverageReport` renders and clears
+// one service's totals for the `case-coverage` bundle.
 //
 // Configured by the daemon at /load with the host → service table; a
 // project with no `coverage: { browser: true }` service never attaches
@@ -220,17 +220,15 @@ export async function harvestAllBrowserCoverage(): Promise<void> {
   await Promise.all([...LIVE_COLLECTORS].map((c) => harvestBrowserCoverage(c.cdp)));
 }
 
-/** One lcov document per service that has any browser coverage — and
- *  the totals are cleared, so the next capture holds only what runs
- *  from now on. Module memory forks with the environment, so a forked
- *  child starts from its parent's last capture, empty. */
-export function takeBrowserCoverageReports(): Map<string, string> {
-  const out = new Map<string, string>();
-  for (const [service, files] of TOTALS) {
-    if (files.size > 0) out.set(service, lcovDocument(files));
-  }
-  TOTALS.clear();
-  return out;
+/** Take one service's lcov report and clear only its totals. Other
+ *  services retain their coverage until their own capture. Each capture
+ *  is a delta; after every service is captured, a forked child inherits
+ *  empty totals from its parent. */
+export function takeBrowserCoverageReport(service: string): string {
+  const files = TOTALS.get(service);
+  const report = files ? lcovDocument(files) : "TN:\n";
+  TOTALS.delete(service);
+  return report;
 }
 
 /** The current totals, without clearing them (tests). */

package/src/components/index.ts

@@ -26,6 +26,7 @@ export { SQL, type SqlClient, type SqlOptions } from "../sql.js";
 export {
   k3s,
   type K3sOptions,
+  type KubernetesImage,
   type K3sHelpers,
   type K3sClient,
   type TaggedObjectApi,

package/src/components/k3s-trust.test.ts

@@ -0,0 +1,81 @@
+import { afterEach, expect, test } from "bun:test";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { execFileSync } from "node:child_process";
+import { request } from "node:https";
+import { installPodTrust, podTrustPatch, stopPodTrust, TRUST_OPT_OUT } from "./k3s-trust";
+
+function patched<T>(value: T, patch: ReturnType<typeof podTrustPatch>): T {
+  const out = structuredClone(value);
+  for (const operation of patch) {
+    const keys = operation.path.slice(1).split("/");
+    const key = keys.pop()!;
+    const parent = keys.reduce((o, k) => o[k], out as any);
+    if (key === "-") parent.push(operation.value); else parent[key] = operation.value;
+  }
+  return out;
+}
+
+test("mounts trust into regular and init containers without changing images or security settings", () => {
+  const pod = { spec: { containers: [{ name: "app", image: "app@sha256:original", securityContext: { runAsUser: 1000, readOnlyRootFilesystem: true } }], initContainers: [{ name: "init", image: "init:1" }] } };
+  const patch = podTrustPatch(pod, "bundle");
+  const result: any = patched(pod, patch);
+  expect(result.spec.containers[0].image).toBe("app@sha256:original");
+  expect(result.spec.containers[0].securityContext).toEqual(pod.spec.containers[0].securityContext);
+  expect(result.spec.initContainers[0].env).toContainEqual({ name: "SSL_CERT_FILE", value: "/spectest/ca-bundle.crt" });
+  expect(result.spec.volumes[0].configMap.name).toBe("bundle");
+  expect(result.spec.containers[0].volumeMounts.every((m: any) => m.readOnly)).toBe(true);
+  expect(podTrustPatch(result, "bundle")).toEqual([]);
+  expect(pod).not.toHaveProperty("spec.volumes");
+});
+
+test("preserves explicit trust settings and mounts, including volume name collisions", () => {
+  const pod = { spec: {
+    volumes: [{ name: "spectest-ca", emptyDir: {} }],
+    containers: [{ env: [{ name: "SSL_CERT_FILE", value: "/custom.pem" }], volumeMounts: [{ name: "custom", mountPath: "/etc/ssl" }] }],
+  } };
+  const result: any = patched(pod, podTrustPatch(pod, "bundle"));
+  expect(result.spec.volumes[1].name).toBe("spectest-ca-1");
+  expect(result.spec.containers[0].env.filter((e: any) => e.name === "SSL_CERT_FILE")).toEqual([{ name: "SSL_CERT_FILE", value: "/custom.pem" }]);
+  expect(result.spec.containers[0].volumeMounts.some((m: any) => m.mountPath === "/etc/ssl/certs/ca-certificates.crt")).toBe(false);
+});
+
+test("opt-out, Windows and ephemeral container updates are handled without changing immutable Pod volumes", () => {
+  expect(podTrustPatch({ metadata: { annotations: { [TRUST_OPT_OUT]: "false" } }, spec: { containers: [{}] } }, "bundle")).toEqual([]);
+  expect(podTrustPatch({ spec: { os: { name: "windows" }, containers: [{}] } }, "bundle")).toEqual([]);
+  expect(podTrustPatch({ spec: { ephemeralContainers: [{}] } }, "bundle", true)).toEqual([]);
+  const result: any = patched({ spec: { containers: [{}], ephemeralContainers: [{}], volumes: [{ name: "existing", configMap: { name: "bundle" } }] } }, podTrustPatch({ spec: { ephemeralContainers: [{}], volumes: [{ name: "existing", configMap: { name: "bundle" } }] } }, "bundle", true));
+  expect(result.spec.volumes).toHaveLength(1);
+  expect(result.spec.containers[0]).toEqual({});
+  expect(result.spec.ephemeralContainers[0].volumeMounts[0].name).toBe("existing");
+});
+
+afterEach(() => stopPodTrust("fixture"));
+test("admission uses verified TLS, provisions bundles on real requests, and fails closed", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "k3s-trust-"));
+  try {
+    execFileSync("openssl", ["req", "-x509", "-newkey", "rsa:2048", "-nodes", "-keyout", join(dir, "key"), "-out", join(dir, "cert"), "-subj", "/CN=fixture", "-addext", "subjectAltName=IP:127.0.0.1", "-days", "1"], { stdio: "ignore" });
+    const cert = readFileSync(join(dir, "cert"), "utf8");
+    let config: any, calls = 0, fail = false;
+    await installPodTrust({ name: "fixture", gateway: "127.0.0.1", bundle: "bundle", cert, key: readFileSync(join(dir, "key"), "utf8"), ca: cert }, {
+      apply: async c => { config = c; },
+      ensureBundle: async namespace => { expect(namespace).toBe("app"); calls++; if (fail) throw new Error("API unavailable"); },
+    });
+    expect(config.webhooks[0].failurePolicy).toBe("Fail");
+    const send = (dryRun = false) => new Promise<{ status: number; body: any }>((resolve, reject) => {
+      const req = request(config.webhooks[0].clientConfig.url + "?timeout=10s", { method: "POST", ca: cert }, res => {
+        let body = ""; res.on("data", c => body += c); res.on("end", () => resolve({ status: res.statusCode!, body: res.statusCode === 200 ? JSON.parse(body) : body }));
+      });
+      req.on("error", reject);
+      req.end(JSON.stringify({ request: { uid: "request-1", resource: { resource: "pods" }, namespace: "app", dryRun, object: { spec: { containers: [{}] } } } }));
+    });
+    const dry = await send(true);
+    expect(dry.body.response.uid).toBe("request-1");
+    expect(calls).toBe(0);
+    expect((await send()).status).toBe(200);
+    expect(calls).toBe(1);
+    fail = true;
+    expect((await send()).status).toBe(500);
+  } finally { rmSync(dir, { recursive: true, force: true }); }
+});

package/src/components/k3s-trust.ts

@@ -0,0 +1,135 @@
+/** Pod trust belongs to the cluster. Admission adds read-only ConfigMap
+ * mounts and environment defaults, without changing any image bytes. */
+import { createHash, randomUUID } from "node:crypto";
+import { createServer, type Server } from "node:https";
+
+export const POD_CA_PATH = "/spectest/ca-bundle.crt";
+const TRUST_ENV: Readonly<Record<string, string>> = {
+  NODE_EXTRA_CA_CERTS: POD_CA_PATH, SSL_CERT_FILE: POD_CA_PATH,
+  REQUESTS_CA_BUNDLE: POD_CA_PATH, AWS_CA_BUNDLE: POD_CA_PATH,
+  PGSSLROOTCERT: POD_CA_PATH, DENO_TLS_CA_STORE: "mozilla,system",
+};
+const MOUNT_PATHS = [POD_CA_PATH, "/etc/ssl/certs/ca-certificates.crt", "/etc/pki/tls/certs/ca-bundle.crt"];
+interface Container {
+  env?: { name: string; value?: string; valueFrom?: unknown }[];
+  volumeMounts?: { name: string; mountPath: string; subPath?: string; readOnly?: boolean }[];
+}
+interface Pod {
+  metadata?: { annotations?: Record<string, string> };
+  spec?: {
+    os?: { name: string };
+    volumes?: { name: string; configMap?: { name: string }; [key: string]: unknown }[];
+    containers?: Container[]; initContainers?: Container[]; ephemeralContainers?: Container[];
+  };
+}
+interface Patch { op: "add"; path: string; value: unknown }
+export const TRUST_OPT_OUT = "spectest.dev/inject-ca";
+
+export function podTrustPatch(pod: Pod, configMap: string, ephemeral = false): Patch[] {
+  if (!pod.spec || pod.spec.os?.name === "windows" || pod.metadata?.annotations?.[TRUST_OPT_OUT] === "false") return [];
+  const patches: Patch[] = [];
+  const volumes = pod.spec.volumes ?? [];
+  // Reuse our immutable ConfigMap, but never overwrite a user's volume.
+  let volume = volumes.find(v => v.configMap?.name === configMap)?.name;
+  if (!volume && ephemeral) return []; // Pod volumes cannot change on this subresource.
+  if (!volume) {
+    const names = new Set(volumes.map(v => v.name));
+    volume = "spectest-ca";
+    for (let n = 1; names.has(volume); n++) volume = `spectest-ca-${n}`;
+    const value = { name: volume, configMap: { name: configMap, defaultMode: 0o444, items: [{ key: "ca-bundle.crt", path: "ca-bundle.crt" }] } };
+    patches.push(pod.spec.volumes
+      ? { op: "add", path: "/spec/volumes/-", value }
+      : { op: "add", path: "/spec/volumes", value: [value] });
+  }
+  const groups = ephemeral ? ["ephemeralContainers"] as const : ["containers", "initContainers"] as const;
+  for (const group of groups) {
+    for (const [index, container] of (pod.spec[group] ?? []).entries()) {
+      const prefix = `/spec/${group}/${index}`;
+      const env = container.env ?? [];
+      const names = new Set(env.map(e => e.name));
+      const extraEnv = Object.entries(TRUST_ENV).filter(([name]) => !names.has(name)).map(([name, value]) => ({ name, value }));
+      const mounts = container.volumeMounts ?? [];
+      // A user mount at a path (or a parent directory) owns that path.
+      const extraMounts = MOUNT_PATHS.filter(path => !mounts.some(m => path === m.mountPath || path.startsWith(m.mountPath.replace(/\/$/, "") + "/")))
+        .map(mountPath => ({ name: volume!, mountPath, subPath: "ca-bundle.crt", readOnly: true }));
+      if (extraEnv.length) patches.push({ op: "add", path: `${prefix}/env`, value: [...env, ...extraEnv] });
+      if (extraMounts.length) patches.push({ op: "add", path: `${prefix}/volumeMounts`, value: [...mounts, ...extraMounts] });
+    }
+  }
+  return patches;
+}
+
+interface AdmissionRequest {
+  uid: string; namespace?: string; dryRun?: boolean; subResource?: string;
+  resource?: { resource: string }; object?: Pod;
+}
+export interface TrustDependencies {
+  /** Ensure this immutable ConfigMap exists in the requesting namespace. */
+  ensureBundle(namespace: string, name: string, bundle: string): Promise<void>;
+  apply(configuration: unknown): Promise<void>;
+}
+const servers = new Map<string, Server>();
+
+export async function installPodTrust(options: {
+  name: string; gateway: string; bundle: string; cert: string; key: string; ca: string;
+}, deps: TrustDependencies): Promise<void> {
+  const configMap = `spectest-ca-${createHash("sha256").update(options.bundle).digest("hex").slice(0, 20)}`;
+  const endpoint = `/admit/${randomUUID()}`;
+  const server = createServer({ cert: options.cert, key: options.key }, async (req, res) => {
+    if (req.method !== "POST" || new URL(req.url ?? "/", "https://local").pathname !== endpoint) { res.writeHead(404).end(); return; }
+    const chunks: Buffer[] = [];
+    let size = 0;
+    try {
+      for await (const chunk of req) {
+        size += chunk.length;
+        if (size > 2 * 1024 * 1024) { res.writeHead(413).end(); return; }
+        chunks.push(Buffer.from(chunk));
+      }
+      const review = JSON.parse(Buffer.concat(chunks).toString());
+      const request = review.request as AdmissionRequest | undefined;
+      if (!request?.uid || request.resource?.resource !== "pods" || !request.object || !request.namespace) {
+        res.writeHead(400).end("invalid Pod admission request"); return;
+      }
+      const patch = podTrustPatch(request.object, configMap, request.subResource === "ephemeralcontainers");
+      // Dry runs return the same patch but perform no API writes.
+      if (patch.length && !request.dryRun) await deps.ensureBundle(request.namespace, configMap, options.bundle);
+      res.setHeader("Content-Type", "application/json");
+      res.end(JSON.stringify({ apiVersion: "admission.k8s.io/v1", kind: "AdmissionReview", response: {
+        uid: request.uid, allowed: true,
+        ...(patch.length ? { patchType: "JSONPatch", patch: Buffer.from(JSON.stringify(patch)).toString("base64") } : {}),
+      } }));
+    } catch (err) {
+      console.error(`[k3s-trust] ${options.name}: ${err instanceof Error ? err.message : err}`);
+      res.writeHead(500).end("could not mount the environment CA");
+    }
+  });
+  server.requestTimeout = 15_000;
+  try {
+    await new Promise<void>((resolve, reject) => { server.once("error", reject); server.listen(0, options.gateway, resolve); });
+    const port = (server.address() as { port: number }).port;
+    await deps.apply({
+      apiVersion: "admissionregistration.k8s.io/v1", kind: "MutatingWebhookConfiguration",
+      metadata: { name: "spectest-pod-trust" },
+      webhooks: [{
+        name: "pod-trust.spectest.dev", admissionReviewVersions: ["v1"],
+        sideEffects: "NoneOnDryRun", failurePolicy: "Fail", timeoutSeconds: 10,
+        reinvocationPolicy: "IfNeeded", matchPolicy: "Equivalent",
+        clientConfig: { url: `https://${options.gateway}:${port}${endpoint}`, caBundle: Buffer.from(options.ca).toString("base64") },
+        rules: [{ operations: ["CREATE"], apiGroups: [""], apiVersions: ["v1"], resources: ["pods"], scope: "Namespaced" },
+          { operations: ["UPDATE"], apiGroups: [""], apiVersions: ["v1"], resources: ["pods/ephemeralcontainers"], scope: "Namespaced" }],
+      }],
+    });
+  } catch (err) {
+    server.closeAllConnections(); server.close(); throw err;
+  }
+  const previous = servers.get(options.name);
+  servers.set(options.name, server);
+  previous?.closeAllConnections(); previous?.close();
+}
+
+/** Release a component listener on replacement or in standalone tests. */
+export function stopPodTrust(name: string): void {
+  const server = servers.get(name);
+  servers.delete(name);
+  server?.closeAllConnections(); server?.close();
+}