@rynx-ai/daemon 0.1.0 → 0.1.9

package/dist/chrome-for-testing-store.js

@@ -0,0 +1,836 @@
+/**
+ * Immutable Chrome for Testing artifact storage for the Runtime Browser.
+ *
+ * This module never resolves a rolling release, searches PATH, discovers a
+ * system browser, or launches the installed executable. It accepts either an
+ * explicitly pinned build or an already-resolved official release.
+ */
+import { createHash } from "node:crypto";
+import { accessSync, chmodSync, closeSync, existsSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync, writeSync, } from "node:fs";
+import { constants as fsConstants } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import extractZipArchive from "@electron-internal/extract-zip";
+import { rynxHome } from "@rynx-ai/core";
+import Database from "better-sqlite3";
+const BUILD_OWNER_FILE = ".rynx-cft-owner.json";
+const STAGING_OWNER_FILE = ".rynx-cft-staging-owner.json";
+const ACTIVE_MANIFEST_FILE = "active.json";
+const STORE_LOCK_FILE = ".rynx-cft-store.sqlite";
+const MAX_METADATA_BYTES = 8 * 1024;
+const DEFAULT_MAX_ARCHIVE_BYTES = 1_024 * 1_024 * 1_024;
+const DEFAULT_STAGING_MAX_AGE_MS = 24 * 60 * 60 * 1_000;
+const STAGING_NAME_PATTERN = /^install-([A-Za-z0-9]{6})$/;
+const HEADLESS_PROFILE_NAME_PATTERN = /^session-([a-f0-9]{64})$/;
+const VERSION_PATTERN = /^\d{1,6}\.\d{1,6}\.\d{1,6}\.\d{1,6}$/;
+const SHA256_PATTERN = /^[a-f0-9]{64}$/;
+const HEADLESS_PROFILE_OWNER_FILE = ".rynx-headless-browser-profile.json";
+const HEADLESS_PROCESS_LEASE_FILE = ".rynx-headless-browser-process.json";
+const MAX_HEADLESS_METADATA_BYTES = 4 * 1_024;
+/** The support matrix is deliberately explicit; adding a host requires tests and a known layout. */
+export function resolveChromeForTestingPlatform(platform = process.platform, arch = process.arch) {
+    if (platform === "darwin" && arch === "arm64") {
+        return {
+            hostPlatform: "darwin-arm64",
+            artifactPlatform: "mac-arm64",
+            executableRelativePath: join("chrome-mac-arm64", "Google Chrome for Testing.app", "Contents", "MacOS", "Google Chrome for Testing"),
+        };
+    }
+    if (platform === "darwin" && arch === "x64") {
+        return {
+            hostPlatform: "darwin-x64",
+            artifactPlatform: "mac-x64",
+            executableRelativePath: join("chrome-mac-x64", "Google Chrome for Testing.app", "Contents", "MacOS", "Google Chrome for Testing"),
+        };
+    }
+    if (platform === "linux" && arch === "x64") {
+        return {
+            hostPlatform: "linux-x64",
+            artifactPlatform: "linux64",
+            executableRelativePath: join("chrome-linux64", "chrome"),
+        };
+    }
+    throw new Error(`unsupported Chrome for Testing host platform: ${platform}-${arch}`);
+}
+export function isChromeForTestingHostSupported(platform = process.platform, arch = process.arch) {
+    try {
+        resolveChromeForTestingPlatform(platform, arch);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function createChromeForTestingArtifactStore(options = {}) {
+    const platform = resolveChromeForTestingPlatform(options.platform ?? process.platform, options.arch ?? process.arch);
+    const rootDir = resolve(options.rootDir ?? join(rynxHome(), "cache", "browser", "chrome-for-testing"));
+    const fetchArtifact = options.fetchArtifact ?? defaultFetchArtifact;
+    const extractZip = options.extractZip ?? defaultExtractZip;
+    const maxArchiveBytes = options.maxArchiveBytes ?? DEFAULT_MAX_ARCHIVE_BYTES;
+    const now = options.now ?? (() => new Date());
+    const headlessProfileRoot = resolve(options.headlessProfileRoot ?? join(rynxHome(), "browser", "profiles", "headless-chromium"));
+    const isProcessLive = options.isProcessLive ?? defaultIsProcessLive;
+    let launchReservationTail = Promise.resolve();
+    if (!Number.isSafeInteger(maxArchiveBytes) || maxArchiveBytes <= 0) {
+        throw new Error("Chrome for Testing maxArchiveBytes must be a positive safe integer");
+    }
+    const readActiveBuild = () => {
+        const paths = ensureStorePaths(rootDir, platform.hostPlatform);
+        const activePath = join(paths.root, ACTIVE_MANIFEST_FILE);
+        if (!existsSync(activePath))
+            return undefined;
+        const active = parseActiveManifest(readSmallOwnedJson(activePath, "Chrome for Testing active manifest"), platform);
+        return requireInstalledBuild(buildPath(paths.buildsRoot, active.version, active.sha256), paths.buildsRoot, platform, {
+            version: active.version,
+            platform: active.artifactPlatform,
+            sha256: active.sha256,
+        });
+    };
+    const installDownloadedBuild = async (release, expectedSha256, installOptions) => {
+        const paths = ensureStorePaths(rootDir, platform.hostPlatform);
+        if (expectedSha256 !== undefined) {
+            const finalPath = buildPath(paths.buildsRoot, release.version, expectedSha256);
+            const existing = readInstalledBuild(finalPath, paths.buildsRoot, platform, {
+                ...release,
+                sha256: expectedSha256,
+            });
+            if (existing) {
+                writeActiveManifest(paths.root, existing);
+                return existing;
+            }
+        }
+        else {
+            // Reusing an active locally pinned build requires no second download. Its
+            // marker and content-addressed path are revalidated by readActiveBuild().
+            const active = readActiveBuild();
+            if (active?.version === release.version &&
+                active.artifactPlatform === release.platform &&
+                active.sourceUrl === release.url) {
+                return active;
+            }
+        }
+        throwIfAborted(installOptions.signal);
+        const transactionDir = mkdtempSync(join(paths.stagingRoot, "install-"));
+        const transactionName = basename(transactionDir);
+        const transactionId = parseStagingName(transactionName);
+        writeExclusiveJson(join(transactionDir, STAGING_OWNER_FILE), {
+            schemaVersion: 1,
+            kind: "rynx-chrome-for-testing-staging",
+            transactionId,
+        });
+        const archivePath = join(transactionDir, "artifact.zip");
+        const payloadPath = join(transactionDir, "payload");
+        try {
+            installOptions.onProgress?.(`downloading Chrome for Testing ${release.version} (${release.platform})`);
+            const sha256 = await downloadArchive({
+                url: release.url,
+                expectedSha256,
+                destination: archivePath,
+                fetchArtifact,
+                maxArchiveBytes,
+                signal: installOptions.signal,
+            });
+            throwIfAborted(installOptions.signal);
+            const build = { ...release, sha256 };
+            const finalPath = buildPath(paths.buildsRoot, build.version, build.sha256);
+            const existing = readInstalledBuild(finalPath, paths.buildsRoot, platform, build);
+            if (existing) {
+                writeActiveManifest(paths.root, existing);
+                return existing;
+            }
+            mkdirOwnedDirectory(payloadPath, paths.root);
+            await extractZip(archivePath, payloadPath);
+            throwIfAborted(installOptions.signal);
+            validateExecutable(payloadPath, platform.executableRelativePath);
+            const marker = {
+                schemaVersion: 1,
+                kind: "rynx-chrome-for-testing-build",
+                hostPlatform: platform.hostPlatform,
+                artifactPlatform: platform.artifactPlatform,
+                version: build.version,
+                sha256: build.sha256,
+                sourceUrl: build.url,
+                installedAt: now().toISOString(),
+            };
+            writeExclusiveJson(join(payloadPath, BUILD_OWNER_FILE), marker);
+            mkdirOwnedDirectory(dirname(finalPath), paths.root);
+            try {
+                renameSync(payloadPath, finalPath);
+            }
+            catch (error) {
+                // A concurrent installer may have promoted the same content-addressed
+                // build. Only accept it after the complete marker/executable check.
+                const concurrent = readInstalledBuild(finalPath, paths.buildsRoot, platform, build);
+                if (!concurrent)
+                    throw error;
+            }
+            const installed = requireInstalledBuild(finalPath, paths.buildsRoot, platform, build);
+            writeActiveManifest(paths.root, installed);
+            installOptions.onProgress?.(`installed Chrome for Testing ${build.version} (${build.sha256})`);
+            return installed;
+        }
+        finally {
+            // Cleanup is marker-gated. If the directory or marker was replaced,
+            // leave it for inspection instead of recursively deleting an unknown tree.
+            removeOwnedStaging(paths.stagingRoot, transactionDir, transactionId);
+        }
+    };
+    return {
+        async install(input, installOptions = {}) {
+            const build = validateBuildMetadata(input, platform);
+            return await withStoreLock(rootDir, () => installDownloadedBuild(build, build.sha256, installOptions));
+        },
+        async installResolved(input, installOptions = {}) {
+            const release = validateResolvedBuildMetadata(input, platform);
+            return await withStoreLock(rootDir, () => installDownloadedBuild(release, undefined, installOptions));
+        },
+        readActive() {
+            return readActiveBuild();
+        },
+        async reserveActiveForLaunch() {
+            let advanceQueue;
+            const previousReservation = launchReservationTail;
+            launchReservationTail = new Promise((resolveReservation) => {
+                advanceQueue = resolveReservation;
+            });
+            await previousReservation;
+            let lock;
+            try {
+                lock = acquireStoreLock(rootDir);
+            }
+            catch (error) {
+                advanceQueue();
+                throw error;
+            }
+            let build;
+            try {
+                build = readActiveBuild();
+            }
+            catch (error) {
+                try {
+                    releaseStoreLock(lock);
+                }
+                finally {
+                    advanceQueue();
+                }
+                throw error;
+            }
+            if (!build) {
+                try {
+                    releaseStoreLock(lock);
+                }
+                finally {
+                    advanceQueue();
+                }
+                return undefined;
+            }
+            let released = false;
+            return {
+                build,
+                release() {
+                    if (released)
+                        return;
+                    released = true;
+                    try {
+                        releaseStoreLock(lock);
+                    }
+                    finally {
+                        advanceQueue();
+                    }
+                },
+            };
+        },
+        pruneBuilds() {
+            const lock = acquireStoreLock(rootDir);
+            try {
+                const paths = ensureStorePaths(rootDir, platform.hostPlatform);
+                const builds = listInstalledBuilds(paths.buildsRoot, platform);
+                const active = readActiveBuild();
+                if (!active) {
+                    if (builds.length > 0) {
+                        throw new Error("Chrome for Testing builds cannot be pruned without a valid active build");
+                    }
+                    return { removedBuilds: [], retainedBuilds: [] };
+                }
+                const activeKey = installedBuildKey(active);
+                if (!builds.some((build) => installedBuildKey(build) === activeKey)) {
+                    throw new Error("Chrome for Testing active build is missing from its owned store");
+                }
+                // The most recently installed valid inactive build is the rollback
+                // build. Ties are deterministic so repeated cleans retain the same one.
+                const inactiveNewestFirst = builds
+                    .filter((build) => installedBuildKey(build) !== activeKey)
+                    .sort(compareInstalledNewestFirst);
+                const rollback = inactiveNewestFirst[0];
+                const retainedKeys = new Set([
+                    activeKey,
+                    ...(rollback ? [installedBuildKey(rollback)] : []),
+                    ...liveHeadlessBuildKeys(headlessProfileRoot, paths.buildsRoot, builds, isProcessLive),
+                ]);
+                const candidates = builds
+                    .filter((build) => !retainedKeys.has(installedBuildKey(build)))
+                    .sort(compareInstalledOldestFirst);
+                const removedBuilds = [];
+                for (const candidate of candidates) {
+                    // Re-read both mutable roots immediately before deletion. If another
+                    // process activates a build, or a Browser starts from an older build,
+                    // this clean pass loses authority to remove it.
+                    const currentActive = readActiveBuild();
+                    if (!currentActive || installedBuildKey(currentActive) !== activeKey) {
+                        throw new Error("Chrome for Testing active build changed while pruning");
+                    }
+                    const currentLive = liveHeadlessBuildKeys(headlessProfileRoot, paths.buildsRoot, builds, isProcessLive);
+                    if (currentLive.has(installedBuildKey(candidate)))
+                        continue;
+                    removeOwnedBuild(paths.buildsRoot, platform, candidate);
+                    removedBuilds.push(candidate);
+                }
+                const removedKeys = new Set(removedBuilds.map(installedBuildKey));
+                return {
+                    removedBuilds,
+                    retainedBuilds: builds.filter((build) => !removedKeys.has(installedBuildKey(build))),
+                };
+            }
+            finally {
+                releaseStoreLock(lock);
+            }
+        },
+        pruneStaging(pruneOptions = {}) {
+            const lock = acquireStoreLock(rootDir);
+            try {
+                const paths = ensureStorePaths(rootDir, platform.hostPlatform);
+                const olderThanMs = pruneOptions.olderThanMs ?? DEFAULT_STAGING_MAX_AGE_MS;
+                if (!Number.isSafeInteger(olderThanMs) || olderThanMs < 0) {
+                    throw new Error("Chrome for Testing staging age must be a non-negative safe integer");
+                }
+                const cutoff = now().getTime() - olderThanMs;
+                let removed = 0;
+                for (const entry of readdirSync(paths.stagingRoot)) {
+                    let transactionId;
+                    try {
+                        transactionId = parseStagingName(entry);
+                    }
+                    catch {
+                        continue;
+                    }
+                    const candidate = join(paths.stagingRoot, entry);
+                    let stat;
+                    try {
+                        stat = lstatSync(candidate);
+                    }
+                    catch {
+                        continue;
+                    }
+                    if (!stat.isDirectory() || stat.isSymbolicLink() || stat.mtimeMs > cutoff)
+                        continue;
+                    if (removeOwnedStaging(paths.stagingRoot, candidate, transactionId))
+                        removed += 1;
+                }
+                return removed;
+            }
+            finally {
+                releaseStoreLock(lock);
+            }
+        },
+    };
+}
+async function withStoreLock(rootDir, operation) {
+    const lock = acquireStoreLock(rootDir);
+    try {
+        return await operation();
+    }
+    finally {
+        releaseStoreLock(lock);
+    }
+}
+function acquireStoreLock(rootDir) {
+    mkdirOwnedDirectory(rootDir, rootDir);
+    const lockPath = join(rootDir, STORE_LOCK_FILE);
+    if (existsSync(lockPath)) {
+        const stat = lstatSync(lockPath);
+        if (!stat.isFile() || stat.isSymbolicLink()) {
+            throw new Error("Chrome for Testing store lock is not a direct regular file");
+        }
+    }
+    const connection = new Database(lockPath, { timeout: 0 });
+    try {
+        const stat = lstatSync(lockPath);
+        if (!stat.isFile() ||
+            stat.isSymbolicLink() ||
+            !isWithin(realpathSync(rootDir), realpathSync(lockPath))) {
+            throw new Error("Chrome for Testing store lock escapes its owned root");
+        }
+        chmodSync(lockPath, 0o600);
+        connection.pragma("busy_timeout = 0");
+        connection.exec("BEGIN EXCLUSIVE");
+        connection.exec("CREATE TABLE IF NOT EXISTS cft_store_guard (id INTEGER PRIMARY KEY)");
+        return connection;
+    }
+    catch (error) {
+        connection.close();
+        if (hasErrorCode(error, "SQLITE_BUSY") || hasErrorCode(error, "SQLITE_LOCKED")) {
+            throw new Error("Chrome for Testing store is busy in another process", { cause: error });
+        }
+        throw error;
+    }
+}
+function releaseStoreLock(connection) {
+    try {
+        connection.exec("ROLLBACK");
+    }
+    finally {
+        connection.close();
+    }
+}
+function ensureStorePaths(root, hostPlatform) {
+    mkdirOwnedDirectory(root, root);
+    const stagingRoot = join(root, "staging");
+    const buildsRoot = join(root, "builds", hostPlatform);
+    mkdirOwnedDirectory(stagingRoot, root);
+    mkdirOwnedDirectory(buildsRoot, root);
+    return { root, stagingRoot, buildsRoot };
+}
+function mkdirOwnedDirectory(path, containmentRoot) {
+    mkdirSync(path, { recursive: true, mode: 0o700 });
+    const stat = lstatSync(path);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) {
+        throw new Error(`Chrome for Testing storage path is not a direct directory: ${path}`);
+    }
+    chmodSync(path, 0o700);
+    const rootReal = realpathSync(containmentRoot);
+    const pathReal = realpathSync(path);
+    if (!isWithin(rootReal, pathReal)) {
+        throw new Error(`Chrome for Testing storage path escapes its root: ${path}`);
+    }
+}
+function validateBuildMetadata(input, platform) {
+    const download = validateDownloadMetadata(input, platform);
+    if (!SHA256_PATTERN.test(input.sha256)) {
+        throw new Error("Chrome for Testing SHA-256 must be 64 hexadecimal lowercase characters");
+    }
+    return { ...download, sha256: input.sha256 };
+}
+function validateResolvedBuildMetadata(input, platform) {
+    const release = validateDownloadMetadata(input, platform);
+    const expectedUrl = `https://storage.googleapis.com/chrome-for-testing-public/${release.version}/${release.platform}/chrome-${release.platform}.zip`;
+    if (release.url !== expectedUrl) {
+        throw new Error("resolved Chrome for Testing artifact URL must be an allowed official URL");
+    }
+    return release;
+}
+function validateDownloadMetadata(input, platform) {
+    if (!VERSION_PATTERN.test(input.version)) {
+        throw new Error("Chrome for Testing version must be an explicit four-part build version");
+    }
+    if (input.platform !== platform.artifactPlatform) {
+        throw new Error(`Chrome for Testing artifact platform ${input.platform} does not match host ${platform.hostPlatform}`);
+    }
+    let url;
+    try {
+        url = new URL(input.url);
+    }
+    catch {
+        throw new Error("Chrome for Testing artifact URL must be a valid HTTPS URL");
+    }
+    if (url.protocol !== "https:" || url.username || url.password) {
+        throw new Error("Chrome for Testing artifact URL must be a credential-free HTTPS URL");
+    }
+    return { version: input.version, platform: input.platform, url: url.href };
+}
+async function downloadArchive(options) {
+    const response = await options.fetchArtifact(options.url, { signal: options.signal });
+    if (!response.ok) {
+        throw new Error(`Chrome for Testing download failed: HTTP ${response.status}${response.statusText ? ` ${response.statusText}` : ""}`);
+    }
+    if (!response.body)
+        throw new Error("Chrome for Testing download returned no response body");
+    const length = parseContentLength(response.headers.get("content-length"));
+    if (length !== undefined && length > options.maxArchiveBytes) {
+        throw new Error(`Chrome for Testing archive exceeds ${options.maxArchiveBytes} bytes`);
+    }
+    const hash = createHash("sha256");
+    const descriptor = openSync(options.destination, "wx", 0o600);
+    let bytes = 0;
+    const reader = response.body.getReader();
+    try {
+        while (true) {
+            throwIfAborted(options.signal);
+            const next = await reader.read();
+            if (next.done)
+                break;
+            const chunk = Buffer.from(next.value);
+            bytes += chunk.byteLength;
+            if (bytes > options.maxArchiveBytes) {
+                throw new Error(`Chrome for Testing archive exceeds ${options.maxArchiveBytes} bytes`);
+            }
+            hash.update(chunk);
+            writeAll(descriptor, chunk);
+        }
+    }
+    finally {
+        closeSync(descriptor);
+        reader.releaseLock();
+    }
+    const actual = hash.digest("hex");
+    if (options.expectedSha256 !== undefined && actual !== options.expectedSha256) {
+        throw new Error(`Chrome for Testing SHA-256 mismatch: expected ${options.expectedSha256}, received ${actual}`);
+    }
+    return actual;
+}
+function writeAll(descriptor, value) {
+    let offset = 0;
+    while (offset < value.byteLength) {
+        const written = writeSync(descriptor, value, offset, value.byteLength - offset);
+        if (written <= 0)
+            throw new Error("Chrome for Testing archive write made no progress");
+        offset += written;
+    }
+}
+function validateExecutable(installPath, executableRelativePath) {
+    const executablePath = join(installPath, executableRelativePath);
+    let stat;
+    try {
+        stat = lstatSync(executablePath);
+    }
+    catch {
+        throw new Error(`Chrome for Testing archive is missing its executable: ${executableRelativePath}`);
+    }
+    if (!stat.isFile() || stat.isSymbolicLink()) {
+        throw new Error("Chrome for Testing executable must be a regular file");
+    }
+    const rootReal = realpathSync(installPath);
+    const executableReal = realpathSync(executablePath);
+    if (!isWithin(rootReal, executableReal)) {
+        throw new Error("Chrome for Testing executable resolves outside its owned build");
+    }
+    try {
+        accessSync(executablePath, fsConstants.X_OK);
+    }
+    catch {
+        throw new Error("Chrome for Testing executable is not executable");
+    }
+    return executablePath;
+}
+function readInstalledBuild(installPath, buildsRoot, platform, expected) {
+    if (!existsSync(installPath))
+        return undefined;
+    const stat = lstatSync(installPath);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) {
+        throw new Error(`Chrome for Testing build path is not an owned directory: ${installPath}`);
+    }
+    if (!isWithin(realpathSync(buildsRoot), realpathSync(installPath))) {
+        throw new Error("Chrome for Testing build path resolves outside its owned store");
+    }
+    const marker = parseBuildOwnerMarker(readSmallOwnedJson(join(installPath, BUILD_OWNER_FILE), "Chrome for Testing build ownership marker"), platform);
+    if (marker.version !== expected.version ||
+        marker.artifactPlatform !== expected.platform ||
+        marker.sha256 !== expected.sha256 ||
+        (expected.url !== undefined && marker.sourceUrl !== expected.url)) {
+        throw new Error("Chrome for Testing build ownership marker does not match pinned metadata");
+    }
+    return {
+        version: marker.version,
+        hostPlatform: marker.hostPlatform,
+        artifactPlatform: marker.artifactPlatform,
+        sha256: marker.sha256,
+        sourceUrl: marker.sourceUrl,
+        installedAt: marker.installedAt,
+        installPath,
+        executablePath: validateExecutable(installPath, platform.executableRelativePath),
+    };
+}
+function requireInstalledBuild(installPath, buildsRoot, platform, expected) {
+    const installed = readInstalledBuild(installPath, buildsRoot, platform, expected);
+    if (!installed)
+        throw new Error("Chrome for Testing active build is not installed");
+    return installed;
+}
+function listInstalledBuilds(buildsRoot, platform) {
+    const builds = [];
+    for (const versionEntry of readdirSync(buildsRoot, { withFileTypes: true })) {
+        if (!VERSION_PATTERN.test(versionEntry.name))
+            continue;
+        const versionPath = join(buildsRoot, versionEntry.name);
+        requireDirectChildDirectory(buildsRoot, versionPath, "version");
+        for (const digestEntry of readdirSync(versionPath, { withFileTypes: true })) {
+            if (!SHA256_PATTERN.test(digestEntry.name))
+                continue;
+            const installPath = join(versionPath, digestEntry.name);
+            requireDirectChildDirectory(versionPath, installPath, "build");
+            builds.push(requireInstalledBuild(installPath, buildsRoot, platform, {
+                version: versionEntry.name,
+                platform: platform.artifactPlatform,
+                sha256: digestEntry.name,
+            }));
+        }
+    }
+    return builds;
+}
+function liveHeadlessBuildKeys(profileRoot, buildsRoot, builds, isProcessLive) {
+    const live = new Set();
+    if (!existsSync(profileRoot))
+        return live;
+    const rootStat = lstatSync(profileRoot);
+    if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) {
+        throw new Error("Headless Browser profile root is not a direct directory");
+    }
+    const rootReal = realpathSync(profileRoot);
+    const buildsByExecutable = new Map(builds.map((build) => [resolve(build.executablePath), build]));
+    for (const entry of readdirSync(profileRoot, { withFileTypes: true })) {
+        const match = HEADLESS_PROFILE_NAME_PATTERN.exec(entry.name);
+        if (!match)
+            continue;
+        const profileDir = join(profileRoot, entry.name);
+        requireDirectChildDirectory(profileRoot, profileDir, "Headless Browser profile");
+        if (!isWithin(rootReal, realpathSync(profileDir))) {
+            throw new Error("Headless Browser profile escapes its root");
+        }
+        const marker = readSmallOwnedJson(join(profileDir, HEADLESS_PROFILE_OWNER_FILE), "Headless Browser profile ownership marker", MAX_HEADLESS_METADATA_BYTES);
+        if (!isRecord(marker) ||
+            marker.schemaVersion !== 1 ||
+            marker.kind !== "rynx-headless-browser-profile" ||
+            marker.executionBackend !== "headless-chromium" ||
+            typeof marker.sessionId !== "string" ||
+            marker.sessionId.length === 0 ||
+            createHash("sha256").update(marker.sessionId, "utf8").digest("hex") !== match[1]) {
+            throw new Error("invalid Headless Browser profile ownership marker");
+        }
+        const leasePath = join(profileDir, HEADLESS_PROCESS_LEASE_FILE);
+        if (!existsSync(leasePath))
+            continue;
+        const lease = parseHeadlessProcessLease(readSmallOwnedJson(leasePath, "Headless Browser process lease", MAX_HEADLESS_METADATA_BYTES));
+        if (lease.profileDir !== resolve(profileDir)) {
+            throw new Error("Headless Browser process lease targets another profile");
+        }
+        // Process existence is intentionally conservative here. PID reuse may
+        // retain an extra build, but it can never authorize deleting one still in
+        // use by the process recorded in a valid owned lease.
+        if (!isProcessLive(lease.pid))
+            continue;
+        const build = buildsByExecutable.get(resolve(lease.executablePath));
+        if (!build || !isWithin(realpathSync(buildsRoot), realpathSync(build.installPath))) {
+            throw new Error("live Headless Browser process lease targets an unowned build");
+        }
+        live.add(installedBuildKey(build));
+    }
+    return live;
+}
+function parseHeadlessProcessLease(value) {
+    if (!isRecord(value) ||
+        value.schemaVersion !== 1 ||
+        value.kind !== "rynx-headless-browser-process" ||
+        !Number.isSafeInteger(value.pid) ||
+        value.pid < 2 ||
+        value.processGroupId !== value.pid ||
+        typeof value.ownerToken !== "string" ||
+        !SHA256_PATTERN.test(value.ownerToken) ||
+        typeof value.executablePath !== "string" ||
+        !isAbsolute(value.executablePath) ||
+        typeof value.profileDir !== "string" ||
+        !isAbsolute(value.profileDir) ||
+        typeof value.startedAt !== "string" ||
+        !Number.isFinite(Date.parse(value.startedAt))) {
+        throw new Error("invalid Headless Browser process lease");
+    }
+    return value;
+}
+function removeOwnedBuild(buildsRoot, platform, build) {
+    const expectedPath = buildPath(buildsRoot, build.version, build.sha256);
+    if (resolve(build.installPath) !== resolve(expectedPath)) {
+        throw new Error("Chrome for Testing build path does not match its owned identity");
+    }
+    requireDirectChildDirectory(buildsRoot, dirname(expectedPath), "version");
+    requireDirectChildDirectory(dirname(expectedPath), expectedPath, "build");
+    requireInstalledBuild(expectedPath, buildsRoot, platform, {
+        version: build.version,
+        platform: build.artifactPlatform,
+        sha256: build.sha256,
+        url: build.sourceUrl,
+    });
+    rmSync(expectedPath, { recursive: true });
+}
+function requireDirectChildDirectory(parent, candidate, label) {
+    const stat = lstatSync(candidate);
+    if (dirname(resolve(candidate)) !== resolve(parent) ||
+        !stat.isDirectory() ||
+        stat.isSymbolicLink() ||
+        !isWithin(realpathSync(parent), realpathSync(candidate))) {
+        throw new Error(`Chrome for Testing ${label} path is not a direct owned directory`);
+    }
+}
+function installedBuildKey(build) {
+    return `${build.version}/${build.sha256}`;
+}
+function compareInstalledNewestFirst(left, right) {
+    const byTime = Date.parse(right.installedAt) - Date.parse(left.installedAt);
+    if (byTime !== 0)
+        return byTime;
+    return compareText(installedBuildKey(right), installedBuildKey(left));
+}
+function compareInstalledOldestFirst(left, right) {
+    return compareInstalledNewestFirst(right, left);
+}
+function compareText(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function parseBuildOwnerMarker(value, platform) {
+    if (!isRecord(value))
+        throw new Error("invalid Chrome for Testing build ownership marker");
+    if (value.schemaVersion !== 1 ||
+        value.kind !== "rynx-chrome-for-testing-build" ||
+        value.hostPlatform !== platform.hostPlatform ||
+        value.artifactPlatform !== platform.artifactPlatform ||
+        typeof value.version !== "string" ||
+        !VERSION_PATTERN.test(value.version) ||
+        typeof value.sha256 !== "string" ||
+        !SHA256_PATTERN.test(value.sha256) ||
+        typeof value.sourceUrl !== "string" ||
+        typeof value.installedAt !== "string" ||
+        !Number.isFinite(Date.parse(value.installedAt))) {
+        throw new Error("invalid Chrome for Testing build ownership marker");
+    }
+    const sourceUrl = validateBuildMetadata({
+        version: value.version,
+        platform: platform.artifactPlatform,
+        url: value.sourceUrl,
+        sha256: value.sha256,
+    }, platform).url;
+    return {
+        schemaVersion: 1,
+        kind: "rynx-chrome-for-testing-build",
+        hostPlatform: platform.hostPlatform,
+        artifactPlatform: platform.artifactPlatform,
+        version: value.version,
+        sha256: value.sha256,
+        sourceUrl,
+        installedAt: value.installedAt,
+    };
+}
+function writeActiveManifest(root, installed) {
+    const manifest = {
+        schemaVersion: 1,
+        kind: "rynx-chrome-for-testing-active",
+        hostPlatform: installed.hostPlatform,
+        artifactPlatform: installed.artifactPlatform,
+        version: installed.version,
+        sha256: installed.sha256,
+    };
+    const tempPath = join(root, `.active-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}.tmp`);
+    try {
+        writeExclusiveJson(tempPath, manifest);
+        renameSync(tempPath, join(root, ACTIVE_MANIFEST_FILE));
+    }
+    finally {
+        rmSync(tempPath, { force: true });
+    }
+}
+function parseActiveManifest(value, platform) {
+    if (!isRecord(value) ||
+        value.schemaVersion !== 1 ||
+        value.kind !== "rynx-chrome-for-testing-active" ||
+        value.hostPlatform !== platform.hostPlatform ||
+        value.artifactPlatform !== platform.artifactPlatform ||
+        typeof value.version !== "string" ||
+        !VERSION_PATTERN.test(value.version) ||
+        typeof value.sha256 !== "string" ||
+        !SHA256_PATTERN.test(value.sha256)) {
+        throw new Error("invalid Chrome for Testing active manifest");
+    }
+    return {
+        schemaVersion: 1,
+        kind: "rynx-chrome-for-testing-active",
+        hostPlatform: platform.hostPlatform,
+        artifactPlatform: platform.artifactPlatform,
+        version: value.version,
+        sha256: value.sha256,
+    };
+}
+function readSmallOwnedJson(path, label, maxBytes = MAX_METADATA_BYTES) {
+    let stat;
+    try {
+        stat = lstatSync(path);
+    }
+    catch {
+        throw new Error(`${label} is missing`);
+    }
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > maxBytes) {
+        throw new Error(`${label} is not a bounded regular file`);
+    }
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        throw new Error(`${label} is invalid JSON`);
+    }
+}
+function writeExclusiveJson(path, value) {
+    writeFileSync(path, `${JSON.stringify(value)}\n`, { flag: "wx", mode: 0o600 });
+    chmodSync(path, 0o600);
+}
+function removeOwnedStaging(stagingRoot, candidate, expectedTransactionId) {
+    try {
+        const stat = lstatSync(candidate);
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            return false;
+        const rootReal = realpathSync(stagingRoot);
+        const candidateReal = realpathSync(candidate);
+        if (dirname(resolve(candidate)) !== resolve(stagingRoot) || !isWithin(rootReal, candidateReal)) {
+            return false;
+        }
+        const marker = readSmallOwnedJson(join(candidate, STAGING_OWNER_FILE), "Chrome for Testing staging ownership marker");
+        if (!isRecord(marker) ||
+            marker.schemaVersion !== 1 ||
+            marker.kind !== "rynx-chrome-for-testing-staging" ||
+            marker.transactionId !== expectedTransactionId) {
+            return false;
+        }
+        rmSync(candidate, { recursive: true });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function parseStagingName(name) {
+    const match = STAGING_NAME_PATTERN.exec(name);
+    if (!match?.[1])
+        throw new Error("invalid Chrome for Testing staging transaction name");
+    return match[1];
+}
+function buildPath(buildsRoot, version, sha256) {
+    return join(buildsRoot, version, sha256);
+}
+function parseContentLength(raw) {
+    if (raw === null || !/^\d+$/.test(raw))
+        return undefined;
+    const value = Number(raw);
+    return Number.isSafeInteger(value) ? value : undefined;
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted)
+        throw new Error("Chrome for Testing installation aborted");
+}
+async function defaultFetchArtifact(url, init) {
+    return fetch(url, { signal: init.signal, redirect: "follow" });
+}
+async function defaultExtractZip(archivePath, destination) {
+    await extractZipArchive(archivePath, { dir: destination });
+}
+function defaultIsProcessLive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return !(error && typeof error === "object" && "code" in error && error.code === "ESRCH");
+    }
+}
+function hasErrorCode(error, code) {
+    return typeof error === "object" && error !== null && "code" in error && error.code === code;
+}
+function isWithin(root, candidate) {
+    const rel = relative(root, candidate);
+    return rel === "" || (!rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel));
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}