@loadmill/droid-cua 2.40.0 → 2.42.0

package/build/src/network/certificate-authority.js

@@ -0,0 +1,205 @@
+import { createHash, createPrivateKey, generateKeyPairSync, randomBytes, X509Certificate } from "node:crypto";
+import { mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import forge from "node-forge";
+export function getCertificatePaths(directory = path.join(os.homedir(), ".droid-cua", "network")) {
+    return {
+        directory,
+        certificate: path.join(directory, "ca.pem"),
+        privateKey: path.join(directory, "ca-key.pem"),
+        displayName: path.join(directory, "ca-name.json"),
+        preparedDevices: path.join(directory, "prepared-devices.json"),
+    };
+}
+function inspectCertificate(certificate, privateKey) {
+    const parsed = new X509Certificate(certificate);
+    if (!parsed.ca || !parsed.checkPrivateKey(createPrivateKey(privateKey))) {
+        throw new Error("The network CA certificate and private key do not match, or the certificate is not a CA.");
+    }
+    return {
+        certificate,
+        privateKey,
+        fingerprint: parsed.fingerprint256,
+        androidFileName: `${legacySubjectHash(certificate)}.0`,
+    };
+}
+function createCertificateAuthority() {
+    const { privateKey, publicKey } = generateKeyPairSync("rsa", {
+        modulusLength: 2048,
+        publicKeyEncoding: { type: "spki", format: "pem" },
+        privateKeyEncoding: { type: "pkcs8", format: "pem" },
+    });
+    const certificate = forge.pki.createCertificate();
+    certificate.publicKey = forge.pki.publicKeyFromPem(publicKey);
+    certificate.serialNumber = randomBytes(16).toString("hex").replace(/^./, "1");
+    certificate.validity.notBefore = new Date(Date.now() - 24 * 60 * 60 * 1000);
+    certificate.validity.notAfter = new Date(Date.now() + 10 * 365 * 24 * 60 * 60 * 1000);
+    const subject = [{ name: "commonName", value: `Droid CUA Root ${randomBytes(4).toString("hex")}` }];
+    certificate.setSubject(subject);
+    certificate.setIssuer(subject);
+    certificate.setExtensions([
+        { name: "basicConstraints", cA: true, critical: true },
+        { name: "keyUsage", keyCertSign: true, cRLSign: true, critical: true },
+        { name: "subjectKeyIdentifier" },
+    ]);
+    certificate.sign(forge.pki.privateKeyFromPem(privateKey), forge.md.sha256.create());
+    return inspectCertificate(forge.pki.certificateToPem(certificate), privateKey);
+}
+function generatedName() {
+    return `droid-network-${new Date().toISOString().slice(0, 10)}.pem`;
+}
+async function storeCertificateAuthority(paths, ca, name) {
+    await mkdir(paths.directory, { recursive: true, mode: 0o700 });
+    let previousFingerprint = null;
+    try {
+        previousFingerprint = new X509Certificate(await readFile(paths.certificate, "utf8")).fingerprint256;
+    }
+    catch (error) {
+        if (error?.code !== "ENOENT")
+            throw error;
+    }
+    const suffix = randomBytes(6).toString("hex");
+    const tempKey = `${paths.privateKey}.${suffix}.tmp`;
+    const tempCertificate = `${paths.certificate}.${suffix}.tmp`;
+    const tempName = `${paths.displayName}.${suffix}.tmp`;
+    try {
+        await writeFile(tempKey, ca.privateKey, { mode: 0o600, flag: "wx" });
+        await writeFile(tempCertificate, ca.certificate, { mode: 0o600, flag: "wx" });
+        await writeFile(tempName, JSON.stringify({ name }), { mode: 0o600, flag: "wx" });
+        await rename(tempKey, paths.privateKey);
+        await rename(tempCertificate, paths.certificate);
+        await rename(tempName, paths.displayName);
+        if (previousFingerprint !== ca.fingerprint)
+            await rm(paths.preparedDevices, { force: true });
+    }
+    finally {
+        await Promise.all([tempKey, tempCertificate, tempName].map((file) => rm(file, { force: true })));
+    }
+    return ca;
+}
+function parsePemBundle(pem) {
+    const blocks = [...pem.matchAll(/-----BEGIN ([A-Z ]+)-----[\s\S]*?-----END \1-----/g)];
+    const certificates = blocks.filter((block) => block[1] === "CERTIFICATE");
+    const keys = blocks.filter((block) => block[1].endsWith("PRIVATE KEY"));
+    if (certificates.length !== 1 || keys.length !== 1 || keys[0][1] === "ENCRYPTED PRIVATE KEY") {
+        throw new Error("Choose one PEM file containing a CA certificate and one unencrypted private key.");
+    }
+    const certificate = `${certificates[0][0]}\n`;
+    const privateKey = `${keys[0][0]}\n`;
+    let ca;
+    try {
+        ca = inspectCertificate(certificate, privateKey);
+    }
+    catch (error) {
+        throw new Error(`The PEM does not contain a matching CA certificate and private key. ${error.message}`);
+    }
+    const parsed = new X509Certificate(certificate);
+    const key = createPrivateKey(privateKey);
+    const usage = forge.pki.certificateFromPem(certificate).getExtension("keyUsage");
+    if (key.asymmetricKeyType !== "rsa" || !usage?.keyCertSign || parsed.issuer !== parsed.subject || !parsed.verify(parsed.publicKey)) {
+        throw new Error("The PEM must contain a self-signed RSA root CA that can sign certificates.");
+    }
+    const now = Date.now();
+    if (now < Date.parse(parsed.validFrom) || now >= Date.parse(parsed.validTo)) {
+        throw new Error("The CA certificate is not currently valid.");
+    }
+    return ca;
+}
+export async function loadCertificateAuthority(directory) {
+    const paths = getCertificatePaths(directory);
+    let certificate;
+    let privateKey;
+    try {
+        [certificate, privateKey] = await Promise.all([
+            readFile(paths.certificate, "utf8"),
+            readFile(paths.privateKey, "utf8"),
+        ]);
+    }
+    catch (error) {
+        if (error?.code === "ENOENT") {
+            throw new Error(`The Droid network CA is incomplete or missing in ${paths.directory}. Use Tools → Install Network Certificate in the desktop app to create it.`);
+        }
+        throw error;
+    }
+    return inspectCertificate(certificate, privateKey);
+}
+export async function getCertificateAuthorityStatus(directory) {
+    const paths = getCertificatePaths(directory);
+    const files = await Promise.all([paths.certificate, paths.privateKey].map(async (file) => {
+        try {
+            await stat(file);
+            return true;
+        }
+        catch (error) {
+            if (error?.code === "ENOENT")
+                return false;
+            throw error;
+        }
+    }));
+    if (files.every((exists) => !exists))
+        return { name: null, fingerprint: null };
+    const ca = await loadCertificateAuthority(directory);
+    let name;
+    try {
+        name = JSON.parse(await readFile(paths.displayName, "utf8")).name;
+    }
+    catch (error) {
+        if (error?.code !== "ENOENT")
+            throw error;
+        const { mtime } = await stat(paths.certificate);
+        name = `droid-network-${mtime.toISOString().slice(0, 10)}.pem`;
+    }
+    return { name, fingerprint: ca.fingerprint };
+}
+export async function importCertificateAuthority(pem, fileName, directory) {
+    if (!fileName.toLowerCase().endsWith(".pem"))
+        throw new Error("Choose a .pem file.");
+    const ca = parsePemBundle(pem);
+    return storeCertificateAuthority(getCertificatePaths(directory), ca, path.basename(fileName));
+}
+export async function generateCertificateAuthority(directory) {
+    return storeCertificateAuthority(getCertificatePaths(directory), createCertificateAuthority(), generatedName());
+}
+export async function removeCertificateAuthority(directory) {
+    const paths = getCertificatePaths(directory);
+    await Promise.all([paths.certificate, paths.privateKey, paths.displayName, paths.preparedDevices].map((file) => rm(file, { force: true })));
+}
+export async function ensureCertificateAuthority(directory) {
+    const paths = getCertificatePaths(directory);
+    await mkdir(paths.directory, { recursive: true, mode: 0o700 });
+    const existing = await Promise.all([paths.certificate, paths.privateKey].map(async (file) => {
+        try {
+            await stat(file);
+            return true;
+        }
+        catch (error) {
+            if (error?.code === "ENOENT")
+                return false;
+            throw error;
+        }
+    }));
+    if (existing.some(Boolean))
+        return loadCertificateAuthority(directory);
+    try {
+        await stat(paths.preparedDevices);
+        throw new Error(`The Droid network CA is missing from ${paths.directory}, but devices were prepared with it. Restore the original CA before installing another device.`);
+    }
+    catch (error) {
+        if (error?.code !== "ENOENT")
+            throw error;
+    }
+    return storeCertificateAuthority(paths, createCertificateAuthority(), generatedName());
+}
+export function legacySubjectHash(certificatePem) {
+    const certificate = forge.pki.certificateFromPem(certificatePem);
+    const asn1 = forge.pki.certificateToAsn1(certificate);
+    const tbs = asn1.value[0];
+    // TBSCertificate places the subject at index 5 when the optional version is present, otherwise 4.
+    const hasVersion = tbs.value[0].tagClass === forge.asn1.Class.CONTEXT_SPECIFIC;
+    const subject = tbs.value[hasVersion ? 5 : 4];
+    const subjectDer = Buffer.from(forge.asn1.toDer(subject).getBytes(), "binary");
+    const digest = createHash("md5").update(subjectDer).digest();
+    // Android's legacy OpenSSL hash reads the first four digest bytes as a little-endian word.
+    return digest.readUInt32LE(0).toString(16).padStart(8, "0");
+}

package/build/src/network/certificate-install.js

@@ -0,0 +1,242 @@
+import { execFile } from "node:child_process";
+import { readFile, writeFile, mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+import { getCertificatePaths, loadCertificateAuthority } from "./certificate-authority.js";
+const execFileAsync = promisify(execFile);
+const MISSING = "__DROID_CERT_MISSING__";
+const APEX_CERTS = "/apex/com.android.conscrypt/cacerts";
+const SYSTEM_CERTS = "/system/etc/security/cacerts";
+function commandError(error) {
+    const output = [error?.stderr, error?.stdout, error?.message].find((value) => typeof value === "string" && value.trim());
+    return String(output || "Command failed").trim();
+}
+async function run(file, args, options = {}) {
+    try {
+        return await execFileAsync(file, args, { timeout: 120000, maxBuffer: 4 * 1024 * 1024, ...options });
+    }
+    catch (error) {
+        throw new Error(`${file} ${args.slice(0, 3).join(" ")}: ${commandError(error)}`);
+    }
+}
+async function adb(adbPath, serial, args, options) {
+    return run(adbPath, ["-s", serial, ...args], options);
+}
+async function shell(adbPath, serial, script) {
+    return adb(adbPath, serial, ["shell", script]);
+}
+async function requireAndroidRoot(adbPath, serial) {
+    try {
+        await adb(adbPath, serial, ["root"]);
+        await adb(adbPath, serial, ["wait-for-device"]);
+        const { stdout } = await adb(adbPath, serial, ["shell", "id", "-u"]);
+        if (stdout.trim() !== "0")
+            throw new Error("ADB did not gain root access.");
+    }
+    catch (error) {
+        throw new Error(`This Android Emulator image does not provide the root access needed for system CA trust. Use a rootable AOSP or Google APIs image. ${commandError(error)}`);
+    }
+}
+async function readRemoteCertificate(adbPath, serial, directory, fileName, namespacePid) {
+    const remote = `${directory}/${fileName}`;
+    const inner = `[ -f ${remote} ] && cat ${remote} || printf ${MISSING}`;
+    const result = namespacePid
+        ? await shell(adbPath, serial, `nsenter --mount=/proc/${namespacePid}/ns/mnt -- sh -c \"${inner}\"`)
+        : await shell(adbPath, serial, inner);
+    return result.stdout.trim() === MISSING ? null : result.stdout;
+}
+export async function selectAndroidCertificateFileName(ca, readExisting) {
+    const hash = ca.androidFileName.slice(0, -2);
+    for (let index = 0; index < 100; index += 1) {
+        const name = `${hash}.${index}`;
+        const existing = await readExisting(name);
+        if (existing === null || existing.trim() === ca.certificate.trim())
+            return { name, alreadyPresent: existing !== null };
+    }
+    throw new Error("The Android certificate store has too many certificates with the same subject hash.");
+}
+async function chooseCertificateName(adbPath, serial, directory, ca) {
+    return selectAndroidCertificateFileName(ca, (name) => readRemoteCertificate(adbPath, serial, directory, name));
+}
+async function isTrustedInNamespaces(adbPath, serial, directory, ca, pids) {
+    const hash = ca.androidFileName.slice(0, -2);
+    const results = await Promise.all(pids.map(async (pid) => {
+        for (let index = 0; index < 100; index += 1) {
+            const current = await readRemoteCertificate(adbPath, serial, directory, `${hash}.${index}`, pid);
+            if (current?.trim() === ca.certificate.trim())
+                return true;
+            if (current === null)
+                return false;
+        }
+        return false;
+    }));
+    return results.every(Boolean);
+}
+export async function getAndroidAvdName(adbPath, serial) {
+    const { stdout } = await adb(adbPath, serial, ["emu", "avd", "name"]);
+    const name = stdout.split(/\r?\n/).map((line) => line.trim()).find((line) => line && line !== "OK");
+    if (!name)
+        throw new Error("Could not identify the Android Virtual Device for certificate preparation.");
+    return name;
+}
+async function readPreparedDevices() {
+    try {
+        return JSON.parse(await readFile(getCertificatePaths().preparedDevices, "utf8"));
+    }
+    catch (error) {
+        if (error?.code === "ENOENT")
+            return {};
+        throw error;
+    }
+}
+export async function hasPreparedAndroidCertificates() {
+    return Object.keys(await readPreparedDevices()).length > 0;
+}
+export async function recordPreparedAndroidCertificate(adbPath, serial, fingerprint) {
+    const prepared = await readPreparedDevices();
+    prepared[await getAndroidAvdName(adbPath, serial)] = fingerprint;
+    await writeFile(getCertificatePaths().preparedDevices, JSON.stringify(prepared, null, 2), { mode: 0o600 });
+}
+async function matchingPreparedAvd(adbPath, serial, ca = null) {
+    const prepared = await readPreparedDevices();
+    if (Object.keys(prepared).length === 0)
+        return null;
+    const avdName = await getAndroidAvdName(adbPath, serial);
+    if (!prepared[avdName])
+        return null;
+    const activeCa = ca || await loadCertificateAuthority();
+    if (prepared[avdName] !== activeCa.fingerprint) {
+        throw new Error(`The active network certificate has changed since ${avdName} was prepared. Run Tools → Install Network Certificate again.`);
+    }
+    return { avdName, ca: activeCa };
+}
+async function pushCertificate(adbPath, serial, ca, fileName) {
+    const tempDir = await mkdtemp(path.join(os.tmpdir(), "droid-network-ca-"));
+    const localPath = path.join(tempDir, fileName);
+    const remotePath = `/data/local/tmp/${fileName}`;
+    try {
+        await writeFile(localPath, ca.certificate, { mode: 0o600 });
+        await adb(adbPath, serial, ["push", localPath, remotePath]);
+        return remotePath;
+    }
+    finally {
+        await rm(tempDir, { recursive: true, force: true });
+    }
+}
+async function getZygotePids(adbPath, serial) {
+    const { stdout } = await shell(adbPath, serial, "pidof zygote zygote64 || true");
+    return [...new Set(stdout.trim().split(/\s+/).filter((value) => /^\d+$/.test(value)))];
+}
+async function requireMountCapabilities(adbPath, serial, directory) {
+    const { stdout } = await shell(adbPath, serial, `test -d '${directory}' && command -v nsenter && command -v mount && command -v chcon`);
+    if (!stdout.trim())
+        throw new Error("The certificate store or required mount tools are unavailable.");
+    const pids = await getZygotePids(adbPath, serial);
+    if (pids.length === 0)
+        throw new Error("No Android Zygote process was found.");
+    try {
+        await adb(adbPath, serial, ["shell", "nsenter", `--mount=/proc/${pids[0]}/ns/mnt`, "--", "true"]);
+    }
+    catch (error) {
+        throw new Error(`This emulator does not allow entry into application mount namespaces. ${commandError(error)}`);
+    }
+    return pids;
+}
+async function installMountedAndroid(adbPath, serial, ca, directory) {
+    let zygotes;
+    try {
+        zygotes = await requireMountCapabilities(adbPath, serial, directory);
+    }
+    catch (error) {
+        throw new Error(`This Android emulator cannot use Droid's system CA mount strategy. ${commandError(error)}`);
+    }
+    if (await isTrustedInNamespaces(adbPath, serial, directory, ca, zygotes))
+        return { changed: false };
+    const workDir = "/data/local/tmp/droid-cua-cacerts";
+    await shell(adbPath, serial, `mkdir -p '${workDir}' && cp '${directory}'/* '${workDir}/' && chmod 755 '${workDir}'`);
+    const { name } = await chooseCertificateName(adbPath, serial, workDir, ca);
+    const staged = await pushCertificate(adbPath, serial, ca, name);
+    await shell(adbPath, serial, `cp '${staged}' '${workDir}/${name}' && chown root:root '${workDir}'/* && chmod 644 '${workDir}'/* && chcon u:object_r:system_file:s0 '${workDir}' '${workDir}'/*`);
+    try {
+        // Zygote namespaces supply trust to newly launched apps.
+        for (const pid of zygotes) {
+            await adb(adbPath, serial, ["shell", "nsenter", `--mount=/proc/${pid}/ns/mnt`, "--", "mount", "--bind", workDir, directory]);
+        }
+    }
+    catch (error) {
+        throw new Error(`This emulator does not allow the required certificate-store bind mount. ${commandError(error)}`);
+    }
+    // Already running apps keep their own mount namespaces until restarted.
+    for (const pid of zygotes) {
+        const { stdout } = await shell(adbPath, serial, `ps -o PID -P ${pid} | tail -n +2`);
+        for (const appPid of stdout.trim().split(/\s+/).filter((value) => /^\d+$/.test(value))) {
+            try {
+                await adb(adbPath, serial, ["shell", "nsenter", `--mount=/proc/${appPid}/ns/mnt`, "--", "mount", "--bind", workDir, directory]);
+            }
+            catch { } // An app may exit while its mount is being updated.
+        }
+    }
+    const installed = await readRemoteCertificate(adbPath, serial, directory, name, zygotes[0]);
+    if (installed?.trim() !== ca.certificate.trim())
+        throw new Error("The Droid CA is not visible from Android's application mount namespace.");
+    return { changed: true };
+}
+export async function inspectNetworkDevice({ platform, deviceId, adbPath = process.env.DROID_CUA_ANDROID_ADB_PATH || "adb" }) {
+    if (platform === "ios") {
+        if (process.platform !== "darwin")
+            throw new Error("iOS Simulator certificate setup requires macOS.");
+        const { stdout } = await run("xcrun", ["simctl", "list", "devices", "--json"]);
+        const devices = JSON.parse(stdout).devices;
+        for (const [runtime, entries] of Object.entries(devices)) {
+            const simulator = entries.find((entry) => entry.udid === deviceId);
+            if (simulator)
+                return { platform, deviceId, osVersion: runtime.match(/iOS-([\d-]+)/)?.[1]?.replaceAll("-", ".") || runtime };
+        }
+        throw new Error("The connected device is not an available iOS Simulator.");
+    }
+    if (platform !== "android" || !/^emulator-\d+$/.test(deviceId)) {
+        throw new Error("Network certificate setup supports local iOS Simulators and Android Emulators only.");
+    }
+    const { stdout } = await adb(adbPath, deviceId, ["shell", "getprop", "ro.build.version.sdk"]);
+    const apiLevel = Number(stdout.trim());
+    if (!Number.isInteger(apiLevel) || apiLevel < 1) {
+        throw new Error(`Could not determine this Android Emulator's API level: ${stdout.trim() || "no value returned"}.`);
+    }
+    if (apiLevel > 36) {
+        const version = apiLevel === 37 ? "Android 17 (API 37)" : `Android API ${apiLevel}`;
+        throw new Error(`This emulator runs ${version}. Droid supports certificate setup through API 36, so installation stopped before checking root access. Use a rootable AOSP or Google APIs emulator on API 36 or earlier, without a Google Play image.`);
+    }
+    return { platform, deviceId, osVersion: `Android API ${apiLevel}`, apiLevel };
+}
+export async function installNetworkCertificate(target, ca, options = {}) {
+    if (target.platform === "ios") {
+        await run("xcrun", ["simctl", "keychain", target.deviceId, "add-root-cert", options.certificatePath]);
+        return { changed: true };
+    }
+    const adbPath = options.adbPath || process.env.DROID_CUA_ANDROID_ADB_PATH || "adb";
+    await requireAndroidRoot(adbPath, target.deviceId);
+    return installMountedAndroid(adbPath, target.deviceId, ca, target.apiLevel >= 34 ? APEX_CERTS : SYSTEM_CERTS);
+}
+export async function ensureCliAndroidCertificate(deviceId, ca, options = {}) {
+    const adbPath = options.adbPath || process.env.DROID_CUA_ANDROID_ADB_PATH || "adb";
+    const target = await inspectNetworkDevice({ platform: "android", deviceId, adbPath });
+    await requireAndroidRoot(adbPath, deviceId);
+    const directory = target.apiLevel >= 34 ? APEX_CERTS : SYSTEM_CERTS;
+    const pids = await requireMountCapabilities(adbPath, deviceId, directory);
+    if (await isTrustedInNamespaces(adbPath, deviceId, directory, ca, pids))
+        return { changed: false };
+    if (!await matchingPreparedAvd(adbPath, deviceId, ca)) {
+        throw new Error("The Android Emulator does not trust Droid's active network CA. Install it with Tools → Install Network Certificate or provision matching trust before running the CLI.");
+    }
+    return installNetworkCertificate(target, ca, { adbPath });
+}
+export async function reapplyPreparedAndroidCertificate(deviceId, options = {}) {
+    const adbPath = options.adbPath || process.env.DROID_CUA_ANDROID_ADB_PATH || "adb";
+    const prepared = await matchingPreparedAvd(adbPath, deviceId);
+    if (!prepared)
+        return null;
+    const target = await inspectNetworkDevice({ platform: "android", deviceId, adbPath });
+    const result = await installNetworkCertificate(target, prepared.ca, { adbPath });
+    return { ...result, avdName: prepared.avdName };
+}