@hue-run/sdk 0.3.2 → 0.4.2

package/dist/setup/installation.js

@@ -0,0 +1,605 @@
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+import { execFile } from "node:child_process";
+import { constants } from "node:fs";
+import { chmod, lstat, mkdir, open, readFile, rename, unlink } from "node:fs/promises";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { validSetupCredentialIdentity } from "./credential.js";
+const MAX_FILE_BYTES = 32 * 1024;
+const IGNORE_RULES = [
+    ".hue/installation-*.json",
+    ".hue/.installation-*.tmp",
+    ".hue/claim-handoff-*.html",
+    ".hue/.claim-handoff-*.tmp",
+    ".hue/application-evidence-*.json",
+    ".hue/.application-evidence-*.tmp",
+    ".hue/application-evidence-*.tmp",
+];
+const LOCAL_IGNORE_RULES = [
+    "installation-*.json",
+    ".installation-*.tmp",
+    "claim-handoff-*.html",
+    ".claim-handoff-*.tmp",
+    "application-evidence-*.json",
+    ".application-evidence-*.tmp",
+    "application-evidence-*.tmp",
+];
+async function gitDiagnostic(root, args, input) {
+    // Repository discovery must not be redirected to another index/worktree by inherited Git options.
+    const environment = Object.fromEntries(Object.entries(process.env).filter(([name]) => !name.startsWith("GIT_")));
+    return new Promise((resolvePromise, reject) => {
+        const child = execFile("git", ["--no-optional-locks", "-c", "core.fsmonitor=false", ...args], {
+            cwd: root,
+            env: { ...environment, GIT_TERMINAL_PROMPT: "0" },
+            shell: false,
+            windowsHide: true,
+            timeout: 5_000,
+            killSignal: "SIGKILL",
+            maxBuffer: 64 * 1024,
+            encoding: "utf8",
+        }, (error, output) => {
+            if (error && error.code !== 1) {
+                reject(new Error("Refusing setup because private-file Git protection could not be checked"));
+                return;
+            }
+            resolvePromise({ code: error ? 1 : 0, output });
+        });
+        child.stdin?.on("error", () => undefined);
+        child.stdin?.end(input);
+    });
+}
+function inside(parent, child) {
+    const path = relative(parent, child);
+    return path === "" || (!path.startsWith("..") && !path.startsWith("/"));
+}
+async function rejectSymlink(path, missing = false) {
+    try {
+        if ((await lstat(path)).isSymbolicLink())
+            throw new Error("Unsafe setup path symlink");
+    }
+    catch (error) {
+        if (missing && error.code === "ENOENT")
+            return;
+        throw error;
+    }
+}
+async function cleanupTemporary(path) {
+    try {
+        const info = await lstat(path);
+        if (info.isFile())
+            await unlink(path);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+}
+async function atomicWrite(path, contents, mode, guard) {
+    await rejectSymlink(path, true);
+    const temporary = join(dirname(path), `.${basename(path)}.${randomUUID()}.tmp`);
+    let handle;
+    try {
+        handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, mode);
+        await handle.writeFile(contents, "utf8");
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        await chmod(temporary, mode);
+        await rejectSymlink(path, true);
+        await guard?.();
+        await rename(temporary, path);
+        if (process.platform !== "win32") {
+            const directory = await open(dirname(path), constants.O_RDONLY);
+            try {
+                await directory.sync();
+            }
+            finally {
+                await directory.close();
+            }
+        }
+    }
+    finally {
+        await handle?.close();
+        await cleanupTemporary(temporary);
+    }
+}
+function exactKeys(value, keys) {
+    return Object.keys(value).sort().join("\0") === [...keys].sort().join("\0");
+}
+function validCredential(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const item = value;
+    return (exactKeys(item, ["apiKey", "keyId", "version", "kind", "capabilities"]) &&
+        item.kind === "anonymous_trial" &&
+        Array.isArray(item.capabilities) &&
+        item.capabilities.length === 1 &&
+        item.capabilities[0] === "setup_telemetry_write" &&
+        validSetupCredentialIdentity(item.apiKey, item.keyId) &&
+        (item.version === 0 || item.version === 1));
+}
+function validProbe(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const item = value;
+    return (exactKeys(item, ["traceId", "spanId", "credentialVersion", "verified"]) &&
+        typeof item.traceId === "string" &&
+        /^[a-f0-9]{32}$/u.test(item.traceId) &&
+        !/^0+$/u.test(item.traceId) &&
+        typeof item.spanId === "string" &&
+        /^[a-f0-9]{16}$/u.test(item.spanId) &&
+        !/^0+$/u.test(item.spanId) &&
+        (item.credentialVersion === 0 || item.credentialVersion === 1) &&
+        typeof item.verified === "boolean");
+}
+function validApplicationEvidence(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const item = value;
+    return (exactKeys(item, ["traceId", "spanId", "credentialVersion", "verified", "source"]) &&
+        item.source === "existing-application-request" &&
+        validProbe({
+            traceId: item.traceId,
+            spanId: item.spanId,
+            credentialVersion: item.credentialVersion,
+            verified: item.verified,
+        }));
+}
+function validApplicationAttempt(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const item = value;
+    return (exactKeys(item, ["credentialVersion", "startedAt"]) &&
+        (item.credentialVersion === 0 || item.credentialVersion === 1) &&
+        typeof item.startedAt === "string" &&
+        item.startedAt.length <= 40 &&
+        Number.isFinite(Date.parse(item.startedAt)));
+}
+function validClaimHandoff(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const item = value;
+    const allowed = [
+        "id",
+        "previousHandoffId",
+        ...(item.state === undefined ? [] : ["state"]),
+        ...(item.expiresAt === undefined ? [] : ["expiresAt"]),
+        ...(item.sessionExpiresAt === undefined ? [] : ["sessionExpiresAt"]),
+    ];
+    return (exactKeys(item, allowed) &&
+        typeof item.id === "string" &&
+        /^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/u.test(item.id) &&
+        (item.previousHandoffId === null ||
+            (typeof item.previousHandoffId === "string" &&
+                /^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/u.test(item.previousHandoffId))) &&
+        (item.state === undefined ||
+            ["pending", "consumed", "expired", "revoked"].includes(item.state)) &&
+        (item.expiresAt === undefined ||
+            (typeof item.expiresAt === "string" &&
+                item.expiresAt.length <= 40 &&
+                Number.isFinite(Date.parse(item.expiresAt)))) &&
+        (item.sessionExpiresAt === undefined ||
+            item.sessionExpiresAt === null ||
+            (typeof item.sessionExpiresAt === "string" &&
+                item.sessionExpiresAt.length <= 40 &&
+                Number.isFinite(Date.parse(item.sessionExpiresAt)))) &&
+        ((item.state === undefined &&
+            item.expiresAt === undefined &&
+            item.sessionExpiresAt === undefined) ||
+            (item.state !== undefined && item.expiresAt !== undefined)));
+}
+function parseRecord(value, origin) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("Invalid setup installation record");
+    const item = value;
+    const allowed = [
+        "format",
+        "origin",
+        "installationId",
+        "installationSecret",
+        "provisionAttempts",
+        "managedFiles",
+        ...(item.credential === undefined ? [] : ["credential"]),
+        ...(item.revocationCredential === undefined ? [] : ["revocationCredential"]),
+        ...(item.anonymousKeyRevoked === undefined ? [] : ["anonymousKeyRevoked"]),
+        ...(item.probe === undefined ? [] : ["probe"]),
+        ...(item.applicationEvidence === undefined ? [] : ["applicationEvidence"]),
+        ...(item.applicationAttempt === undefined ? [] : ["applicationAttempt"]),
+        ...(item.claimHandoff === undefined ? [] : ["claimHandoff"]),
+    ];
+    if (!exactKeys(item, allowed) ||
+        item.format !== 1 ||
+        item.origin !== origin ||
+        typeof item.installationId !== "string" ||
+        !/^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/u.test(item.installationId) ||
+        typeof item.installationSecret !== "string" ||
+        !/^[A-Za-z0-9_-]{43}$/u.test(item.installationSecret) ||
+        !Array.isArray(item.provisionAttempts) ||
+        item.provisionAttempts.length > 5 ||
+        item.provisionAttempts.some((entry) => typeof entry !== "string" || entry.length > 40 || !Number.isFinite(Date.parse(entry))) ||
+        (item.credential !== undefined && !validCredential(item.credential)) ||
+        (item.anonymousKeyRevoked !== undefined &&
+            (item.anonymousKeyRevoked !== true ||
+                !validCredential(item.credential) ||
+                item.credential.version !== 1 ||
+                item.revocationCredential !== undefined)) ||
+        (item.revocationCredential !== undefined &&
+            (!validCredential(item.revocationCredential) ||
+                item.revocationCredential.version !== 0 ||
+                !validCredential(item.credential) ||
+                item.credential.version !== 1)) ||
+        (item.probe !== undefined && !validProbe(item.probe)) ||
+        (item.applicationEvidence !== undefined &&
+            !validApplicationEvidence(item.applicationEvidence)) ||
+        (item.applicationAttempt !== undefined && !validApplicationAttempt(item.applicationAttempt)) ||
+        (item.claimHandoff !== undefined && !validClaimHandoff(item.claimHandoff)) ||
+        (item.applicationEvidence !== undefined &&
+            (!validApplicationAttempt(item.applicationAttempt) ||
+                item.applicationEvidence.credentialVersion !==
+                    item.applicationAttempt.credentialVersion)) ||
+        !item.managedFiles ||
+        typeof item.managedFiles !== "object" ||
+        Array.isArray(item.managedFiles) ||
+        Object.entries(item.managedFiles).some(([path, digest]) => !path ||
+            path.length > 4096 ||
+            typeof digest !== "string" ||
+            !/^[a-f0-9]{64}$/u.test(digest)))
+        throw new Error("Invalid setup installation record");
+    return item;
+}
+/** Owner-only, project/origin-scoped storage for installation proof and telemetry credentials. */
+export class FileSetupInstallationStore {
+    lastSnapshot;
+    /** Resolved project directory containing the installation state. */
+    projectRoot;
+    /** Exact normalized Hue origin scoped to this store. */
+    origin;
+    /** Owner-only `.hue` directory. */
+    directory;
+    /** Origin-scoped ignored installation record path. */
+    path;
+    /** Origin-scoped owner-only browser handoff; its contents are never emitted. */
+    claimHandoffPath;
+    /** Origin-scoped private application evidence transfer path. */
+    applicationEvidencePath;
+    constructor(projectRoot, origin) {
+        this.projectRoot = resolve(projectRoot);
+        this.origin = origin;
+        this.directory = join(this.projectRoot, ".hue");
+        const originHash = createHash("sha256").update(origin).digest("hex").slice(0, 20);
+        this.path = join(this.directory, `installation-${originHash}.json`);
+        this.claimHandoffPath = join(this.directory, `claim-handoff-${originHash}.html`);
+        this.applicationEvidencePath = join(this.directory, `application-evidence-${originHash}.json`);
+        if (!inside(this.projectRoot, this.path))
+            throw new Error("Unsafe setup installation path");
+        if (!inside(this.projectRoot, this.claimHandoffPath))
+            throw new Error("Unsafe setup claim handoff path");
+        if (!inside(this.projectRoot, this.applicationEvidencePath))
+            throw new Error("Unsafe setup application evidence path");
+    }
+    async rejectUnsafeProjectRoot() {
+        let path = this.projectRoot;
+        for (;;) {
+            const info = await lstat(path);
+            if (!info.isDirectory() || info.isSymbolicLink())
+                throw new Error("Unsafe setup project root symlink");
+            const parent = dirname(path);
+            if (parent === path)
+                break;
+            path = parent;
+        }
+    }
+    async hasGitWorktree() {
+        let directory = this.projectRoot;
+        for (;;) {
+            try {
+                const marker = await lstat(join(directory, ".git"));
+                if (marker.isSymbolicLink() || (!marker.isDirectory() && !marker.isFile()))
+                    throw new Error("Refusing unsafe Git metadata while protecting setup private files");
+                const result = await gitDiagnostic(this.projectRoot, [
+                    "rev-parse",
+                    "--is-inside-work-tree",
+                ]);
+                if (result.code !== 0 || result.output.trim() !== "true")
+                    throw new Error("Refusing setup outside a verifiable Git worktree");
+                return true;
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+            }
+            const parent = dirname(directory);
+            if (parent === directory)
+                return false;
+            directory = parent;
+        }
+    }
+    privatePaths() {
+        const names = [this.path, this.claimHandoffPath, this.applicationEvidencePath].map((path) => basename(path));
+        return [
+            ...names,
+            ...names.map((name) => `.${name}.00000000-0000-4000-8000-000000000000.tmp`),
+            `${basename(this.applicationEvidencePath)}.0.tmp`,
+        ].map((name) => `.hue/${name}`);
+    }
+    async assertPrivateGitProtection(requireIgnored) {
+        // This is a private storage directory, not a general project ignore file.
+        // Refuse selective negations too: sampling a random temporary name cannot
+        // establish protection for every future atomic-write/app-process filename.
+        const localIgnore = join(this.directory, ".gitignore");
+        await rejectSymlink(this.directory, true);
+        await rejectSymlink(localIgnore, true);
+        try {
+            const handle = await open(localIgnore, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+            try {
+                const info = await handle.stat();
+                if (!info.isFile() || info.size > 1024 * 1024)
+                    throw new Error("Unsafe setup private ignore file");
+                if ((await handle.readFile("utf8")).split(/\r?\n/u).some((line) => line.startsWith("!")))
+                    throw new Error("Refusing conflicting Git ignore rules for setup private files");
+            }
+            finally {
+                await handle.close();
+            }
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+        if (!(await this.hasGitWorktree()))
+            return;
+        const tracked = await gitDiagnostic(this.projectRoot, [
+            "--literal-pathspecs",
+            "ls-files",
+            "--cached",
+            "-z",
+            "--",
+            ".hue",
+        ]);
+        if (tracked.code !== 0 ||
+            tracked.output
+                .split("\0")
+                .some((path) => /^\.hue\/\.?(?:installation-|claim-handoff-|application-evidence-)/u.test(path)))
+            throw new Error("Refusing tracked setup private files; remove them from the Git index first");
+        const paths = this.privatePaths();
+        const result = await gitDiagnostic(this.projectRoot, ["check-ignore", "--no-index", "--verbose", "--non-matching", "-z", "--stdin"], `${paths.join("\0")}\0`);
+        const fields = result.output.split("\0");
+        if (fields.pop() !== "" || fields.length !== paths.length * 4)
+            throw new Error("Refusing unverifiable setup private-file ignore rules");
+        for (let index = 0; index < paths.length; index++) {
+            const pattern = fields[index * 4 + 2];
+            if (fields[index * 4 + 3] !== paths[index])
+                throw new Error("Refusing unverifiable setup private-file ignore rules");
+            if (pattern.startsWith("!") || (requireIgnored && !pattern))
+                throw new Error("Refusing conflicting Git ignore rules for setup private files");
+        }
+    }
+    async snapshot() {
+        await this.rejectUnsafeProjectRoot();
+        await rejectSymlink(this.directory);
+        const handle = await open(this.path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        try {
+            const info = await handle.stat();
+            if (!info.isFile() ||
+                info.size > MAX_FILE_BYTES ||
+                (process.platform !== "win32" &&
+                    ((info.mode & 0o077) !== 0 || info.uid !== process.getuid?.())))
+                throw new Error("Unsafe setup installation record; owner-only mode 0600 is required");
+            const contents = await handle.readFile("utf8");
+            const after = await handle.stat();
+            if (info.mtimeMs !== after.mtimeMs ||
+                info.ctimeMs !== after.ctimeMs ||
+                info.size !== after.size)
+                throw new Error("Refusing changed setup installation record");
+            return { contents, info };
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    async ensureIgnoreFile(ignorePath, rule) {
+        await rejectSymlink(ignorePath, true);
+        let source = "";
+        let mode = 0o644;
+        try {
+            const info = await lstat(ignorePath);
+            if (!info.isFile() || info.size > 1024 * 1024)
+                throw new Error("Unsafe project .gitignore");
+            mode = info.mode & 0o777;
+            source = await readFile(ignorePath, "utf8");
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+        if (source.split(/\r?\n/u).includes(rule))
+            return;
+        const separator = source.length === 0 || source.endsWith("\n") ? "" : "\n";
+        await atomicWrite(ignorePath, `${source}${separator}${rule}\n`, mode, async () => {
+            await rejectSymlink(ignorePath, true);
+            let current = "";
+            try {
+                current = await readFile(ignorePath, "utf8");
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+            }
+            if (current !== source)
+                throw new Error("Refusing concurrently changed setup ignore rules");
+        });
+    }
+    async ensureRootIgnored() {
+        for (const rule of IGNORE_RULES)
+            await this.ensureIgnoreFile(join(this.projectRoot, ".gitignore"), rule);
+    }
+    /** Revalidates owner-only storage and ignore rules before an existing proof is used for I/O. */
+    async ensureIgnored() {
+        await this.rejectUnsafeProjectRoot();
+        await this.assertPrivateGitProtection(false);
+        await this.ensureRootIgnored();
+        await rejectSymlink(this.directory);
+        const info = await lstat(this.directory);
+        if (!info.isDirectory())
+            throw new Error("Unsafe setup installation directory");
+        if (process.platform !== "win32")
+            await chmod(this.directory, 0o700);
+        for (const rule of LOCAL_IGNORE_RULES)
+            await this.ensureIgnoreFile(join(this.directory, ".gitignore"), rule);
+        await this.assertPrivateGitProtection(true);
+    }
+    /** Loads a valid owner-only record without creating one. */
+    async load() {
+        await this.rejectUnsafeProjectRoot();
+        await rejectSymlink(this.directory, true);
+        await rejectSymlink(this.path, true);
+        await this.assertPrivateGitProtection(false);
+        try {
+            await lstat(this.path);
+            await this.assertPrivateGitProtection(true);
+            const current = await this.snapshot();
+            let value;
+            try {
+                value = JSON.parse(current.contents);
+            }
+            catch {
+                throw new Error("Invalid setup installation record");
+            }
+            const record = parseRecord(value, this.origin);
+            this.lastSnapshot = current;
+            return record;
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return undefined;
+            throw error;
+        }
+    }
+    /** Creates and durably saves the installation proof before any caller may perform network I/O. */
+    async loadOrCreate() {
+        const existing = await this.load();
+        if (existing) {
+            await this.ensureIgnored();
+            return existing;
+        }
+        await this.assertPrivateGitProtection(false);
+        await this.ensureRootIgnored();
+        await rejectSymlink(this.directory, true);
+        await mkdir(this.directory, { recursive: false, mode: 0o700 }).catch((error) => {
+            if (error.code !== "EEXIST")
+                throw error;
+        });
+        await rejectSymlink(this.directory);
+        if (process.platform !== "win32")
+            await chmod(this.directory, 0o700);
+        for (const rule of LOCAL_IGNORE_RULES)
+            await this.ensureIgnoreFile(join(this.directory, ".gitignore"), rule);
+        await this.assertPrivateGitProtection(true);
+        const record = {
+            format: 1,
+            origin: this.origin,
+            installationId: randomUUID().toLowerCase(),
+            installationSecret: randomBytes(32).toString("base64url"),
+            provisionAttempts: [],
+            managedFiles: {},
+        };
+        try {
+            const handle = await open(this.path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+            try {
+                await handle.writeFile(`${JSON.stringify(record)}\n`, "utf8");
+                await handle.sync();
+            }
+            finally {
+                await handle.close();
+            }
+            if (process.platform !== "win32")
+                await chmod(this.path, 0o600);
+            if (process.platform !== "win32") {
+                const directory = await open(this.directory, constants.O_RDONLY);
+                try {
+                    await directory.sync();
+                }
+                finally {
+                    await directory.close();
+                }
+            }
+            this.lastSnapshot = await this.snapshot();
+            return record;
+        }
+        catch (error) {
+            if (error.code === "EEXIST") {
+                const raced = await this.load();
+                if (raced)
+                    return raced;
+            }
+            throw error;
+        }
+    }
+    /** Atomically replaces this store's validated owner-only record. */
+    async save(record) {
+        parseRecord(record, this.origin);
+        await this.assertPrivateGitProtection(true);
+        await rejectSymlink(this.directory);
+        const expected = this.lastSnapshot;
+        if (!expected)
+            throw new Error("Refusing to save an installation without loading its current state");
+        await atomicWrite(this.path, `${JSON.stringify(record)}\n`, 0o600, async () => {
+            await this.assertPrivateGitProtection(true);
+            const current = await this.snapshot();
+            if (current.contents !== expected.contents ||
+                current.info.dev !== expected.info.dev ||
+                current.info.ino !== expected.info.ino ||
+                current.info.mode !== expected.info.mode ||
+                current.info.mtimeMs !== expected.info.mtimeMs ||
+                current.info.ctimeMs !== expected.info.ctimeMs)
+                throw new Error("Refusing concurrently changed setup installation state; rerun after the other command finishes");
+        });
+        this.lastSnapshot = await this.snapshot();
+    }
+    /** Saves a private browser redirect without putting its capability in a process argument. */
+    async saveClaimHandoff(claimUrl) {
+        await this.ensureIgnored();
+        const encoded = JSON.stringify(claimUrl).replaceAll("<", "\\u003c");
+        const html = `<!doctype html>
+<meta charset="utf-8">
+<meta name="referrer" content="no-referrer">
+<meta http-equiv="cache-control" content="no-store">
+<title>Continue Hue setup</title>
+<script>location.replace(${encoded})</script>
+<p>This private Hue setup handoff is opened locally. Close this page if it does not continue.</p>
+`;
+        await atomicWrite(this.claimHandoffPath, html, 0o600, () => this.assertPrivateGitProtection(true));
+        return this.claimHandoffPath;
+    }
+    /** Removes a consumed or terminal claim handoff without following symlinks. */
+    async removeClaimHandoff() {
+        await rejectSymlink(this.claimHandoffPath, true);
+        try {
+            const info = await lstat(this.claimHandoffPath);
+            if (!info.isFile())
+                throw new Error("Unsafe setup claim handoff path");
+            await unlink(this.claimHandoffPath);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    }
+    /** Removes the private child-to-parent evidence transfer file without following symlinks. */
+    async removeApplicationEvidence() {
+        await rejectSymlink(this.applicationEvidencePath, true);
+        try {
+            const info = await lstat(this.applicationEvidencePath);
+            if (!info.isFile())
+                throw new Error("Unsafe setup application evidence path");
+            await unlink(this.applicationEvidencePath);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    }
+}
+/** Computes the digest used to detect unexpected edits to managed files. */
+export function setupManagedDigest(contents) {
+    return createHash("sha256").update(contents).digest("hex");
+}

package/dist/setup/lock.d.ts

@@ -0,0 +1,2 @@
+/** Serializes all origins for one project: they share manifests and application files. */
+export declare function acquireSetupCommandLock(projectRoot: string): Promise<() => Promise<void>>;

package/dist/setup/lock.js

@@ -0,0 +1,38 @@
+import { createHash } from "node:crypto";
+import { lstat, mkdir, realpath, rmdir } from "node:fs/promises";
+import { join } from "node:path";
+/** Serializes all origins for one project: they share manifests and application files. */
+export async function acquireSetupCommandLock(projectRoot) {
+    const root = await realpath(projectRoot);
+    if ((process.platform !== "linux" && process.platform !== "darwin") || !process.getuid)
+        throw new Error("Automatic setup requires supported POSIX command ownership");
+    // The OS-wide canonical temporary directory is fixed, not selected by TMPDIR,
+    // HOME or XDG variables. All aliases/origins for the same real project share it.
+    const parent = join(await realpath("/tmp"), `hue-setup-locks-${process.getuid()}`);
+    await mkdir(parent, { mode: 0o700 }).catch((error) => {
+        if (error.code !== "EEXIST")
+            throw error;
+    });
+    const info = await lstat(parent);
+    if (!info.isDirectory() ||
+        info.isSymbolicLink() ||
+        (info.mode & 0o077) !== 0 ||
+        info.uid !== process.getuid())
+        throw new Error("Refusing unsafe setup command lock directory");
+    const path = join(parent, createHash("sha256").update(root).digest("hex"));
+    try {
+        await mkdir(path, { mode: 0o700 });
+    }
+    catch (error) {
+        if (error.code === "EEXIST")
+            throw new Error("Refusing concurrent setup commands. Wait for the existing command to finish. If it was forcibly killed, the owner must inspect and remove its stale local command lock before resuming.");
+        throw error;
+    }
+    const acquired = await lstat(path);
+    return async () => {
+        const current = await lstat(path);
+        if (current.ino !== acquired.ino || current.dev !== acquired.dev || !current.isDirectory())
+            throw new Error("Refusing to release a changed setup command lock");
+        await rmdir(path);
+    };
+}

package/dist/setup/machine.d.ts

@@ -83,16 +83,7 @@ interface PlanReadyTransitionEvent {
     plan: SetupPlan;
 }
 /** @inline */
-interface ConfigureTelemetryRequiredTransitionEvent {
-    /** Transition-event discriminator. */
-    event: "action.required";
-    /** Project action needed next. */
-    action: "configure";
-    /** Secret-free explanation. */
-    message: string;
-}
-/** @inline */
-type SetupTransitionEvent = StartStepTransitionEvent | ProjectDetectedTransitionEvent | CompleteStepTransitionEvent | PlanReadyTransitionEvent | ConfigureTelemetryRequiredTransitionEvent;
+type SetupTransitionEvent = StartStepTransitionEvent | ProjectDetectedTransitionEvent | CompleteStepTransitionEvent | PlanReadyTransitionEvent;
 /** Pure transition result. Events are templates completed by the runner. */
 export interface SetupTransition {
     /** State to checkpoint before executing another effect. */