@specific.dev/spectest 0.123.0 → 0.125.0

package/dist/components/android-runtime.mjs

@@ -3,6 +3,7 @@ import http from "node:http";
 import { spawn, execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { mkdir, stat, open, rm } from "node:fs/promises";
+import { installAndroidTrust } from "./spectest-android-trust.mjs";
 const exec = promisify(execFile);
 const serial = process.env.ANDROID_SERIAL;
 const directory = "/recordings";
@@ -28,6 +29,7 @@ async function bootstrap() {
       "Android did not boot; the guest kernel needs Binder, DMA-BUF heaps and PSI enabled",
     );
   }
+  await installAndroidTrust(adb, process.env.ANDROID_CA_PATH);
   await adb("install", "-r", "/spectest/app.apk");
   await adb("shell", "settings", "put", "global", "private_dns_mode", "off");
   for (const setting of [

package/dist/components/android-trust.mjs

@@ -0,0 +1,126 @@
+// Runtime-only trust provisioning for the private Android device. Never change
+// the image or disable certificate/hostname verification in the application.
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { mkdtemp, writeFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const exec = promisify(execFile);
+
+export const ANDROID_TRUST_SCRIPT = `#!/system/bin/sh
+set -eu
+cert=/data/local/tmp/spectest-ca.crt
+store=/data/local/tmp/spectest-system-cacerts
+system=/system/etc/security/cacerts
+apex=/apex/com.android.conscrypt/cacerts
+hash="$1"
+test "$(id -u)" = 0
+test -s "$cert"
+
+# Keep a private copy of the active Android root set, including its public CAs.
+# The directory and namespace mounts are part of the VM snapshot, not the image.
+if [ ! -d "$store" ]; then
+    original="$system"
+    if [ -d "$apex" ] && [ -n "$(ls -A "$apex")" ]; then original="$apex"; fi
+    copy=$(mktemp -d /data/local/tmp/spectest-cacerts.XXXXXX)
+    trap 'rm -rf "$copy"' EXIT
+    cp "$original"/* "$copy"/
+    mv "$copy" "$store"
+    trap - EXIT
+fi
+
+# Android uses the old OpenSSL subject hash, with numbered collisions. Never
+# overwrite a public root with the same subject hash, or duplicate our own CA.
+index=0
+while [ -f "$store/$hash.$index" ]; do
+    if cmp -s "$cert" "$store/$hash.$index"; then break; fi
+    index=$((index + 1))
+done
+cp "$cert" "$store/$hash.$index"
+chown 0:0 "$store" "$store"/*
+chmod 0755 "$store"
+chmod 0644 "$store"/*
+if [ "$(getenforce)" != Disabled ]; then
+    chcon u:object_r:system_file:s0 "$store" "$store"/*
+fi
+
+# Android 14 loads roots from Conscrypt's APEX. Each zygote has a private mount
+# namespace, inherited by new apps and the pre-forked USAP pool. Enter those
+# namespaces, including existing descendants, before the APK is launched.
+zygotes="$(pidof zygote zygote64 || true)"
+test -n "$zygotes" || { echo 'Android TLS: no zygote process found' >&2; exit 1; }
+# Mount each generation before enumerating its children. A process forked
+# after enumeration then inherits the mounted store, closing the USAP race.
+frontier="$zygotes"
+while [ -n "$frontier" ]; do
+    for pid in $frontier; do
+        [ -d "/proc/$pid" ] || continue
+        for target in "$system" "$apex"; do
+            [ -d "/proc/$pid/root$target" ] || continue
+            if ! cmp -s "$cert" "/proc/$pid/root$target/$hash.$index"; then
+                # setns alone can retain the caller's filesystem root.
+                if ! nsenter --mount="/proc/$pid/ns/mnt" -- chroot "/proc/$pid/root" mount --bind "$store" "$target"; then
+                    [ ! -d "/proc/$pid" ] && break
+                    echo "Android TLS: cannot install trust in process $pid" >&2
+                    exit 1
+                fi
+            fi
+        done
+    done
+    # Android 14's toybox has no awk. Walk with the system shell instead.
+    processes="$(ps -A -o PID,PPID)"
+    next=""
+    while read -r pid parent; do
+        case " $frontier " in *" $parent "*) next="$next $pid" ;; esac
+    done <<PROCESSES
+$processes
+PROCESSES
+    frontier="$next"
+done
+for pid in $zygotes; do
+    target="$system"
+    if [ -d "/proc/$pid/root$apex" ]; then target="$apex"; fi
+    cmp -s "$cert" "/proc/$pid/root$target/$hash.$index"
+done
+echo 'spectest-android-trust-ready'
+`;
+
+/** Install the environment CA before app installation/launch. Throws on failure. */
+export async function installAndroidTrust(adb, caPath, run = exec) {
+  try {
+    const { stdout } = await run("openssl", ["x509", "-in", caPath, "-subject_hash_old", "-noout"]);
+    const hash = stdout.trim();
+    if (!/^[a-f0-9]{8}$/.test(hash)) throw new Error("invalid CA subject hash");
+
+    let root = [];
+    if ((await adb("shell", "id", "-u")).stdout.trim() !== "0") {
+      try {
+        if ((await adb("shell", "su", "0", "id", "-u")).stdout.trim() !== "0") throw new Error("not root");
+        root = ["su", "0"];
+      } catch {
+        await adb("root");
+        await adb("wait-for-device");
+        if ((await adb("shell", "id", "-u")).stdout.trim() !== "0") {
+          throw new Error("the Android image must provide root ADB or su access");
+        }
+      }
+    }
+    const directory = await mkdtemp(join(tmpdir(), "spectest-android-trust-"));
+    try {
+      const script = join(directory, "trust.sh");
+      await writeFile(script, ANDROID_TRUST_SCRIPT);
+      await adb("push", caPath, "/data/local/tmp/spectest-ca.crt");
+      await adb("push", script, "/data/local/tmp/spectest-trust.sh");
+      const result = await adb("shell", ...root, "sh", "/data/local/tmp/spectest-trust.sh", hash);
+      if (!result.stdout.includes("spectest-android-trust-ready")) {
+        throw new Error("system CA provisioning did not confirm success");
+      }
+    } finally {
+      await rm(directory, { recursive: true, force: true });
+      await adb("shell", "rm", "-f", "/data/local/tmp/spectest-ca.crt", "/data/local/tmp/spectest-trust.sh").catch(() => {});
+    }
+  } catch (cause) {
+    throw new Error(`Android TLS trust provisioning failed: ${cause.message}`, { cause });
+  }
+}

package/dist/components/android.d.ts

@@ -19,7 +19,7 @@ export interface AndroidOptions {
     recording?: false | AndroidRecordingOptions;
     dependsOn?: string[];
 }
-export declare const ANDROID_TOOLS_DOCKERFILE = "FROM node:22-bookworm-slim\nRUN apt-get update && apt-get install -y --no-install-recommends adb aapt apksigner zipalign ffmpeg default-jdk-headless ca-certificates curl gcc pkg-config meson ninja-build libsdl2-dev libavcodec-dev libavdevice-dev libavformat-dev libavutil-dev libswresample-dev libusb-1.0-0-dev && rm -rf /var/lib/apt/lists/*\nRUN curl -fL https://github.com/Genymobile/scrcpy/archive/refs/tags/v3.3.1.tar.gz | tar xz -C /tmp && curl -fL https://github.com/Genymobile/scrcpy/releases/download/v3.3.1/scrcpy-server-v3.3.1 -o /tmp/scrcpy-server && meson setup /tmp/scrcpy-build /tmp/scrcpy-3.3.1 --buildtype=release -Dprebuilt_server=/tmp/scrcpy-server && ninja -C /tmp/scrcpy-build -j4 install && rm -rf /tmp/scrcpy*\nENV ANDROID_HOME=/opt/android JAVA_HOME=/usr/lib/jvm/default-java APPIUM_HOME=/opt/appium\nRUN mkdir -p /opt/android/platform-tools && for tool in adb aapt aapt2 apksigner zipalign; do ln -s /usr/bin/$tool /opt/android/platform-tools/$tool; done && npm install -g appium@3.8.0 && appium driver install uiautomator2@8.7.0\n";
+export declare const ANDROID_TOOLS_DOCKERFILE = "FROM node:22-bookworm-slim\nRUN apt-get update && apt-get install -y --no-install-recommends adb aapt apksigner zipalign ffmpeg default-jdk-headless ca-certificates openssl curl gcc pkg-config meson ninja-build libsdl2-dev libavcodec-dev libavdevice-dev libavformat-dev libavutil-dev libswresample-dev libusb-1.0-0-dev && rm -rf /var/lib/apt/lists/*\nRUN curl -fL https://github.com/Genymobile/scrcpy/archive/refs/tags/v3.3.1.tar.gz | tar xz -C /tmp && curl -fL https://github.com/Genymobile/scrcpy/releases/download/v3.3.1/scrcpy-server-v3.3.1 -o /tmp/scrcpy-server && meson setup /tmp/scrcpy-build /tmp/scrcpy-3.3.1 --buildtype=release -Dprebuilt_server=/tmp/scrcpy-server && ninja -C /tmp/scrcpy-build -j4 install && rm -rf /tmp/scrcpy*\nENV ANDROID_HOME=/opt/android JAVA_HOME=/usr/lib/jvm/default-java APPIUM_HOME=/opt/appium\nRUN mkdir -p /opt/android/platform-tools && for tool in adb aapt aapt2 apksigner zipalign; do ln -s /usr/bin/$tool /opt/android/platform-tools/$tool; done && npm install -g appium@3.8.0 && appium driver install uiautomator2@8.7.0\n";
 /** Native Android, Appium and software recording, all inside the environment VM. */
 export declare function android(options: AndroidOptions): import("../index.js").ServiceGroup<{
     device: {
@@ -60,6 +60,7 @@ export declare function android(options: AndroidOptions): import("../index.js").
         inputs: string[];
         env: {
             ANDROID_SERIAL: string;
+            ANDROID_CA_PATH: string;
             ANDROID_ACTIVITY: string;
             ANDROID_SHOW_TOUCHES: string;
         };

package/dist/components/android.js

@@ -3,8 +3,9 @@ import { posix } from "node:path";
 import { serviceGroup } from "../index.js";
 import { resolveExistingProjectPath } from "../project-files.js";
 import { androidApp } from "../android.js";
+import { ENVIRONMENT_CA_PATH } from "../environment-ca.js";
 export const ANDROID_TOOLS_DOCKERFILE = `FROM node:22-bookworm-slim
-RUN apt-get update && apt-get install -y --no-install-recommends adb aapt apksigner zipalign ffmpeg default-jdk-headless ca-certificates curl gcc pkg-config meson ninja-build libsdl2-dev libavcodec-dev libavdevice-dev libavformat-dev libavutil-dev libswresample-dev libusb-1.0-0-dev && rm -rf /var/lib/apt/lists/*
+RUN apt-get update && apt-get install -y --no-install-recommends adb aapt apksigner zipalign ffmpeg default-jdk-headless ca-certificates openssl curl gcc pkg-config meson ninja-build libsdl2-dev libavcodec-dev libavdevice-dev libavformat-dev libavutil-dev libswresample-dev libusb-1.0-0-dev && rm -rf /var/lib/apt/lists/*
 RUN curl -fL https://github.com/Genymobile/scrcpy/archive/refs/tags/v3.3.1.tar.gz | tar xz -C /tmp && curl -fL https://github.com/Genymobile/scrcpy/releases/download/v3.3.1/scrcpy-server-v3.3.1 -o /tmp/scrcpy-server && meson setup /tmp/scrcpy-build /tmp/scrcpy-3.3.1 --buildtype=release -Dprebuilt_server=/tmp/scrcpy-server && ninja -C /tmp/scrcpy-build -j4 install && rm -rf /tmp/scrcpy*
 ENV ANDROID_HOME=/opt/android JAVA_HOME=/usr/lib/jvm/default-java APPIUM_HOME=/opt/appium
 RUN mkdir -p /opt/android/platform-tools && for tool in adb aapt aapt2 apksigner zipalign; do ln -s /usr/bin/$tool /opt/android/platform-tools/$tool; done && npm install -g appium@3.8.0 && appium driver install uiautomator2@8.7.0
@@ -61,6 +62,10 @@ export function android(options) {
                         path: "/spectest-android.mjs",
                         content: readFileSync(new URL("./android-runtime.mjs", import.meta.url), "utf8"),
                     },
+                    {
+                        path: "/spectest-android-trust.mjs",
+                        content: readFileSync(new URL("./android-trust.mjs", import.meta.url), "utf8"),
+                    },
                 ],
                 volumes: [
                     {
@@ -72,6 +77,7 @@ export function android(options) {
                 inputs: [apk],
                 env: {
                     ANDROID_SERIAL: `${g.key("device")}.internal:5555`,
+                    ANDROID_CA_PATH: ENVIRONMENT_CA_PATH,
                     ANDROID_ACTIVITY: `${options.package}/${options.activity}`,
                     ANDROID_SHOW_TOUCHES: options.showTouches === false ? "0" : "1",
                 },

package/dist/daemon.js

@@ -1,3 +1,4 @@
+import { ensureServiceNetwork, serviceIpv4Gateway } from "./harness/service-network.js";
 import { collectSecretRefs } from "./fake-upstream.js";
 import { phoneScope, phoneRecordingChunk, releasePhoneRecording } from "./phone.js";
 import { runWithBackgroundFailures } from "./harness/background-failures.js";
@@ -504,15 +505,6 @@ function qualifyImageRef(ref) {
         return `docker.io/${ref}`;
     return ref;
 }
-async function ensureNetwork() {
-    const inspect = await docker(["network", "inspect", NETWORK_NAME], 30_000);
-    if (inspect.code === 0)
-        return;
-    const create = await docker(["network", "create", NETWORK_NAME], 60_000);
-    if (create.code !== 0) {
-        throw new Error(`docker network create ${NETWORK_NAME} failed: ${create.stderr.trim() || create.stdout.trim()}`);
-    }
-}
 /** Host directory backing one volume mount. Rules (notably which volumes
  *  survive the delta-restore teardown) live in `harness/volume-paths.ts`. */
 function resolveHostPath(service, vol) {
@@ -1490,15 +1482,15 @@ async function bridgeGatewayIp() {
         "network",
         "inspect",
         "--format",
-        "{{(index .IPAM.Config 0).Gateway}}",
+        "{{json .IPAM.Config}}",
         NETWORK_NAME,
     ], 10_000);
     if (out.code !== 0) {
         throw new Error(`docker network inspect ${NETWORK_NAME} failed (rc=${out.code}): ${out.stderr.trim()}`);
     }
-    const ip = out.stdout.trim();
+    const ip = serviceIpv4Gateway(JSON.parse(out.stdout));
     if (!ip)
-        throw new Error(`no gateway IP returned for network ${NETWORK_NAME}`);
+        throw new Error(`no IPv4 gateway IP returned for network ${NETWORK_NAME}`);
     cachedGatewayIp = ip;
     return ip;
 }
@@ -2591,7 +2583,10 @@ async function bootstrapInner(prepared, identity) {
     // wouldn't need it — but the writes are sub-millisecond so we just
     // gate image prep behind both.
     await Promise.all([
-        ensureNetwork(),
+        (async () => {
+            await ensureServiceNetwork(NETWORK_NAME, cfg.network, docker, shx);
+            cachedGatewayIp = null;
+        })(),
         (async () => {
             await fs.mkdir(WORKSPACE, { recursive: true });
             // Never overwrite the project's own root `.dockerignore`. BuildKit

package/dist/harness/service-network.d.ts

@@ -0,0 +1,21 @@
+/** The service LAN lives entirely inside one VM and is cloned with it. */
+export interface ServiceNetworkOptions {
+    /** Add VM-private IPv6 addresses alongside IPv4 (no external IPv6 route). */
+    ipv6?: boolean;
+    /** Flood multicast within the service bridge, including IPv4/IPv6 mDNS. */
+    multicast?: boolean;
+}
+export declare const SERVICE_IPV6_SUBNET = "fd53:7065:6374::/64";
+type CommandResult = {
+    code: number;
+    stdout: string;
+    stderr: string;
+};
+type Docker = (args: string[], timeoutMs: number) => Promise<CommandResult>;
+export declare function validateServiceNetwork(options: ServiceNetworkOptions | undefined): void;
+export declare function ensureServiceNetwork(name: string, options: ServiceNetworkOptions | undefined, docker: Docker, command: (file: string, args: string[], timeoutMs: number) => Promise<CommandResult>): Promise<void>;
+/** Ingress and resolver listeners remain IPv4 on a dual-stack bridge. */
+export declare function serviceIpv4Gateway(config: {
+    Gateway?: string;
+}[]): string | undefined;
+export {};

package/dist/harness/service-network.js

@@ -0,0 +1,94 @@
+import { isIPv4 } from "node:net";
+// Identical in each VM, like the guest's IPv4 identity. Never advertise outside
+// the guest: siblings retain their sockets/addresses without sharing a LAN.
+export const SERVICE_IPV6_SUBNET = "fd53:7065:6374::/64";
+const MULTICAST_LABEL = "dev.specific.spectest.multicast";
+export function validateServiceNetwork(options) {
+    if (options === undefined)
+        return;
+    if (!options || typeof options !== "object" || Array.isArray(options))
+        throw new Error("network must be an object with optional ipv6 and multicast booleans");
+    for (const key of Object.keys(options)) {
+        if (key !== "ipv6" && key !== "multicast")
+            throw new Error(`unknown network option: ${key}`);
+        if (typeof options[key] !== "boolean")
+            throw new Error(`network.${key} must be a boolean`);
+    }
+}
+export async function ensureServiceNetwork(name, options, docker, command) {
+    validateServiceNetwork(options);
+    const ipv6 = options?.ipv6 === true;
+    const multicast = options?.multicast === true;
+    const run = async (args, timeoutMs = 30_000) => {
+        const result = await docker(args, timeoutMs);
+        if (result.code !== 0)
+            throw new Error(`docker ${args.join(" ")} failed: ${result.stderr.trim() || result.stdout.trim()}`);
+        return result;
+    };
+    const parse = (stdout) => {
+        const network = JSON.parse(stdout)?.[0];
+        if (!network || typeof network.Id !== "string")
+            throw new Error(`Invalid Docker network inspection for ${name}`);
+        return network;
+    };
+    const inspected = await docker(["network", "inspect", name], 30_000);
+    let network = inspected.code === 0 ? parse(inspected.stdout) : undefined;
+    let ipv4Pool;
+    if (network) {
+        const expectedSubnet = !ipv6 || network.IPAM?.Config?.some(c => c.Subnet === SERVICE_IPV6_SUBNET);
+        const matches = network.Driver === "bridge" && !!network.EnableIPv6 === ipv6 && expectedSubnet &&
+            (network.Labels?.[MULTICAST_LABEL] === "true") === multicast;
+        if (!matches) {
+            // Changing an empty stale project network is safe; never detach live
+            // endpoints, or replace an externally supplied network configuration.
+            if (name !== "spectest-net" || network.Driver !== "bridge" ||
+                (network.IPAM?.Driver && network.IPAM.Driver !== "default") ||
+                Object.keys(network.Options ?? {}).length > 0 ||
+                Object.keys(network.Containers ?? {}).length > 0) {
+                throw new Error(`Network ${name} is incompatible with network.ipv6=${ipv6}, network.multicast=${multicast}; start a fresh environment. Active or custom networks are never replaced.`);
+            }
+            // Preserve the old IPv4 identity: the independent DNS process may
+            // already have a listener bound to this bridge gateway.
+            ipv4Pool = network.IPAM?.Config?.find(c => c.Subnet && isIPv4(c.Subnet.split("/")[0]));
+            await run(["network", "rm", name]);
+            network = undefined;
+        }
+    }
+    if (!network) {
+        const args = ["network", "create"];
+        if (ipv4Pool?.Subnet) {
+            args.push("--subnet", ipv4Pool.Subnet);
+            if (ipv4Pool.Gateway)
+                args.push("--gateway", ipv4Pool.Gateway);
+        }
+        if (ipv6)
+            args.push("--ipv6", "--subnet", SERVICE_IPV6_SUBNET);
+        if (multicast)
+            args.push("--label", `${MULTICAST_LABEL}=true`);
+        args.push(name);
+        await run(args, 60_000);
+        if (multicast)
+            network = parse((await run(["network", "inspect", name])).stdout);
+    }
+    if (multicast && network) {
+        const bridge = network.Options?.["com.docker.network.bridge.name"] ?? `br-${network.Id.slice(0, 12)}`;
+        if (!/^[a-zA-Z0-9_.-]{1,15}$/.test(bridge))
+            throw new Error(`Invalid Docker bridge name: ${bridge}`);
+        // No external querier exists on this LAN. Flooding avoids membership
+        // expiration and discovery races after a paused snapshot is restored.
+        // Keep the setting scoped to this bridge; never alter host forwarding.
+        try {
+            // Use netlink: some supported VM runtimes mount sysfs read-only.
+            const result = await command("ip", ["link", "set", "dev", bridge, "type", "bridge", "mcast_snooping", "0"], 10_000);
+            if (result.code !== 0)
+                throw new Error(result.stderr.trim() || result.stdout.trim() || `ip exited ${result.code}`);
+        }
+        catch (error) {
+            throw new Error(`Cannot enable multicast on ${name} (${bridge}): ${error}`);
+        }
+    }
+}
+/** Ingress and resolver listeners remain IPv4 on a dual-stack bridge. */
+export function serviceIpv4Gateway(config) {
+    return config.find(c => c.Gateway && isIPv4(c.Gateway))?.Gateway;
+}

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { type ServiceNetworkOptions } from "./harness/service-network.js";
+export type { ServiceNetworkOptions } from "./harness/service-network.js";
 import type { InjectRule, SignConfig } from "./fake-upstream.js";
 export type { InjectRule, InjectMatch, StringMatch, SignConfig, AwsSigV4Sign } from "./fake-upstream.js";
 export type { Phone, PhoneOptions, CallOptions, SpeechOptions } from "./phone.js";
@@ -71,6 +73,8 @@ export interface EnvironmentConfig<S extends ServicesMap = ServicesMap> {
      * string used in `dependsOn` references.
      */
     services: S;
+    /** Private service LAN. IPv4 remains enabled; IPv6 and multicast are opt-in. */
+    network?: ServiceNetworkOptions;
     /** Sandbox timeout in seconds (default 1h). */
     timeoutSecs?: number;
     /** Display metadata only; entrypoints retain their author-declared order. */
@@ -1754,6 +1758,8 @@ export interface EnvironmentInput<SI extends InputServicesMap, F extends FakesMa
          * and use 000000 as the code". */
         instructions?: string;
     };
+    /** Private service LAN. IPv4 remains enabled; IPv6 and multicast are opt-in. */
+    network?: ServiceNetworkOptions;
     /** Sandbox timeout in seconds (default 1h). */
     timeoutSecs?: number;
     /** Fake servers — see {@link defineFake}. Keyed by stable name; the key

package/dist/index.js

@@ -1,3 +1,4 @@
+import { validateServiceNetwork } from "./harness/service-network.js";
 import { stripVTControlCharacters } from "node:util";
 import { resolveEntrypoints } from "./interactive.js";
 // Spectest SDK. The user's single `spectest/index.ts` calls
@@ -310,6 +311,7 @@ export function validateServiceImage(serviceName, input) {
     return image;
 }
 function validateEnvironmentConfig(config) {
+    validateServiceNetwork(config.network);
     const entries = Object.entries(config.services);
     const serviceNames = new Set(entries.map(([n]) => n));
     const claimedBy = new Map();

package/dist/resolver.js

@@ -25,6 +25,7 @@
 // from a kernel-chosen source (127.0.0.1), and glibc's resolver drops the
 // answer because its source doesn't match the queried server.
 import { createSocket } from "node:dgram";
+import { isIPv4 } from "node:net";
 import { request as httpRequest } from "node:http";
 import { readFile, stat } from "node:fs/promises";
 import { lookup } from "./harness/names-registry.js";
@@ -203,7 +204,7 @@ async function handleQuery(sock, msg, rinfo) {
                 ? await dockerLookupByName(name)
                 : await dockerLookupByAlias(name));
         if (ip) {
-            // For AAAA we still answer empty — Docker bridges are IPv4 only, but
+            // For AAAA we still answer empty — the ingress registry is IPv4, and
             // we own this name so libc should fall back to A instead of chasing
             // a stray upstream AAAA for the real public hostname.
             const resp = q.type === "A" ? aAnswer(query, q.name, ip) : emptyAnswer(query);
@@ -277,7 +278,7 @@ function bindListener(addr, fatalOnError) {
  * uses to reach the VM host. Null until the network exists. */
 async function bridgeGatewayIp() {
     const net = (await dockerGet(`/networks/${encodeURIComponent(NETWORK_NAME)}`));
-    const gw = net?.IPAM?.Config?.find((c) => c.Gateway)?.Gateway;
+    const gw = net?.IPAM?.Config?.find(c => c.Gateway && isIPv4(c.Gateway))?.Gateway;
     return gw && gw.length > 0 ? gw : null;
 }
 // Primary listener: the loopback nameserver. Fatal if it can't bind.

package/package.json

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

package/src/components/android-runtime.mjs

@@ -3,6 +3,7 @@ import http from "node:http";
 import { spawn, execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { mkdir, stat, open, rm } from "node:fs/promises";
+import { installAndroidTrust } from "./spectest-android-trust.mjs";
 const exec = promisify(execFile);
 const serial = process.env.ANDROID_SERIAL;
 const directory = "/recordings";
@@ -28,6 +29,7 @@ async function bootstrap() {
       "Android did not boot; the guest kernel needs Binder, DMA-BUF heaps and PSI enabled",
     );
   }
+  await installAndroidTrust(adb, process.env.ANDROID_CA_PATH);
   await adb("install", "-r", "/spectest/app.apk");
   await adb("shell", "settings", "put", "global", "private_dns_mode", "off");
   for (const setting of [

package/src/components/android-trust.mjs

@@ -0,0 +1,126 @@
+// Runtime-only trust provisioning for the private Android device. Never change
+// the image or disable certificate/hostname verification in the application.
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { mkdtemp, writeFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const exec = promisify(execFile);
+
+export const ANDROID_TRUST_SCRIPT = `#!/system/bin/sh
+set -eu
+cert=/data/local/tmp/spectest-ca.crt
+store=/data/local/tmp/spectest-system-cacerts
+system=/system/etc/security/cacerts
+apex=/apex/com.android.conscrypt/cacerts
+hash="$1"
+test "$(id -u)" = 0
+test -s "$cert"
+
+# Keep a private copy of the active Android root set, including its public CAs.
+# The directory and namespace mounts are part of the VM snapshot, not the image.
+if [ ! -d "$store" ]; then
+    original="$system"
+    if [ -d "$apex" ] && [ -n "$(ls -A "$apex")" ]; then original="$apex"; fi
+    copy=$(mktemp -d /data/local/tmp/spectest-cacerts.XXXXXX)
+    trap 'rm -rf "$copy"' EXIT
+    cp "$original"/* "$copy"/
+    mv "$copy" "$store"
+    trap - EXIT
+fi
+
+# Android uses the old OpenSSL subject hash, with numbered collisions. Never
+# overwrite a public root with the same subject hash, or duplicate our own CA.
+index=0
+while [ -f "$store/$hash.$index" ]; do
+    if cmp -s "$cert" "$store/$hash.$index"; then break; fi
+    index=$((index + 1))
+done
+cp "$cert" "$store/$hash.$index"
+chown 0:0 "$store" "$store"/*
+chmod 0755 "$store"
+chmod 0644 "$store"/*
+if [ "$(getenforce)" != Disabled ]; then
+    chcon u:object_r:system_file:s0 "$store" "$store"/*
+fi
+
+# Android 14 loads roots from Conscrypt's APEX. Each zygote has a private mount
+# namespace, inherited by new apps and the pre-forked USAP pool. Enter those
+# namespaces, including existing descendants, before the APK is launched.
+zygotes="$(pidof zygote zygote64 || true)"
+test -n "$zygotes" || { echo 'Android TLS: no zygote process found' >&2; exit 1; }
+# Mount each generation before enumerating its children. A process forked
+# after enumeration then inherits the mounted store, closing the USAP race.
+frontier="$zygotes"
+while [ -n "$frontier" ]; do
+    for pid in $frontier; do
+        [ -d "/proc/$pid" ] || continue
+        for target in "$system" "$apex"; do
+            [ -d "/proc/$pid/root$target" ] || continue
+            if ! cmp -s "$cert" "/proc/$pid/root$target/$hash.$index"; then
+                # setns alone can retain the caller's filesystem root.
+                if ! nsenter --mount="/proc/$pid/ns/mnt" -- chroot "/proc/$pid/root" mount --bind "$store" "$target"; then
+                    [ ! -d "/proc/$pid" ] && break
+                    echo "Android TLS: cannot install trust in process $pid" >&2
+                    exit 1
+                fi
+            fi
+        done
+    done
+    # Android 14's toybox has no awk. Walk with the system shell instead.
+    processes="$(ps -A -o PID,PPID)"
+    next=""
+    while read -r pid parent; do
+        case " $frontier " in *" $parent "*) next="$next $pid" ;; esac
+    done <<PROCESSES
+$processes
+PROCESSES
+    frontier="$next"
+done
+for pid in $zygotes; do
+    target="$system"
+    if [ -d "/proc/$pid/root$apex" ]; then target="$apex"; fi
+    cmp -s "$cert" "/proc/$pid/root$target/$hash.$index"
+done
+echo 'spectest-android-trust-ready'
+`;
+
+/** Install the environment CA before app installation/launch. Throws on failure. */
+export async function installAndroidTrust(adb, caPath, run = exec) {
+  try {
+    const { stdout } = await run("openssl", ["x509", "-in", caPath, "-subject_hash_old", "-noout"]);
+    const hash = stdout.trim();
+    if (!/^[a-f0-9]{8}$/.test(hash)) throw new Error("invalid CA subject hash");
+
+    let root = [];
+    if ((await adb("shell", "id", "-u")).stdout.trim() !== "0") {
+      try {
+        if ((await adb("shell", "su", "0", "id", "-u")).stdout.trim() !== "0") throw new Error("not root");
+        root = ["su", "0"];
+      } catch {
+        await adb("root");
+        await adb("wait-for-device");
+        if ((await adb("shell", "id", "-u")).stdout.trim() !== "0") {
+          throw new Error("the Android image must provide root ADB or su access");
+        }
+      }
+    }
+    const directory = await mkdtemp(join(tmpdir(), "spectest-android-trust-"));
+    try {
+      const script = join(directory, "trust.sh");
+      await writeFile(script, ANDROID_TRUST_SCRIPT);
+      await adb("push", caPath, "/data/local/tmp/spectest-ca.crt");
+      await adb("push", script, "/data/local/tmp/spectest-trust.sh");
+      const result = await adb("shell", ...root, "sh", "/data/local/tmp/spectest-trust.sh", hash);
+      if (!result.stdout.includes("spectest-android-trust-ready")) {
+        throw new Error("system CA provisioning did not confirm success");
+      }
+    } finally {
+      await rm(directory, { recursive: true, force: true });
+      await adb("shell", "rm", "-f", "/data/local/tmp/spectest-ca.crt", "/data/local/tmp/spectest-trust.sh").catch(() => {});
+    }
+  } catch (cause) {
+    throw new Error(`Android TLS trust provisioning failed: ${cause.message}`, { cause });
+  }
+}

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

@@ -0,0 +1,113 @@
+import { expect, test } from "bun:test";
+import { mkdtempSync, writeFileSync, mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { ANDROID_TRUST_SCRIPT, installAndroidTrust } from "./android-trust.mjs";
+
+test("Android CA provisioning requires confirmed installation and supports root ADB restart", async () => {
+  const calls: string[][] = [];
+  let rooted = false;
+  const adb = async (...args: string[]) => {
+    calls.push(args);
+    if (args[0] === "root") rooted = true;
+    if (args.includes("su")) throw new Error("no su");
+    return { stdout: args.includes("id") ? (rooted ? "0\n" : "2000\n") : "" };
+  };
+  await expect(installAndroidTrust(adb, "/fixture/ca.crt", async () => ({ stdout: "1234abcd\n" })))
+    .rejects.toThrow("did not confirm success");
+  expect(calls.findIndex(args => args[0] === "root")).toBeLessThan(calls.findIndex(args => args[0] === "push"));
+  expect(calls).toContainEqual(["wait-for-device"]);
+  expect(calls.at(-1)).toEqual(["shell", "rm", "-f", "/data/local/tmp/spectest-ca.crt", "/data/local/tmp/spectest-trust.sh"]);
+});
+
+test("invalid CA data fails before accessing Android", async () => {
+  let called = false;
+  await expect(installAndroidTrust(async () => { called = true; }, "/fixture/ca.crt", async () => ({ stdout: "not-a-certificate" })))
+    .rejects.toThrow("invalid CA subject hash");
+  expect(called).toBe(false);
+});
+
+const canMount = process.platform === "linux" && Bun.spawnSync(["sh", "-c", "command -v unshare >/dev/null && unshare -Urnm true"], { stderr: "ignore" }).exitCode === 0;
+if (process.env.SPECTEST_REQUIRE_ANDROID_TRUST_MOUNTS === "1" && !canMount) {
+  throw new Error("Android trust CI requires Linux user/mount namespaces (unshare -Urnm); refusing to skip mount coverage");
+}
+
+// Exercise real bind mounts and private zygote/child mount namespaces.
+// This is intentionally more than an assertion about the generated script.
+test.skipIf(!canMount)("Android trust preserves roots and hash collisions, reaches private app namespaces and is idempotent", async () => {
+  const directory = mkdtempSync(join(tmpdir(), "spectest-android-mounts-"));
+  for (const name of ["system", "apex", "bin"]) mkdirSync(join(directory, name));
+  writeFileSync(join(directory, "apex", "1234abcd.0"), "public root with the same subject hash\n");
+  writeFileSync(join(directory, "apex", "deadbeef.0"), "another public root\n");
+  writeFileSync(join(directory, "spectest-ca.crt"), "the environment CA\n");
+  writeFileSync(join(directory, "bin", "getenforce"), "#!/bin/sh\necho Disabled\n", { mode: 0o755 });
+  // Linux procps calls these fields lowercase; Android toybox uses uppercase.
+  writeFileSync(join(directory, "bin", "ps"), `#!/bin/sh
+set -eu
+snapshot=$(/bin/ps -A -o pid,ppid)
+if [ ! -e '${directory}/race.triggered' ]; then
+    touch '${directory}/race.triggered'
+    kill -USR1 $(cat '${directory}/zygote.pid')
+    while [ ! -e '${directory}/late.ready' ]; do sleep 0.01; done
+fi
+# The late app is deliberately absent from this process-list snapshot. It
+# must inherit the parent's trust even though it gets its own namespace.
+printf '%s\\n' "$snapshot"
+`, { mode: 0o755 });
+  writeFileSync(join(directory, "bin", "pidof"), `#!/bin/sh\ncat '${directory}/zygote.pid'\n`, { mode: 0o755 });
+  writeFileSync(join(directory, "trust.sh"), ANDROID_TRUST_SCRIPT
+    .replaceAll("/system/etc/security/cacerts", `${directory}/system`)
+    .replaceAll("/apex/com.android.conscrypt/cacerts", `${directory}/apex`)
+    .replaceAll("/data/local/tmp", directory));
+  writeFileSync(join(directory, "late.sh"), `#!/bin/sh
+set -eu
+mount --make-rprivate /
+touch '${directory}/late.ready'
+exec sleep 120
+`);
+  writeFileSync(join(directory, "zygote.sh"), `#!/bin/sh
+set -eu
+mount --make-rprivate /
+late_app() {
+    unshare -m sh '${directory}/late.sh' &
+    echo $! > '${directory}/late.pid'
+}
+trap late_app USR1
+echo $$ > '${directory}/zygote.pid'
+unshare -m sh -c 'mount --make-rprivate /; touch "${directory}/app.ready"; exec sleep 120' &
+echo $! > '${directory}/app.pid'
+while true; do wait || true; done
+`);
+  writeFileSync(join(directory, "verify.sh"), `#!/bin/sh
+set -eu
+export PATH='${directory}/bin':"$PATH":/usr/sbin:/sbin
+unshare -m sh '${directory}/zygote.sh' &
+child=$!
+trap 'kill "$child" $(cat "${directory}/app.pid" "${directory}/late.pid" 2>/dev/null) 2>/dev/null || true' EXIT
+while [ ! -f '${directory}/app.ready' ]; do sleep 0.01; done
+sh '${directory}/trust.sh' 1234abcd
+for pid in $(cat '${directory}/zygote.pid' '${directory}/app.pid' '${directory}/late.pid'); do
+    for store in system apex; do
+        cmp '${directory}/spectest-ca.crt' "/proc/$pid/root${directory}/$store/1234abcd.1"
+        test "$(cat "/proc/$pid/root${directory}/$store/1234abcd.0")" = 'public root with the same subject hash'
+        test "$(cat "/proc/$pid/root${directory}/$store/deadbeef.0")" = 'another public root'
+    done
+done
+before=$(wc -l < /proc/$child/mountinfo)
+sh '${directory}/trust.sh' 1234abcd
+after=$(wc -l < /proc/$child/mountinfo)
+test "$before" = "$after"
+test ! -e '${directory}/spectest-system-cacerts/1234abcd.2'
+# A populated shell trust store is insufficient without a usable zygote.
+: > '${directory}/zygote.pid'
+if sh '${directory}/trust.sh' 1234abcd; then exit 1; fi
+`);
+  try {
+    const child = Bun.spawn(["timeout", "10s", "unshare", "-Urnm", "sh", join(directory, "verify.sh")], { stdout: "pipe", stderr: "pipe" });
+    const [stdout, stderr, status] = await Promise.all([new Response(child.stdout).text(), new Response(child.stderr).text(), child.exited]);
+    expect({ status, stderr: stderr.replace("Android TLS: no zygote process found\n", "") }).toEqual({ status: 0, stderr: "" });
+    expect(stdout.match(/spectest-android-trust-ready/g)?.length).toBe(2);
+  } finally {
+    rmSync(directory, { recursive: true, force: true });
+  }
+}, 20_000);

package/src/components/android.test.ts

@@ -42,6 +42,7 @@ test("Android expands into two VM services with an APK input and private Appium/
     expect(tools.env?.ANDROID_SERIAL).toBe("phone-device.internal:5555");
     expect(tools.env?.ANDROID_ACTIVITY).toBe("com.example.app/.MainActivity");
     expect(tools.env?.ANDROID_SHOW_TOUCHES).toBe("1");
+    expect(tools.env?.ANDROID_CA_PATH).toBe(process.env.SPECTEST_CA_PATH ?? "/etc/spectest/ca.crt");
     expect(tools.inputs).toContain("app.apk");
     expect(tools.volumes).toContainEqual({
       source: apk,
@@ -50,6 +51,7 @@ test("Android expands into two VM services with an APK input and private Appium/
     });
     expect(tools.readyCheck).toMatchObject({ type: "http", port: 4725 });
     expect(tools.files?.[0].content).toContain("--no-window");
+    expect(tools.files?.map((file: { path: string }) => file.path)).toContain("/spectest-android-trust.mjs");
   } finally {
     rmSync(dir, { recursive: true, force: true });
   }

package/src/components/android.ts

@@ -3,6 +3,7 @@ import { posix } from "node:path";
 import { serviceGroup } from "../index.js";
 import { resolveExistingProjectPath } from "../project-files.js";
 import { androidApp, type AndroidApp, type AndroidRecordingOptions } from "../android.js";
+import { ENVIRONMENT_CA_PATH } from "../environment-ca.js";
 
 export interface AndroidOptions {
   /** Project-relative path to an APK built for the worker's native ABI. */
@@ -26,7 +27,7 @@ export interface AndroidOptions {
 }
 
 export const ANDROID_TOOLS_DOCKERFILE = `FROM node:22-bookworm-slim
-RUN apt-get update && apt-get install -y --no-install-recommends adb aapt apksigner zipalign ffmpeg default-jdk-headless ca-certificates curl gcc pkg-config meson ninja-build libsdl2-dev libavcodec-dev libavdevice-dev libavformat-dev libavutil-dev libswresample-dev libusb-1.0-0-dev && rm -rf /var/lib/apt/lists/*
+RUN apt-get update && apt-get install -y --no-install-recommends adb aapt apksigner zipalign ffmpeg default-jdk-headless ca-certificates openssl curl gcc pkg-config meson ninja-build libsdl2-dev libavcodec-dev libavdevice-dev libavformat-dev libavutil-dev libswresample-dev libusb-1.0-0-dev && rm -rf /var/lib/apt/lists/*
 RUN curl -fL https://github.com/Genymobile/scrcpy/archive/refs/tags/v3.3.1.tar.gz | tar xz -C /tmp && curl -fL https://github.com/Genymobile/scrcpy/releases/download/v3.3.1/scrcpy-server-v3.3.1 -o /tmp/scrcpy-server && meson setup /tmp/scrcpy-build /tmp/scrcpy-3.3.1 --buildtype=release -Dprebuilt_server=/tmp/scrcpy-server && ninja -C /tmp/scrcpy-build -j4 install && rm -rf /tmp/scrcpy*
 ENV ANDROID_HOME=/opt/android JAVA_HOME=/usr/lib/jvm/default-java APPIUM_HOME=/opt/appium
 RUN mkdir -p /opt/android/platform-tools && for tool in adb aapt aapt2 apksigner zipalign; do ln -s /usr/bin/$tool /opt/android/platform-tools/$tool; done && npm install -g appium@3.8.0 && appium driver install uiautomator2@8.7.0
@@ -91,6 +92,10 @@ export function android(options: AndroidOptions) {
             path: "/spectest-android.mjs",
             content: readFileSync(new URL("./android-runtime.mjs", import.meta.url), "utf8"),
           },
+          {
+            path: "/spectest-android-trust.mjs",
+            content: readFileSync(new URL("./android-trust.mjs", import.meta.url), "utf8"),
+          },
         ],
         volumes: [
           {
@@ -102,6 +107,7 @@ export function android(options: AndroidOptions) {
         inputs: [apk],
         env: {
           ANDROID_SERIAL: `${g.key("device")}.internal:5555`,
+          ANDROID_CA_PATH: ENVIRONMENT_CA_PATH,
           ANDROID_ACTIVITY: `${options.package}/${options.activity}`,
           ANDROID_SHOW_TOUCHES: options.showTouches === false ? "0" : "1",
         },

package/src/daemon.ts

@@ -1,3 +1,4 @@
+import { ensureServiceNetwork, serviceIpv4Gateway } from "./harness/service-network.js";
 import { collectSecretRefs } from "./fake-upstream.js";
 import { phoneScope, phoneRecordingChunk, releasePhoneRecording, type PhoneRecording } from "./phone.js";
 import { runWithBackgroundFailures } from "./harness/background-failures.js";
@@ -760,16 +761,6 @@ function qualifyImageRef(ref: string): string {
   return ref;
 }
 
-async function ensureNetwork(): Promise<void> {
-  const inspect = await docker(["network", "inspect", NETWORK_NAME], 30_000);
-  if (inspect.code === 0) return;
-  const create = await docker(["network", "create", NETWORK_NAME], 60_000);
-  if (create.code !== 0) {
-    throw new Error(
-      `docker network create ${NETWORK_NAME} failed: ${create.stderr.trim() || create.stdout.trim()}`,
-    );
-  }
-}
 
 /** Host directory backing one volume mount. Rules (notably which volumes
  *  survive the delta-restore teardown) live in `harness/volume-paths.ts`. */
@@ -1876,7 +1867,7 @@ async function bridgeGatewayIp(): Promise<string> {
       "network",
       "inspect",
       "--format",
-      "{{(index .IPAM.Config 0).Gateway}}",
+      "{{json .IPAM.Config}}",
       NETWORK_NAME,
     ],
     10_000,
@@ -1886,8 +1877,8 @@ async function bridgeGatewayIp(): Promise<string> {
       `docker network inspect ${NETWORK_NAME} failed (rc=${out.code}): ${out.stderr.trim()}`,
     );
   }
-  const ip = out.stdout.trim();
-  if (!ip) throw new Error(`no gateway IP returned for network ${NETWORK_NAME}`);
+  const ip = serviceIpv4Gateway(JSON.parse(out.stdout));
+  if (!ip) throw new Error(`no IPv4 gateway IP returned for network ${NETWORK_NAME}`);
   cachedGatewayIp = ip;
   return ip;
 }
@@ -3090,7 +3081,10 @@ async function bootstrapInner(prepared?: PreparedImages, identity?: string): Pro
   // wouldn't need it — but the writes are sub-millisecond so we just
   // gate image prep behind both.
   await Promise.all([
-    ensureNetwork(),
+    (async () => {
+      await ensureServiceNetwork(NETWORK_NAME, cfg.network, docker, shx);
+      cachedGatewayIp = null;
+    })(),
     (async () => {
       await fs.mkdir(WORKSPACE, { recursive: true });
       // Never overwrite the project's own root `.dockerignore`. BuildKit

package/src/harness/service-network.test.ts

@@ -0,0 +1,103 @@
+import { expect, test } from "bun:test";
+import { defineEnvironment } from "../index";
+import { ensureServiceNetwork, SERVICE_IPV6_SUBNET } from "./service-network";
+
+const id = "0123456789abcdef";
+const base = { Id: id, Driver: "bridge", EnableIPv6: false, Containers: {}, IPAM: { Driver: "default", Config: [] } };
+function fixture(existing: object | undefined) {
+  const calls: string[][] = [], writes: string[][] = [];
+  let network = existing;
+  return { calls, writes, async docker(args: string[]) {
+    calls.push(args);
+    if (args[1] === "inspect") return network ? { code: 0, stdout: JSON.stringify([network]), stderr: "" } : { code: 1, stdout: "", stderr: "missing" };
+    if (args[1] === "rm") network = undefined;
+    if (args[1] === "create") network = { ...base, EnableIPv6: args.includes("--ipv6"), Labels: args.includes("--label") ? { "dev.specific.spectest.multicast": "true" } : {} };
+    return { code: 0, stdout: id, stderr: "" };
+  }, async command(file: string, args: string[]) { writes.push([file, ...args]); return { code: 0, stdout: "", stderr: "" }; } };
+}
+
+test("default networks keep IPv4 creation and reuse behavior", async () => {
+  const f = fixture(undefined);
+  await ensureServiceNetwork("spectest-net", undefined, f.docker, f.command);
+  expect(f.calls).toEqual([["network", "inspect", "spectest-net"], ["network", "create", "spectest-net"]]);
+  expect(f.writes).toEqual([]);
+  const reused = fixture(base);
+  await ensureServiceNetwork("spectest-net", undefined, reused.docker, reused.command);
+  expect(reused.calls).toHaveLength(1);
+});
+
+test("dual stack creates the fixed ULA and scopes multicast to its bridge", async () => {
+  const f = fixture(undefined);
+  await ensureServiceNetwork("spectest-net", { ipv6: true, multicast: true }, f.docker, f.command);
+  expect(f.calls[1]).toEqual(["network", "create", "--ipv6", "--subnet", SERVICE_IPV6_SUBNET, "--label", "dev.specific.spectest.multicast=true", "spectest-net"]);
+  expect(f.writes).toEqual([["ip", "link", "set", "dev", `br-${id.slice(0, 12)}`, "type", "bridge", "mcast_snooping", "0"]]);
+});
+
+test("multicast supports IPv4 without requiring IPv6", async () => {
+  const f = fixture(undefined);
+  await ensureServiceNetwork("spectest-net", { multicast: true }, f.docker, f.command);
+  expect(f.calls[1]).not.toContain("--ipv6");
+  expect(f.writes).toHaveLength(1);
+});
+
+test("only an empty ordinary bridge can be migrated", async () => {
+  const f = fixture(base);
+  await ensureServiceNetwork("spectest-net", { ipv6: true }, f.docker, f.command);
+  expect(f.calls[1]).toEqual(["network", "rm", "spectest-net"]);
+  for (const [name, network] of [
+    ["spectest-net", { ...base, Containers: { live: {} } }],
+    ["custom", base],
+    ["spectest-net", { ...base, Driver: "macvlan" }],
+    ["spectest-net", { ...base, Options: { "com.docker.network.bridge.name": "custom0" } }],
+    ["spectest-net", { ...base, IPAM: { Driver: "plugin" } }],
+  ] as const) {
+    const live = fixture(network);
+    await expect(ensureServiceNetwork(name, { ipv6: true }, live.docker, live.command)).rejects.toThrow("never replaced");
+    expect(live.calls).toHaveLength(1);
+  }
+});
+
+test("incorrect IPv6 prefixes and mode downgrades are not silently reused", async () => {
+  for (const options of [{ ipv6: true }, {}]) {
+    const f = fixture({ ...base, EnableIPv6: true, Containers: { live: {} }, IPAM: { Config: [{ Subnet: "fd00::/64" }] } });
+    await expect(ensureServiceNetwork("spectest-net", options, f.docker, f.command)).rejects.toThrow("incompatible");
+  }
+});
+
+test("a matching live network is reused, multicast is reasserted", async () => {
+  const f = fixture({ ...base, EnableIPv6: true, Containers: { live: {} },
+    IPAM: { Config: [{ Subnet: SERVICE_IPV6_SUBNET }] }, Labels: { "dev.specific.spectest.multicast": "true" } });
+  await ensureServiceNetwork("spectest-net", { ipv6: true, multicast: true }, f.docker, f.command);
+  expect(f.calls).toHaveLength(1);
+  expect(f.writes).toHaveLength(1);
+});
+
+test("configuration rejects invalid options before boot", () => {
+  for (const network of [null, [], { ipv6: "true" }, { multicast: 1 }, { subnet: "anything" }]) {
+    expect(() => defineEnvironment({ name: "invalid", services: {}, network: network as any })).toThrow();
+  }
+  expect(defineEnvironment({ name: "valid", services: {}, network: { ipv6: true } }).config.network).toEqual({ ipv6: true });
+});
+
+test("multicast configuration errors fail setup rather than silently disabling discovery", async () => {
+  const f = fixture(undefined);
+  await expect(ensureServiceNetwork("spectest-net", { multicast: true }, f.docker, async () => { throw Error("read-only"); })).rejects.toThrow("Cannot enable multicast");
+});
+
+test("IPv4 ingress gateway is selected even when Docker lists IPv6 first", async () => {
+  const { serviceIpv4Gateway } = await import("./service-network");
+  expect(serviceIpv4Gateway([{ Gateway: "fd53:7065:6374::1" }, { Gateway: "172.18.0.1" }])).toBe("172.18.0.1");
+  expect(serviceIpv4Gateway([{ Gateway: "fd53:7065:6374::1" }])).toBeUndefined();
+});
+
+test("empty-network migration preserves the IPv4 gateway used by the DNS listener", async () => {
+  const f = fixture({ ...base, IPAM: { Driver: "default", Config: [{ Subnet: "172.18.0.0/16", Gateway: "172.18.0.1" }] } });
+  await ensureServiceNetwork("spectest-net", { ipv6: true }, f.docker, f.command);
+  expect(f.calls[2]).toEqual(["network", "create", "--subnet", "172.18.0.0/16", "--gateway", "172.18.0.1", "--ipv6", "--subnet", SERVICE_IPV6_SUBNET, "spectest-net"]);
+});
+
+test("a rejected netlink command fails setup with its diagnostic", async () => {
+  const f = fixture(undefined);
+  await expect(ensureServiceNetwork("spectest-net", { multicast: true }, f.docker,
+    async () => ({ code: 2, stdout: "", stderr: "RTNETLINK answers: Operation not permitted" }))).rejects.toThrow("Operation not permitted");
+});

package/src/harness/service-network.ts

@@ -0,0 +1,111 @@
+import { isIPv4 } from "node:net";
+
+/** The service LAN lives entirely inside one VM and is cloned with it. */
+export interface ServiceNetworkOptions {
+  /** Add VM-private IPv6 addresses alongside IPv4 (no external IPv6 route). */
+  ipv6?: boolean;
+  /** Flood multicast within the service bridge, including IPv4/IPv6 mDNS. */
+  multicast?: boolean;
+}
+
+// Identical in each VM, like the guest's IPv4 identity. Never advertise outside
+// the guest: siblings retain their sockets/addresses without sharing a LAN.
+export const SERVICE_IPV6_SUBNET = "fd53:7065:6374::/64";
+const MULTICAST_LABEL = "dev.specific.spectest.multicast";
+
+type CommandResult = { code: number; stdout: string; stderr: string };
+type Docker = (args: string[], timeoutMs: number) => Promise<CommandResult>;
+interface Network {
+  Id: string;
+  Driver: string;
+  EnableIPv6?: boolean;
+  IPAM?: { Driver?: string; Config?: { Subnet?: string; Gateway?: string }[] };
+  Options?: Record<string, string>;
+  Labels?: Record<string, string>;
+  Containers?: Record<string, unknown>;
+}
+
+export function validateServiceNetwork(options: ServiceNetworkOptions | undefined): void {
+  if (options === undefined) return;
+  if (!options || typeof options !== "object" || Array.isArray(options))
+    throw new Error("network must be an object with optional ipv6 and multicast booleans");
+  for (const key of Object.keys(options)) {
+    if (key !== "ipv6" && key !== "multicast") throw new Error(`unknown network option: ${key}`);
+    if (typeof options[key] !== "boolean") throw new Error(`network.${key} must be a boolean`);
+  }
+}
+
+export async function ensureServiceNetwork(
+  name: string,
+  options: ServiceNetworkOptions | undefined,
+  docker: Docker,
+  command: (file: string, args: string[], timeoutMs: number) => Promise<CommandResult>,
+): Promise<void> {
+  validateServiceNetwork(options);
+  const ipv6 = options?.ipv6 === true;
+  const multicast = options?.multicast === true;
+  const run = async (args: string[], timeoutMs = 30_000) => {
+    const result = await docker(args, timeoutMs);
+    if (result.code !== 0) throw new Error(`docker ${args.join(" ")} failed: ${result.stderr.trim() || result.stdout.trim()}`);
+    return result;
+  };
+  const parse = (stdout: string): Network => {
+    const network = JSON.parse(stdout)?.[0];
+    if (!network || typeof network.Id !== "string") throw new Error(`Invalid Docker network inspection for ${name}`);
+    return network;
+  };
+  const inspected = await docker(["network", "inspect", name], 30_000);
+  let network = inspected.code === 0 ? parse(inspected.stdout) : undefined;
+  let ipv4Pool: { Subnet?: string; Gateway?: string } | undefined;
+  if (network) {
+    const expectedSubnet = !ipv6 || network.IPAM?.Config?.some(c => c.Subnet === SERVICE_IPV6_SUBNET);
+    const matches = network.Driver === "bridge" && !!network.EnableIPv6 === ipv6 && expectedSubnet &&
+      (network.Labels?.[MULTICAST_LABEL] === "true") === multicast;
+    if (!matches) {
+      // Changing an empty stale project network is safe; never detach live
+      // endpoints, or replace an externally supplied network configuration.
+      if (name !== "spectest-net" || network.Driver !== "bridge" ||
+          (network.IPAM?.Driver && network.IPAM.Driver !== "default") ||
+          Object.keys(network.Options ?? {}).length > 0 ||
+          Object.keys(network.Containers ?? {}).length > 0) {
+        throw new Error(`Network ${name} is incompatible with network.ipv6=${ipv6}, network.multicast=${multicast}; start a fresh environment. Active or custom networks are never replaced.`);
+      }
+      // Preserve the old IPv4 identity: the independent DNS process may
+      // already have a listener bound to this bridge gateway.
+      ipv4Pool = network.IPAM?.Config?.find(c => c.Subnet && isIPv4(c.Subnet.split("/")[0]));
+      await run(["network", "rm", name]);
+      network = undefined;
+    }
+  }
+  if (!network) {
+    const args = ["network", "create"];
+    if (ipv4Pool?.Subnet) {
+      args.push("--subnet", ipv4Pool.Subnet);
+      if (ipv4Pool.Gateway) args.push("--gateway", ipv4Pool.Gateway);
+    }
+    if (ipv6) args.push("--ipv6", "--subnet", SERVICE_IPV6_SUBNET);
+    if (multicast) args.push("--label", `${MULTICAST_LABEL}=true`);
+    args.push(name);
+    await run(args, 60_000);
+    if (multicast) network = parse((await run(["network", "inspect", name])).stdout);
+  }
+  if (multicast && network) {
+    const bridge = network.Options?.["com.docker.network.bridge.name"] ?? `br-${network.Id.slice(0, 12)}`;
+    if (!/^[a-zA-Z0-9_.-]{1,15}$/.test(bridge)) throw new Error(`Invalid Docker bridge name: ${bridge}`);
+    // No external querier exists on this LAN. Flooding avoids membership
+    // expiration and discovery races after a paused snapshot is restored.
+    // Keep the setting scoped to this bridge; never alter host forwarding.
+    try {
+      // Use netlink: some supported VM runtimes mount sysfs read-only.
+      const result = await command("ip", ["link", "set", "dev", bridge, "type", "bridge", "mcast_snooping", "0"], 10_000);
+      if (result.code !== 0) throw new Error(result.stderr.trim() || result.stdout.trim() || `ip exited ${result.code}`);
+    } catch (error) {
+      throw new Error(`Cannot enable multicast on ${name} (${bridge}): ${error}`);
+    }
+  }
+}
+
+/** Ingress and resolver listeners remain IPv4 on a dual-stack bridge. */
+export function serviceIpv4Gateway(config: { Gateway?: string }[]): string | undefined {
+  return config.find(c => c.Gateway && isIPv4(c.Gateway))?.Gateway;
+}

package/src/index.ts

@@ -1,3 +1,5 @@
+import { validateServiceNetwork, type ServiceNetworkOptions } from "./harness/service-network.js";
+export type { ServiceNetworkOptions } from "./harness/service-network.js";
 import { stripVTControlCharacters } from "node:util";
 import type { LocatorAssertionRequest } from "./playwright-assertions.js";
 import type { InjectRule, SignConfig } from "./fake-upstream.js";
@@ -241,6 +243,8 @@ export interface EnvironmentConfig<S extends ServicesMap = ServicesMap> {
    * string used in `dependsOn` references.
    */
   services: S;
+  /** Private service LAN. IPv4 remains enabled; IPv6 and multicast are opt-in. */
+  network?: ServiceNetworkOptions;
   /** Sandbox timeout in seconds (default 1h). */
   timeoutSecs?: number;
   /** Display metadata only; entrypoints retain their author-declared order. */
@@ -1627,6 +1631,7 @@ export interface FakeContext {
 function validateEnvironmentConfig<S extends ServicesMap>(
   config: EnvironmentConfig<S>,
 ): void {
+  validateServiceNetwork(config.network);
   const entries = Object.entries(config.services);
   const serviceNames = new Set(entries.map(([n]) => n));
   const claimedBy = new Map<string, string>();
@@ -2520,6 +2525,8 @@ export interface EnvironmentInput<
      * and use 000000 as the code". */
     instructions?: string;
   };
+  /** Private service LAN. IPv4 remains enabled; IPv6 and multicast are opt-in. */
+  network?: ServiceNetworkOptions;
   /** Sandbox timeout in seconds (default 1h). */
   timeoutSecs?: number;
   /** Fake servers — see {@link defineFake}. Keyed by stable name; the key

package/src/resolver.ts

@@ -26,6 +26,7 @@
 // answer because its source doesn't match the queried server.
 
 import { createSocket, type RemoteInfo } from "node:dgram";
+import { isIPv4 } from "node:net";
 import { request as httpRequest } from "node:http";
 import { readFile, stat } from "node:fs/promises";
 import { lookup } from "./harness/names-registry.js";
@@ -241,7 +242,7 @@ async function handleQuery(
         : await dockerLookupByAlias(name));
 
     if (ip) {
-      // For AAAA we still answer empty — Docker bridges are IPv4 only, but
+      // For AAAA we still answer empty — the ingress registry is IPv4, and
       // we own this name so libc should fall back to A instead of chasing
       // a stray upstream AAAA for the real public hostname.
       const resp = q.type === "A" ? aAnswer(query, q.name, ip) : emptyAnswer(query);
@@ -320,7 +321,7 @@ async function bridgeGatewayIp(): Promise<string | null> {
   const net = (await dockerGet(`/networks/${encodeURIComponent(NETWORK_NAME)}`)) as
     | { IPAM?: { Config?: Array<{ Gateway?: string }> } }
     | null;
-  const gw = net?.IPAM?.Config?.find((c) => c.Gateway)?.Gateway;
+  const gw = net?.IPAM?.Config?.find(c => c.Gateway && isIPv4(c.Gateway))?.Gateway;
   return gw && gw.length > 0 ? gw : null;
 }