@specific.dev/spectest 0.124.0 → 0.126.0

package/dist/components/android-recording-state.mjs

@@ -0,0 +1,28 @@
+// scrcpy opens its output before receiving codec metadata or a video frame.
+// Only the patched recorder's first-frame signal makes an immediate stop safe.
+export const FIRST_VIDEO_FRAME = "SPECTEST_FIRST_VIDEO_FRAME";
+export const RECORDER_CAPABILITY = "spectest-first-frame-v1";
+
+export function requireRecorderCapability(version) {
+  if (!version.includes(RECORDER_CAPABILITY)) {
+    throw new Error("Android toolsImage needs scrcpy with the spectest-first-frame-v1 patch; rebuild it from ANDROID_TOOLS_DOCKERFILE");
+  }
+}
+
+export function observeRecorderOutput(record, chunk) {
+  record.log = (record.log + chunk).slice(-16000);
+  if (!record.started && record.log.includes(FIRST_VIDEO_FRAME)) {
+    record.started = true;
+    record.startedAtMs = Date.now();
+  }
+}
+
+export async function waitForRecorderFrame(record, timeoutMs = 10000) {
+  const deadline = Date.now() + timeoutMs;
+  while (true) {
+    if (record.error) throw new Error(`${record.error}: ${record.log}`);
+    if (record.started) return { startedAtMs: record.startedAtMs };
+    if (Date.now() >= deadline) throw new Error(`Recorder first video frame timed out: ${record.log}`);
+    await new Promise(resolve => setTimeout(resolve, Math.min(50, deadline - Date.now())));
+  }
+}

package/dist/components/android-runtime.mjs

@@ -1,8 +1,10 @@
 // Runs inside the Android tools container, in the same snapshotted VM.
 import http from "node:http";
+import { requireRecorderCapability, observeRecorderOutput, waitForRecorderFrame } from "./android-recording-state.mjs";
 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 +30,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 [
@@ -72,6 +75,7 @@ bootstrap().catch((error) => {
 });
 
 async function startRecording(body) {
+  requireRecorderCapability((await exec("scrcpy", ["--version"], { timeout: 5000 })).stdout);
   if (!/^[a-z0-9-]{1,100}$/.test(body.id)) throw new Error("invalid recording id");
   if (recordings.has(body.id)) throw new Error("recording already exists");
   if ([...recordings.values()].some((r) => !r.stopped))
@@ -119,19 +123,13 @@ async function startRecording(body) {
       record.error = error.message;
       resolve(-1);
     });
-    child.on("exit", (code) => {
+    child.on("close", (code) => {
       if (!record.stopped) record.error = `Recorder exited early (${code})`;
       resolve(code);
     });
   });
   for (const output of [child.stdout, child.stderr])
-    output.on("data", (b) => {
-      record.log = (record.log + b).slice(-16000);
-      if (!record.started && record.log.includes("Recording started")) {
-        record.started = true;
-        record.startedAtMs = Date.now();
-      }
-    });
+    output.on("data", (b) => observeRecorderOutput(record, b));
   record.guard = setInterval(async () => {
     if ((await stat(path).catch(() => ({ size: 0 }))).size > maxBytes) {
       record.error = "Recording exceeded 256 MiB";
@@ -139,12 +137,7 @@ async function startRecording(body) {
     }
   }, 1000);
   try {
-    for (let i = 0; i < 200; i++) {
-      if (record.error) throw new Error(`${record.error}: ${record.log}`);
-      if (record.started) return { startedAtMs: record.startedAtMs };
-      await sleep(50);
-    }
-    throw new Error(`Recorder startup timed out: ${record.log}`);
+    return await waitForRecorderFrame(record);
   } catch (error) {
     clearInterval(record.guard);
     record.stopped = true;

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: string;
 /** 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,9 +3,27 @@ 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";
+// Instrument the pinned recorder at the point its first real video packet is
+// retained. This follows the MP4 header and survives an immediate SIGINT.
+const recorderPatch = String.raw `from pathlib import Path
+p = Path('/tmp/scrcpy-3.3.1/app/src/recorder.c')
+s = p.read_text()
+a = '    int64_t pts_origin = AV_NOPTS_VALUE;'
+b = '            video_pkt_previous = video_pkt;'
+assert s.count(a) == 1 and s.count(b) == 1
+s = s.replace(a, a + '\n    bool spectest_first_frame = true;')
+s = s.replace(b, b + '\n            if (spectest_first_frame) {\n                LOGI("SPECTEST_FIRST_VIDEO_FRAME");\n                spectest_first_frame = false;\n            }')
+p.write_text(s)
+p = Path('/tmp/scrcpy-3.3.1/app/src/version.c')
+s = p.read_text()
+a = 'scrcpy_print_version(void) {'
+assert s.count(a) == 1
+p.write_text(s.replace(a, a + '\n    puts("spectest-first-frame-v1");'))`;
+const shellQuote = (value) => "'" + value.replaceAll("'", "'\\''") + "'";
 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 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*
+RUN apt-get update && apt-get install -y --no-install-recommends adb aapt apksigner zipalign ffmpeg default-jdk-headless ca-certificates openssl curl gcc python3 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 && python3 -c ${shellQuote(recorderPatch.replaceAll("\n", ";"))} && 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 +79,14 @@ export function android(options) {
                         path: "/spectest-android.mjs",
                         content: readFileSync(new URL("./android-runtime.mjs", import.meta.url), "utf8"),
                     },
+                    {
+                        path: "/android-recording-state.mjs",
+                        content: readFileSync(new URL("./android-recording-state.mjs", import.meta.url), "utf8"),
+                    },
+                    {
+                        path: "/spectest-android-trust.mjs",
+                        content: readFileSync(new URL("./android-trust.mjs", import.meta.url), "utf8"),
+                    },
                 ],
                 volumes: [
                     {
@@ -72,6 +98,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/components/index.d.ts

@@ -15,4 +15,4 @@ export { microsoft, type MicrosoftOptions } from "./microsoft.js";
 export { okta, type OktaOptions } from "./okta.js";
 export { replayFake, type ReplayFakeOptions, type ReplayFakeContext, type ReplayHandler, type ReplayKey, type WebSocketKey, type ReplayWebSocketMessage, type CassetteWebSocket, type CassetteWebSocketMessage, type WebSocketTiming, type ReplayRequest, type MatchKey, type JsonValue, type InjectRule, type InjectMatch, type StringMatch, type SignConfig, type AwsSigV4Sign, type ReplayHelpers, type ReplaySummary, type Cassette, type CassetteInteraction, type CassetteRequest, type CassetteResponse, type CassetteState, } from "./replayFake.js";
 export { electron, type ElectronOptions } from "./electron.js";
-export { android, type AndroidOptions } from "./android.js";
+export { android, ANDROID_TOOLS_DOCKERFILE, type AndroidOptions } from "./android.js";

package/dist/components/index.js

@@ -24,4 +24,4 @@ export { microsoft } from "./microsoft.js";
 export { okta } from "./okta.js";
 export { replayFake, } from "./replayFake.js";
 export { electron } from "./electron.js";
-export { android } from "./android.js";
+export { android, ANDROID_TOOLS_DOCKERFILE } from "./android.js";

package/package.json

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

package/src/components/android-recording-state.mjs

@@ -0,0 +1,28 @@
+// scrcpy opens its output before receiving codec metadata or a video frame.
+// Only the patched recorder's first-frame signal makes an immediate stop safe.
+export const FIRST_VIDEO_FRAME = "SPECTEST_FIRST_VIDEO_FRAME";
+export const RECORDER_CAPABILITY = "spectest-first-frame-v1";
+
+export function requireRecorderCapability(version) {
+  if (!version.includes(RECORDER_CAPABILITY)) {
+    throw new Error("Android toolsImage needs scrcpy with the spectest-first-frame-v1 patch; rebuild it from ANDROID_TOOLS_DOCKERFILE");
+  }
+}
+
+export function observeRecorderOutput(record, chunk) {
+  record.log = (record.log + chunk).slice(-16000);
+  if (!record.started && record.log.includes(FIRST_VIDEO_FRAME)) {
+    record.started = true;
+    record.startedAtMs = Date.now();
+  }
+}
+
+export async function waitForRecorderFrame(record, timeoutMs = 10000) {
+  const deadline = Date.now() + timeoutMs;
+  while (true) {
+    if (record.error) throw new Error(`${record.error}: ${record.log}`);
+    if (record.started) return { startedAtMs: record.startedAtMs };
+    if (Date.now() >= deadline) throw new Error(`Recorder first video frame timed out: ${record.log}`);
+    await new Promise(resolve => setTimeout(resolve, Math.min(50, deadline - Date.now())));
+  }
+}

package/src/components/android-runtime.mjs

@@ -1,8 +1,10 @@
 // Runs inside the Android tools container, in the same snapshotted VM.
 import http from "node:http";
+import { requireRecorderCapability, observeRecorderOutput, waitForRecorderFrame } from "./android-recording-state.mjs";
 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 +30,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 [
@@ -72,6 +75,7 @@ bootstrap().catch((error) => {
 });
 
 async function startRecording(body) {
+  requireRecorderCapability((await exec("scrcpy", ["--version"], { timeout: 5000 })).stdout);
   if (!/^[a-z0-9-]{1,100}$/.test(body.id)) throw new Error("invalid recording id");
   if (recordings.has(body.id)) throw new Error("recording already exists");
   if ([...recordings.values()].some((r) => !r.stopped))
@@ -119,19 +123,13 @@ async function startRecording(body) {
       record.error = error.message;
       resolve(-1);
     });
-    child.on("exit", (code) => {
+    child.on("close", (code) => {
       if (!record.stopped) record.error = `Recorder exited early (${code})`;
       resolve(code);
     });
   });
   for (const output of [child.stdout, child.stderr])
-    output.on("data", (b) => {
-      record.log = (record.log + b).slice(-16000);
-      if (!record.started && record.log.includes("Recording started")) {
-        record.started = true;
-        record.startedAtMs = Date.now();
-      }
-    });
+    output.on("data", (b) => observeRecorderOutput(record, b));
   record.guard = setInterval(async () => {
     if ((await stat(path).catch(() => ({ size: 0 }))).size > maxBytes) {
       record.error = "Recording exceeded 256 MiB";
@@ -139,12 +137,7 @@ async function startRecording(body) {
     }
   }, 1000);
   try {
-    for (let i = 0; i < 200; i++) {
-      if (record.error) throw new Error(`${record.error}: ${record.log}`);
-      if (record.started) return { startedAtMs: record.startedAtMs };
-      await sleep(50);
-    }
-    throw new Error(`Recorder startup timed out: ${record.log}`);
+    return await waitForRecorderFrame(record);
   } catch (error) {
     clearInterval(record.guard);
     record.stopped = true;

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 });
   }
@@ -66,3 +68,62 @@ test("bad dimensions and identifiers fail before image builds", () => {
     android({ apk: "spectest/tests/app.apk", package: "com.example", activity: ".MainActivity" }),
   ).toThrow("invalidate snapshots");
 });
+
+test("recorder waits for a retained first frame before an immediate stop, including split output", async () => {
+  const { spawn } = await import("node:child_process");
+  const { observeRecorderOutput, waitForRecorderFrame } = await import("./android-recording-state.mjs");
+  // Opening the output is deliberately separate from receiving the frame.
+  // This models scrcpy's static-screen path: only SIGINT flushes the last frame.
+  const child = spawn("node", ["-e", `
+    let retained = false;
+    process.on('SIGINT', () => {
+      process.stdout.write(retained ? 'VALID_VIDEO_WITH_TRAILER' : 'INVALID_EMPTY_VIDEO');
+      process.exit(retained ? 0 : 1);
+    });
+    process.stdin.once('data', () => {
+      retained = true;
+      process.stdout.write('SPECTEST_FIRST_VIDEO_');
+      setImmediate(() => process.stdout.write('FRAME\\n'));
+    });
+    process.stdout.write('Recording started to mp4 file: fixture.mp4\\n');
+  `]);
+  const record = { log: "", error: null as string | null, started: false, startedAtMs: 0 };
+  let opened!: () => void;
+  const outputOpened = new Promise<void>(resolve => { opened = resolve; });
+  child.stdout.on("data", chunk => {
+    observeRecorderOutput(record, chunk);
+    if (record.log.includes("Recording started")) opened();
+  });
+  const closed = new Promise<number | null>(resolve => child.on("close", resolve));
+  try {
+    await outputOpened;
+    let ready = false;
+    const waiting = waitForRecorderFrame(record).then(value => { ready = true; return value; });
+    await new Promise(resolve => setImmediate(resolve));
+    expect(ready).toBe(false);
+    expect(record.started).toBe(false);
+    const frameRequested = Date.now();
+    child.stdin.write("deliver first frame");
+    const result = await waiting;
+    expect(result.startedAtMs).toBeGreaterThanOrEqual(frameRequested);
+    child.kill("SIGINT");
+    expect(await closed).toBe(0);
+    expect(record.log).toContain("VALID_VIDEO_WITH_TRAILER");
+    expect(record.log).not.toContain("INVALID_EMPTY_VIDEO");
+  } finally {
+    child.kill("SIGKILL");
+    await closed;
+  }
+});
+
+test("recorder rejects missing frames, early exit and unpatched custom tools explicitly", async () => {
+  const { requireRecorderCapability, observeRecorderOutput, waitForRecorderFrame } = await import("./android-recording-state.mjs");
+  expect(() => requireRecorderCapability("scrcpy 3.3.1\n")).toThrow("rebuild it from ANDROID_TOOLS_DOCKERFILE");
+  expect(() => requireRecorderCapability("scrcpy 3.3.1\nspectest-first-frame-v1\n")).not.toThrow();
+  const record = { log: "", error: null as string | null, started: false, startedAtMs: 0 };
+  observeRecorderOutput(record, "Recording started to mp4 file: empty.mp4\n");
+  await expect(waitForRecorderFrame(record, 20)).rejects.toThrow("first video frame timed out");
+  record.error = "Recorder exited early (1)";
+  observeRecorderOutput(record, "SPECTEST_FIRST_VIDEO_FRAME\n");
+  await expect(waitForRecorderFrame(record)).rejects.toThrow("Recorder exited early");
+});

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. */
@@ -25,9 +26,27 @@ export interface AndroidOptions {
   dependsOn?: string[];
 }
 
+// Instrument the pinned recorder at the point its first real video packet is
+// retained. This follows the MP4 header and survives an immediate SIGINT.
+const recorderPatch = String.raw`from pathlib import Path
+p = Path('/tmp/scrcpy-3.3.1/app/src/recorder.c')
+s = p.read_text()
+a = '    int64_t pts_origin = AV_NOPTS_VALUE;'
+b = '            video_pkt_previous = video_pkt;'
+assert s.count(a) == 1 and s.count(b) == 1
+s = s.replace(a, a + '\n    bool spectest_first_frame = true;')
+s = s.replace(b, b + '\n            if (spectest_first_frame) {\n                LOGI("SPECTEST_FIRST_VIDEO_FRAME");\n                spectest_first_frame = false;\n            }')
+p.write_text(s)
+p = Path('/tmp/scrcpy-3.3.1/app/src/version.c')
+s = p.read_text()
+a = 'scrcpy_print_version(void) {'
+assert s.count(a) == 1
+p.write_text(s.replace(a, a + '\n    puts("spectest-first-frame-v1");'))`;
+const shellQuote = (value: string) => "'" + value.replaceAll("'", "'\\''") + "'";
+
 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 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*
+RUN apt-get update && apt-get install -y --no-install-recommends adb aapt apksigner zipalign ffmpeg default-jdk-headless ca-certificates openssl curl gcc python3 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 && python3 -c ${shellQuote(recorderPatch.replaceAll("\n", ";"))} && 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 +110,14 @@ export function android(options: AndroidOptions) {
             path: "/spectest-android.mjs",
             content: readFileSync(new URL("./android-runtime.mjs", import.meta.url), "utf8"),
           },
+          {
+            path: "/android-recording-state.mjs",
+            content: readFileSync(new URL("./android-recording-state.mjs", import.meta.url), "utf8"),
+          },
+          {
+            path: "/spectest-android-trust.mjs",
+            content: readFileSync(new URL("./android-trust.mjs", import.meta.url), "utf8"),
+          },
         ],
         volumes: [
           {
@@ -102,6 +129,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/components/index.ts

@@ -111,4 +111,4 @@ export {
 } from "./replayFake.js";
 export { electron, type ElectronOptions } from "./electron.js";
 
-export { android, type AndroidOptions } from "./android.js";
+export { android, ANDROID_TOOLS_DOCKERFILE, type AndroidOptions } from "./android.js";