@fentaris/edge 0.2.2 → 0.3.0

package/dist/installation.js

@@ -0,0 +1,897 @@
+import { spawn } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import { chmod, copyFile, cp, lstat, mkdir, open, readFile, readdir, realpath, rm, stat, writeFile, } from "node:fs/promises";
+import path from "node:path";
+import { computeInstallationDigest, edgeError, installationApprovalDigest, normalizeInstallationReadiness, validateInstallationRecipe, } from "@fentaris/core";
+import { redactInstallerText } from "./redaction.js";
+const emptyDocument = () => ({
+    schemaVersion: 1,
+    attempts: {},
+    approvals: {},
+    lifecycle: {},
+    artifacts: {},
+    activePointers: {},
+    retentionReferences: {},
+});
+/** Protected durable installation state persisted atomically by the platform store. */
+export class ProtectedInstallationState {
+    store;
+    queue = Promise.resolve();
+    constructor(store) {
+        this.store = store;
+    }
+    async snapshot() {
+        return structuredClone(await this.store.load() ?? emptyDocument());
+    }
+    async update(mutation) {
+        let result;
+        const operation = this.queue.then(async () => {
+            const [next, value] = mutation(await this.snapshot());
+            await this.store.save(next);
+            result = value;
+        });
+        this.queue = operation.catch(() => undefined);
+        await operation;
+        return result;
+    }
+    putAttempt(attempt) {
+        return this.update((document) => [{ ...document, attempts: { ...document.attempts, [attempt.attemptId]: freeze(attempt) } }, undefined]);
+    }
+    putApproval(approval) {
+        return this.update((document) => [{ ...document, approvals: { ...document.approvals, [approvalKey(approval.approvalDigest, approval.cleanup)]: freeze(approval) } }, undefined]);
+    }
+    putLifecycle(value) {
+        return this.update((document) => {
+            const current = document.lifecycle[value.deploymentId];
+            if (current && (value.desiredVersion < current.desiredVersion
+                || (value.desiredVersion === current.desiredVersion && value.recipeDigest !== current.recipeDigest)
+                || value.observedAt < current.observedAt)) {
+                throw edgeError("EDGE_PROTOCOL", "Installation lifecycle update is stale.");
+            }
+            return [{ ...document, lifecycle: { ...document.lifecycle, [value.deploymentId]: freeze(value) } }, undefined];
+        });
+    }
+    putArtifact(value) {
+        return this.update((document) => [{ ...document, artifacts: { ...document.artifacts, [value.recipeDigest]: freeze(value) } }, undefined]);
+    }
+    async approval(digest, cleanup = false) {
+        return (await this.snapshot()).approvals[approvalKey(digest, cleanup)];
+    }
+    async lifecycle(deploymentId) {
+        return (await this.snapshot()).lifecycle[deploymentId];
+    }
+    async artifact(digest) {
+        return (await this.snapshot()).artifacts[digest];
+    }
+    async attempts(digest) {
+        return Object.values((await this.snapshot()).attempts)
+            .filter((attempt) => attempt.recipeDigest === digest)
+            .sort((left, right) => left.startedAt - right.startedAt);
+    }
+    async activate(deploymentId, artifact, retain) {
+        await this.update((document) => {
+            const previous = document.activePointers[deploymentId];
+            const retained = [previous, ...(document.retentionReferences[deploymentId] ?? [])]
+                .filter((digest) => digest !== undefined && digest !== artifact.recipeDigest)
+                .slice(0, retain);
+            const artifacts = { ...document.artifacts };
+            if (previous && previous !== artifact.recipeDigest && artifacts[previous]) {
+                const references = Math.max(0, artifacts[previous].references - 1);
+                artifacts[previous] = { ...artifacts[previous], active: references > 0, references };
+            }
+            artifacts[artifact.recipeDigest] = { ...artifact, active: true };
+            return [{
+                    ...document,
+                    artifacts,
+                    activePointers: { ...document.activePointers, [deploymentId]: artifact.recipeDigest },
+                    retentionReferences: { ...document.retentionReferences, [deploymentId]: retained },
+                }, undefined];
+        });
+    }
+    async removeReference(deploymentId, digest) {
+        return this.update((document) => {
+            const current = document.artifacts[digest];
+            if (!current)
+                return [document, undefined];
+            const references = Math.max(0, current.references - 1);
+            const artifact = { ...current, active: references > 0, references };
+            const activePointers = { ...document.activePointers };
+            delete activePointers[deploymentId];
+            return [{ ...document, artifacts: { ...document.artifacts, [digest]: artifact }, activePointers }, artifact];
+        });
+    }
+    async rollbackCandidate(deploymentId) {
+        const document = await this.snapshot();
+        const digest = document.retentionReferences[deploymentId]?.[0];
+        return digest ? document.artifacts[digest] : undefined;
+    }
+    clear() { return this.store.delete(); }
+}
+/** Build exact bounded custom-install review material without credential values. */
+export function buildInstallationReview(recipe, localPolicy) {
+    const provider = recipe.provider;
+    const source = provider.kind === "custom" ? sanitizeSource(provider.source) : undefined;
+    return freeze({
+        approvalDigest: installationApprovalDigest(recipe, localPolicy),
+        recipeDigest: recipe.digest,
+        provider: provider.kind,
+        providerDetails: sanitizeProvider(provider),
+        ...(source ? { source } : {}),
+        ...(provider.kind === "custom" ? { entrypoint: provider.entrypoint, interpreter: provider.interpreter } : {}),
+        arguments: provider.kind === "custom" ? [...(provider.args ?? [])] : [],
+        permissions: recipe.permissions,
+        outputs: recipe.outputs,
+        verification: recipe.verification,
+        cleanup: recipe.cleanup,
+    });
+}
+export class InstallationConsentManager {
+    state;
+    now;
+    constructor(state, now = Date.now) {
+        this.state = state;
+        this.now = now;
+    }
+    review(recipe, localPolicy) { return buildInstallationReview(recipe, localPolicy); }
+    async decide(review, decision, cleanup = false) {
+        await this.state.putApproval({ approvalDigest: review.approvalDigest, recipeDigest: review.recipeDigest, decision, cleanup, decidedAt: this.now() });
+    }
+    async decision(review, cleanup = false) { return this.state.approval(review.approvalDigest, cleanup); }
+}
+/** Interactive local approval flow that presents the complete bounded review. */
+export class TerminalInstallationConsent {
+    consent;
+    prompt;
+    constructor(consent, prompt) {
+        this.consent = consent;
+        this.prompt = prompt;
+    }
+    async reviewAndDecide(recipe, localPolicy, cleanup = false) {
+        const review = this.consent.review(recipe, cleanup ? { localPolicy, cleanup: true } : localPolicy);
+        await this.prompt.present(review);
+        const approved = await this.prompt.confirm(cleanup
+            ? `Approve custom cleanup ${review.approvalDigest}?`
+            : `Approve custom installation ${review.approvalDigest}?`);
+        await this.consent.decide(review, approved ? "approved" : "denied", cleanup);
+        return (await this.consent.decision(review, cleanup));
+    }
+}
+/** Build an enforceable platform adapter when an approved sandbox command is configured. */
+export function commandIsolationAdapter(options = {}) {
+    const platform = options.platform ?? process.platform;
+    const executable = options.executable;
+    if (!executable)
+        return noIsolationAdapter;
+    if (platform === "linux")
+        return {
+            filesystem: true,
+            network: true,
+            wrap: async (input) => ({
+                ...input,
+                command: executable,
+                args: ["--die-with-parent", "--unshare-all", "--new-session", "--bind", input.cwd, input.cwd, "--chdir", input.cwd, input.command, ...(input.args ?? [])],
+            }),
+        };
+    if (platform === "darwin")
+        return {
+            filesystem: true,
+            network: true,
+            wrap: async (input) => ({
+                ...input,
+                command: executable,
+                args: ["-p", `(version 1) (deny default) (allow process*) (allow file-read*) (allow file-write* (subpath "${escapeSandbox(input.cwd)}"))${input.requireNetworkIsolation ? "" : " (allow network*)"}`, input.command, ...(input.args ?? [])],
+            }),
+        };
+    return noIsolationAdapter;
+}
+/** Process-tree supervised, bounded, no-elevation installer execution. */
+export class BoundedInstallerRunner {
+    isolation;
+    now;
+    constructor(isolation = noIsolationAdapter, now = Date.now) {
+        this.isolation = isolation;
+        this.now = now;
+    }
+    async run(input) {
+        denyElevation(input.command, input.args ?? []);
+        if (input.allowedExecutables && !input.allowedExecutables.includes(path.basename(input.command))) {
+            throw installationFailure("elevation-denied", "Installer executable is not allowed by local policy.");
+        }
+        if ((input.requireFilesystemIsolation && !this.isolation.filesystem) || (input.requireNetworkIsolation && !this.isolation.network)) {
+            throw installationFailure("isolation-unavailable", "Required installer isolation is unavailable on this platform.");
+        }
+        const wrapped = await this.isolation.wrap(input);
+        await mkdir(wrapped.cwd, { recursive: true, mode: 0o700 });
+        const startedAt = this.now();
+        return new Promise((resolve, reject) => {
+            const child = spawn(wrapped.command, [...(wrapped.args ?? [])], {
+                cwd: wrapped.cwd,
+                env: allowlistedEnvironment(wrapped.env),
+                stdio: ["ignore", "pipe", "pipe"],
+                detached: process.platform !== "win32",
+                windowsHide: true,
+            });
+            let bytes = 0;
+            let output = "";
+            let settled = false;
+            const terminate = () => terminateTree(child.pid);
+            const timer = setTimeout(() => {
+                terminate();
+                finishError(installationFailure("limit-exceeded", "Installer timed out."));
+            }, wrapped.timeoutMs);
+            const finishError = (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                reject(error);
+            };
+            const collect = (chunk) => {
+                bytes += chunk.length;
+                if (bytes > wrapped.maxOutputBytes) {
+                    terminate();
+                    finishError(installationFailure("limit-exceeded", "Installer output limit exceeded."));
+                    return;
+                }
+                output += chunk.toString("utf8");
+            };
+            child.stdout?.on("data", collect);
+            child.stderr?.on("data", collect);
+            child.once("error", finishError);
+            child.once("exit", async (code) => {
+                if (settled)
+                    return;
+                try {
+                    if (await directoryBytes(wrapped.cwd) > wrapped.maxDiskBytes)
+                        throw installationFailure("limit-exceeded", "Installer disk limit exceeded.");
+                    const sanitized = redactInstallerText(output, wrapped.secrets ?? []);
+                    if (code !== 0)
+                        throw installationFailure("installation-failed", `Installer exited with code ${code ?? -1}: ${sanitized}`);
+                    settled = true;
+                    clearTimeout(timer);
+                    resolve({ code: 0, output: sanitized, startedAt, finishedAt: this.now(), ...(child.pid ? { pid: child.pid } : {}) });
+                }
+                catch (error) {
+                    finishError(error);
+                }
+            });
+        });
+    }
+}
+export class NodeInstallationCommandExecutor {
+    runner;
+    constructor(runner = new BoundedInstallerRunner()) {
+        this.runner = runner;
+    }
+    async run(command, args, options) {
+        return (await this.runner.run({ command, args, cwd: options.cwd, env: options.env, timeoutMs: 300_000, maxOutputBytes: 1_048_576, maxDiskBytes: 1_073_741_824 })).output;
+    }
+}
+export class FetchInstallationDownloader {
+    async download(url, destination, credential, maxBytes = 536_870_912) {
+        const response = await fetch(url, { redirect: "error", headers: credential ? { authorization: `Bearer ${credential}` } : {} });
+        if (!response.ok || !response.body)
+            throw installationFailure("source-unavailable", `Archive download failed with status ${response.status}.`);
+        const declared = Number(response.headers.get("content-length") ?? 0);
+        if (declared > maxBytes)
+            throw installationFailure("limit-exceeded", "Archive exceeds the source size limit.");
+        const handle = await open(destination, "wx", 0o600);
+        let total = 0;
+        try {
+            for await (const chunk of response.body) {
+                total += chunk.byteLength;
+                if (total > maxBytes)
+                    throw installationFailure("limit-exceeded", "Archive exceeds the source size limit.");
+                await handle.write(chunk);
+            }
+        }
+        finally {
+            await handle.close();
+        }
+    }
+}
+/** Tar archive extraction with preflight type/path checks and post-extract containment. */
+export class SecureTarExtractor {
+    commands;
+    constructor(commands = new NodeInstallationCommandExecutor()) {
+        this.commands = commands;
+    }
+    async extract(archive, destination) {
+        await mkdir(destination, { recursive: true, mode: 0o700 });
+        const listing = await this.commands.run("tar", ["-tvf", archive], { cwd: destination });
+        for (const line of listing.split("\n").filter(Boolean)) {
+            const type = line[0];
+            if (type !== "-" && type !== "d")
+                throw installationFailure("source-integrity-failed", "Archive contains links or special files.");
+            const name = line.trim().split(/\s+/).at(-1) ?? "";
+            assertContainedRelative(name, "archive entry");
+        }
+        await this.commands.run("tar", ["-xf", archive, "--no-same-owner", "--no-same-permissions", "-C", destination], { cwd: destination });
+        await assertTreeSafe(destination);
+    }
+}
+/** Immutable Git/archive/inline/local/enterprise staging implementation. */
+export class ManagedInstallationSourceResolver {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async resolve(source, destination) {
+        await rm(destination, { recursive: true, force: true });
+        await mkdir(destination, { recursive: true, mode: 0o700 });
+        if (source.kind === "git")
+            await this.git(source, destination);
+        else if (source.kind === "archive")
+            await this.archive(source, destination);
+        else if (source.kind === "inline")
+            await this.inline(source, destination);
+        else if (source.kind === "local")
+            await this.local(source, destination);
+        else
+            await this.enterprise(source, destination);
+        const digest = await hashTree(destination);
+        const expected = source.kind === "local" || source.kind === "enterprise" ? source.integrity : undefined;
+        if (expected && digest !== expected) {
+            await rm(destination, { recursive: true, force: true });
+            throw installationFailure("source-integrity-failed", "Resolved source digest does not match the recipe.");
+        }
+        return { root: destination, digest };
+    }
+    async git(source, destination) {
+        const commands = this.options.commands ?? new NodeInstallationCommandExecutor();
+        const credential = source.credentialRef ? await this.options.credentials?.get(source.credentialRef) : undefined;
+        if (source.credentialRef && !credential)
+            throw installationFailure("source-credential-required", "Private Git source credential is unavailable locally.");
+        const askpass = path.join(destination, process.platform === "win32" ? ".fentaris-askpass.cmd" : ".fentaris-askpass");
+        if (credential) {
+            const contents = process.platform === "win32"
+                ? "@echo off\r\necho %FENTARIS_SOURCE_CREDENTIAL%\r\n"
+                : "#!/bin/sh\nprintf '%s\\n' \"$FENTARIS_SOURCE_CREDENTIAL\"\n";
+            await writeFile(askpass, contents, { encoding: "utf8", mode: 0o700 });
+            await chmod(askpass, 0o700).catch(() => undefined);
+        }
+        const env = credential ? {
+            GIT_TERMINAL_PROMPT: "0",
+            GIT_ASKPASS: askpass,
+            GIT_ASKPASS_REQUIRE: "force",
+            FENTARIS_SOURCE_CREDENTIAL: credential,
+        } : { GIT_TERMINAL_PROMPT: "0" };
+        await commands.run("git", ["init", "--quiet"], { cwd: destination });
+        await commands.run("git", ["remote", "add", "origin", source.repository], { cwd: destination });
+        try {
+            await commands.run("git", ["fetch", "--depth", "1", "origin", source.commit], { cwd: destination, env });
+        }
+        finally {
+            await rm(askpass, { force: true });
+        }
+        await commands.run("git", ["checkout", "--detach", "--quiet", "FETCH_HEAD"], { cwd: destination });
+        const actual = (await commands.run("git", ["rev-parse", "HEAD"], { cwd: destination })).trim();
+        if (actual !== source.commit)
+            throw installationFailure("source-integrity-failed", "Git checkout did not resolve to the exact requested commit.");
+        const gitmodules = path.join(destination, ".gitmodules");
+        if (await exists(gitmodules))
+            throw installationFailure("source-integrity-failed", "Git submodules are disabled by the bounded source policy.");
+        await rm(path.join(destination, ".git"), { recursive: true, force: true });
+    }
+    async archive(source, destination) {
+        const archive = `${destination}.archive`;
+        const credential = source.credentialRef ? await this.options.credentials?.get(source.credentialRef) : undefined;
+        if (source.credentialRef && !credential)
+            throw installationFailure("source-credential-required", "Private source credential is unavailable locally.");
+        try {
+            await (this.options.downloader ?? new FetchInstallationDownloader()).download(source.url, archive, credential, source.maxBytes);
+            if (await hashFile(archive) !== source.integrity)
+                throw installationFailure("source-integrity-failed", "Archive digest mismatch.");
+            await (this.options.extractor ?? new SecureTarExtractor()).extract(archive, destination);
+        }
+        finally {
+            await rm(archive, { force: true });
+        }
+    }
+    async inline(source, destination) {
+        const filename = source.filename ?? "installer";
+        assertContainedRelative(filename, "inline filename");
+        await writeFile(path.join(destination, filename), source.content, { encoding: "utf8", mode: 0o700 });
+    }
+    async local(source, destination) {
+        const granted = await this.options.local?.resolve(source.grantRef);
+        if (!granted)
+            throw installationFailure("source-unavailable", "Approved local source grant is unavailable.");
+        const info = await lstat(granted);
+        if (info.isSymbolicLink() || (!info.isFile() && !info.isDirectory()))
+            throw installationFailure("source-integrity-failed", "Local source is a link or special file.");
+        if (info.isDirectory())
+            await cp(granted, destination, { recursive: true, dereference: false, errorOnExist: false });
+        else
+            await copyFile(granted, path.join(destination, path.basename(granted)));
+        await assertTreeSafe(destination);
+    }
+    async enterprise(source, destination) {
+        const adapter = this.options.enterprise?.find((candidate) => candidate.adapter === source.adapter);
+        if (!adapter)
+            throw installationFailure("source-unavailable", "Enterprise source adapter is unavailable.");
+        const credential = source.credentialRef ? await this.options.credentials?.get(source.credentialRef) : undefined;
+        if (source.credentialRef && !credential)
+            throw installationFailure("source-credential-required", "Enterprise source credential is unavailable locally.");
+        await adapter.resolve(source.artifactRef, destination, credential);
+        await assertTreeSafe(destination);
+    }
+}
+export class NodeInstallationVerificationService {
+    async verify(recipe, root) {
+        const canonicalRoot = await realpath(root);
+        const outputs = {};
+        for (const output of recipe.outputs) {
+            const candidate = await containedPath(canonicalRoot, output.path);
+            const info = await stat(candidate);
+            if (output.kind === "directory" ? !info.isDirectory() : !info.isFile())
+                throw installationFailure("verification-failed", `Declared output ${output.name} has the wrong type.`);
+            if (output.kind === "executable" && process.platform !== "win32" && (info.mode & 0o111) === 0)
+                throw installationFailure("verification-failed", `Declared output ${output.name} is not executable.`);
+            outputs[output.name] = candidate;
+        }
+        for (const verification of recipe.verification)
+            await verifyOne(verification, canonicalRoot);
+        return freeze(outputs);
+    }
+}
+export class SharedInstallationProvider {
+    kind;
+    source;
+    runner;
+    verifier;
+    constructor(kind, source, runner, verifier = new NodeInstallationVerificationService()) {
+        this.kind = kind;
+        this.source = source;
+        this.runner = runner;
+        this.verifier = verifier;
+    }
+    async preflight(context) {
+        if (context.recipe.provider.kind === "manual") {
+            const detect = context.recipe.provider.detect;
+            try {
+                await this.runner.run(runRequest(context.recipe, detect.target, detect.args ?? [], context.stagingRoot));
+                return { ready: true };
+            }
+            catch {
+                return { ready: false, reasonCode: "manual-prerequisite-required" };
+            }
+        }
+        return { ready: await exists(context.installationRoot) };
+    }
+    async install(context) {
+        const provider = context.recipe.provider;
+        await mkdir(context.installationRoot, { recursive: true, mode: 0o700 });
+        if (provider.kind === "custom") {
+            const staged = await this.source.resolve(provider.source, context.stagingRoot);
+            const entrypoint = await containedPath(staged.root, provider.entrypoint);
+            const command = interpreterCommand(provider.interpreter, entrypoint);
+            const args = provider.interpreter === "executable" ? [...(provider.args ?? [])] : [entrypoint, ...(provider.args ?? [])];
+            await this.runner.run(runRequest(context.recipe, command, args, staged.root));
+            await cp(staged.root, context.installationRoot, { recursive: true, force: true });
+            return;
+        }
+        if (provider.kind === "binary") {
+            const staged = await this.source.resolve(provider.source, context.stagingRoot);
+            await cp(staged.root, context.installationRoot, { recursive: true, force: true });
+            return;
+        }
+        if (provider.kind === "node-package") {
+            const spec = `${provider.package}@${provider.version}`;
+            await mkdir(context.stagingRoot, { recursive: true, mode: 0o700 });
+            const packed = await this.runner.run(runRequest(context.recipe, "npm", ["pack", "--json", "--pack-destination", context.stagingRoot, spec], context.stagingRoot));
+            const metadata = JSON.parse(packed.output);
+            const filename = metadata[0]?.filename;
+            if (!filename)
+                throw installationFailure("source-integrity-failed", "npm did not return a packed artifact identity.");
+            const tarball = path.join(context.stagingRoot, filename);
+            if (await hashFile(tarball) !== provider.integrity)
+                throw installationFailure("source-integrity-failed", "Node package integrity mismatch.");
+            await this.runner.run(runRequest(context.recipe, "npm", ["install", "--prefix", context.installationRoot, "--save-exact", provider.allowLifecycleScripts ? "--foreground-scripts" : "--ignore-scripts", tarball], context.installationRoot));
+            return;
+        }
+        if (provider.kind === "python") {
+            const python = provider.python ?? "python3";
+            await mkdir(context.stagingRoot, { recursive: true, mode: 0o700 });
+            await this.runner.run(runRequest(context.recipe, python, ["-m", "pip", "download", "--no-deps", "--dest", context.stagingRoot, `${provider.package}==${provider.version}`], context.stagingRoot));
+            const distributions = (await readdir(context.stagingRoot, { withFileTypes: true })).filter((entry) => entry.isFile());
+            if (distributions.length === 0)
+                throw installationFailure("source-integrity-failed", "Python resolver returned no distribution.");
+            for (const distribution of distributions) {
+                if (!provider.hashes.includes(await hashFile(path.join(context.stagingRoot, distribution.name))))
+                    throw installationFailure("source-integrity-failed", "Python distribution hash is not declared by the recipe.");
+            }
+            await this.runner.run(runRequest(context.recipe, python, ["-m", "venv", context.installationRoot], context.installationRoot));
+            const pip = process.platform === "win32" ? path.join(context.installationRoot, "Scripts", "pip.exe") : path.join(context.installationRoot, "bin", "pip");
+            await this.runner.run(runRequest(context.recipe, pip, ["install", "--no-index", "--no-deps", ...distributions.map((entry) => path.join(context.stagingRoot, entry.name))], context.installationRoot));
+            return;
+        }
+        if (provider.kind === "container") {
+            const runtime = provider.runtime ?? "docker";
+            await this.runner.run(runRequest(context.recipe, runtime, ["pull", `${provider.image}@${provider.digest}`], context.installationRoot));
+            const inspected = await this.runner.run(runRequest(context.recipe, runtime, ["image", "inspect", "--format", "{{json .RepoDigests}}", `${provider.image}@${provider.digest}`], context.installationRoot));
+            if (!inspected.output.includes(`@${provider.digest}`))
+                throw installationFailure("verification-failed", "Container runtime did not confirm the requested immutable digest.");
+            await writeFile(path.join(context.installationRoot, "image.json"), JSON.stringify({ image: provider.image, digest: provider.digest }), { mode: 0o600 });
+            return;
+        }
+        throw installationFailure("manual-prerequisite-required", provider.nextAction);
+    }
+    verify(context) {
+        if (context.recipe.provider.kind === "manual") {
+            return Promise.resolve(Object.fromEntries(context.recipe.outputs.map((output) => [output.name, context.recipe.provider.kind === "manual" ? context.recipe.provider.detect.target : output.path])));
+        }
+        return this.verifier.verify(context.recipe, context.installationRoot);
+    }
+    async cleanup(context) {
+        const cleanup = context.recipe.cleanup;
+        if (cleanup.kind === "manual")
+            throw installationFailure("manual-prerequisite-required", "Complete the documented cleanup locally.");
+        if (cleanup.kind === "custom") {
+            if (!cleanup.entrypoint || !cleanup.interpreter)
+                throw installationFailure("verification-failed", "Custom cleanup is missing an entrypoint or interpreter.");
+            const entrypoint = await containedPath(context.installationRoot, cleanup.entrypoint);
+            const command = interpreterCommand(cleanup.interpreter, entrypoint);
+            const args = cleanup.interpreter === "executable" ? [...(cleanup.args ?? [])] : [entrypoint, ...(cleanup.args ?? [])];
+            await this.runner.run(runRequest(context.recipe, command, args, context.installationRoot));
+        }
+        await rm(context.installationRoot, { recursive: true, force: true });
+    }
+}
+/** Idempotent, crash-aware installation lifecycle coordinator. */
+export class InstallationCoordinator {
+    options;
+    now;
+    attemptId;
+    constructor(options) {
+        this.options = options;
+        this.now = options.now ?? Date.now;
+        this.attemptId = options.attemptId ?? randomUUID;
+    }
+    async reconcile(request) {
+        const recipe = validateInstallationRecipe(request.recipe);
+        const root = path.join(this.options.installationRoot, digestDirectory(recipe.digest));
+        return this.options.lock.runExclusive(root, async () => {
+            const existing = await this.options.state.lifecycle(request.deploymentId);
+            if (existing && existing.desiredVersion > request.desiredVersion)
+                throw edgeError("EDGE_PROTOCOL", "Installation desired state is stale.");
+            if (existing && existing.desiredVersion === request.desiredVersion && existing.recipeDigest === recipe.digest) {
+                if (["ready", "installed"].includes(existing.state))
+                    return existing;
+                if (!request.explicitRetry && existing.state === "failed")
+                    return existing;
+            }
+            if (!platformSupported(recipe, this.options.platform ?? process.platform, this.options.architecture ?? process.arch)) {
+                return this.transition(request, "blocked", { reasonCode: "unsupported-platform", retryable: false });
+            }
+            const provider = this.options.providers.get(recipe.provider.kind);
+            if (!provider)
+                return this.transition(request, "blocked", { reasonCode: "agent-upgrade-required", retryable: false });
+            if (recipe.provider.kind === "custom") {
+                const review = this.options.consent.review(recipe, request.localPolicy ?? {});
+                const approval = await this.options.consent.decision(review);
+                if (!approval) {
+                    await this.emit("edge.installation.approval", request, "required", { approvalDigest: review.approvalDigest, sourceKind: recipe.provider.source.kind });
+                    return this.transition(request, "approval-required", { reasonCode: "approval-required", retryable: false, nextAction: `Review installation ${review.approvalDigest}.` });
+                }
+                if (approval.decision !== "approved")
+                    return this.transition(request, "blocked", { reasonCode: approval.decision === "revoked" ? "approval-revoked" : "approval-denied", retryable: false });
+            }
+            const artifact = await this.options.state.artifact(recipe.digest);
+            if (artifact && await exists(artifact.root)) {
+                await this.options.state.activate(request.deploymentId, { ...artifact, active: true, references: artifact.references + 1 }, recipe.retention.previousVersions);
+                return this.transition(request, "installed", { retryable: false });
+            }
+            const prior = await this.options.state.attempts(recipe.digest);
+            if (!request.explicitRetry && prior.some((attempt) => attempt.state === "failed")) {
+                return this.transition(request, "failed", { reasonCode: prior.at(-1)?.reasonCode ?? "installation-failed", retryable: true, attempt: prior.at(-1) });
+            }
+            const attemptId = this.attemptId();
+            const startedAt = this.now();
+            const attempt = { attemptId, deploymentId: request.deploymentId, desiredVersion: request.desiredVersion, recipeDigest: recipe.digest, state: "installing", startedAt, retryable: false };
+            await this.options.state.putAttempt(attempt);
+            await this.transition(request, "installing", { retryable: false, attempt });
+            const stagingRoot = path.join(this.options.stagingRoot, attemptId);
+            const context = { recipe, attemptId, stagingRoot, installationRoot: root };
+            try {
+                const preflight = await provider.preflight(context);
+                if (!preflight.ready) {
+                    await this.emit("edge.installation.source", request, "resolving", { provider: recipe.provider.kind, sourceKind: recipe.provider.kind === "custom" ? recipe.provider.source.kind : recipe.provider.kind });
+                    await provider.install(context);
+                }
+                const outputs = await provider.verify(context);
+                await this.emit("edge.installation.verification", request, "verified", { attemptId, outputNames: Object.keys(outputs).sort() });
+                const verified = { recipeDigest: recipe.digest, root, outputs, verifiedAt: this.now(), active: true, references: 1, externalSideEffects: recipe.cleanup.externalSideEffects };
+                await this.options.state.putArtifact(verified);
+                await this.options.state.activate(request.deploymentId, verified, recipe.retention.previousVersions);
+                await this.emit("edge.installation.activation", request, "activated", { attemptId, rollbackAvailable: recipe.retention.previousVersions > 0 });
+                const complete = { ...attempt, state: "installed", finishedAt: this.now() };
+                await this.options.state.putAttempt(complete);
+                return this.transition(request, "installed", { retryable: false, attempt: complete });
+            }
+            catch (error) {
+                const reasonCode = installationReason(error);
+                const failed = { ...attempt, state: "failed", finishedAt: this.now(), reasonCode, retryable: retryableReason(reasonCode), diagnostics: [redactInstallerText(error instanceof Error ? error.message : String(error))] };
+                await this.options.state.putAttempt(failed);
+                await this.emit("edge.installation.attempt", request, "failed", { attemptId, reasonCode, retryable: failed.retryable });
+                return this.transition(request, "failed", { reasonCode, retryable: failed.retryable, attempt: failed });
+            }
+            finally {
+                await rm(stagingRoot, { recursive: true, force: true });
+            }
+        });
+    }
+    status(deploymentId) {
+        return this.options.state.lifecycle(deploymentId);
+    }
+    review(recipe, localPolicy = {}, cleanup = false) {
+        return this.options.consent.review(recipe, cleanup ? { localPolicy, cleanup: true } : localPolicy);
+    }
+    async decide(recipe, decision, localPolicy = {}, cleanup = false) {
+        const review = this.review(recipe, localPolicy, cleanup);
+        await this.options.consent.decide(review, decision, cleanup);
+        return (await this.options.consent.decision(review, cleanup));
+    }
+    async recoverInterrupted() {
+        const document = await this.options.state.snapshot();
+        const interrupted = [];
+        for (const attempt of Object.values(document.attempts).filter((candidate) => candidate.state === "installing")) {
+            for (const pid of attempt.processIds ?? [])
+                await this.options.terminateProcess?.(pid);
+            const updated = { ...attempt, state: "failed", finishedAt: this.now(), reasonCode: "attempt-interrupted", retryable: true };
+            await this.options.state.putAttempt(updated);
+            interrupted.push(updated);
+        }
+        return interrupted;
+    }
+    async remove(deploymentId, recipe, approveCleanup = false) {
+        const existing = await this.options.state.lifecycle(deploymentId);
+        const request = { deploymentId, desiredVersion: existing?.desiredVersion ?? 0, launchDigest: existing?.launchDigest ?? "sha256:removed", recipe };
+        if (recipe.cleanup.kind === "custom" && recipe.cleanup.externalSideEffects) {
+            const review = this.options.consent.review(recipe, { cleanup: true });
+            const approval = await this.options.consent.decision(review, true);
+            if (!approveCleanup || approval?.decision !== "approved")
+                return this.transition(request, "blocked", { reasonCode: "cleanup-approval-required", retryable: false });
+        }
+        await this.transition(request, "removing", { retryable: false });
+        const current = await this.options.state.artifact(recipe.digest);
+        if (current && current.references <= 1) {
+            const provider = this.options.providers.get(recipe.provider.kind);
+            if (!provider)
+                return this.transition(request, "blocked", { reasonCode: "agent-upgrade-required", retryable: false });
+            try {
+                await provider.cleanup({
+                    recipe,
+                    attemptId: `cleanup-${randomUUID()}`,
+                    stagingRoot: this.options.stagingRoot,
+                    installationRoot: current.root,
+                });
+            }
+            catch (error) {
+                const reasonCode = installationReason(error);
+                return this.transition(request, "failed", { reasonCode, retryable: retryableReason(reasonCode) });
+            }
+        }
+        const artifact = await this.options.state.removeReference(deploymentId, recipe.digest);
+        if (artifact?.references === 0)
+            await rm(artifact.root, { recursive: true, force: true });
+        await this.emit("edge.installation.cleanup", request, "removed", { managedOnly: true, remainingReferences: artifact?.references ?? 0 });
+        return this.transition(request, "removed", { retryable: false });
+    }
+    async rollback(deploymentId, request) {
+        const candidate = await this.options.state.rollbackCandidate(deploymentId);
+        if (!candidate || candidate.externalSideEffects || !await exists(candidate.root)) {
+            return this.transition(request, "failed", { reasonCode: "artifact-missing", retryable: false, nextAction: "Perform manual recovery; no safe verified rollback is available." });
+        }
+        await this.options.state.activate(deploymentId, { ...candidate, active: true, references: candidate.references + 1 }, request.recipe.retention.previousVersions);
+        await this.emit("edge.installation.rollback", request, "activated", { rollbackDigest: candidate.recipeDigest });
+        return this.transition({ ...request, recipe: { ...request.recipe, digest: candidate.recipeDigest } }, "installed", { retryable: false });
+    }
+    async resolveArtifact(reference) {
+        const artifact = await this.options.state.artifact(reference.installationDigest);
+        const output = artifact?.outputs[reference.output];
+        if (!artifact?.active || !output)
+            throw installationFailure("artifact-missing", "Installed artifact output is unavailable.");
+        return containedPath(await realpath(artifact.root), path.relative(artifact.root, output));
+    }
+    async transition(request, state, options) {
+        const lifecycle = {
+            deploymentId: request.deploymentId,
+            desiredVersion: request.desiredVersion,
+            recipeDigest: request.recipe.digest,
+            launchDigest: request.launchDigest,
+            state,
+            readiness: normalizeInstallationReadiness(state),
+            observedAt: this.now(),
+            ...(options.reasonCode ? { reasonCode: options.reasonCode } : {}),
+            ...(options.attempt ? { attempt: options.attempt } : {}),
+            ...(options.nextAction ? { nextAction: options.nextAction } : {}),
+        };
+        await this.options.state.putLifecycle(lifecycle);
+        return lifecycle;
+    }
+    async emit(name, request, outcome, metadata) {
+        await this.options.telemetry?.emit({ name, deploymentId: request.deploymentId, outcome, metadata: { recipeDigest: request.recipe.digest, desiredVersion: request.desiredVersion, ...metadata } }).catch(() => undefined);
+    }
+}
+export function createDefaultInstallationProviders(options = {}) {
+    const source = options.source ?? new ManagedInstallationSourceResolver();
+    const runner = options.runner ?? new BoundedInstallerRunner();
+    const kinds = ["custom", "node-package", "python", "binary", "container", "manual"];
+    return new Map(kinds.map((kind) => [kind, new SharedInstallationProvider(kind, source, runner, options.verifier)]));
+}
+const noIsolationAdapter = Object.freeze({
+    filesystem: false,
+    network: false,
+    wrap: async (input) => input,
+});
+function runRequest(recipe, command, args, cwd) {
+    return {
+        command, args, cwd,
+        timeoutMs: recipe.permissions.limits.timeoutMs,
+        maxOutputBytes: recipe.permissions.limits.maxOutputBytes,
+        maxDiskBytes: recipe.permissions.limits.maxDiskBytes,
+        allowedExecutables: recipe.permissions.executables,
+        requireFilesystemIsolation: recipe.permissions.requireFilesystemIsolation,
+        requireNetworkIsolation: recipe.permissions.requireNetworkIsolation,
+    };
+}
+function sanitizeSource(source) {
+    const copy = { ...source };
+    delete copy.credentialRef;
+    if (source.kind === "inline")
+        copy.content = source.content.slice(0, 32_768);
+    return freeze(copy);
+}
+function sanitizeProvider(provider) {
+    const copy = structuredClone(provider);
+    if (provider.kind === "custom")
+        copy.source = sanitizeSource(provider.source);
+    return freeze(copy);
+}
+function allowlistedEnvironment(input = {}) {
+    const env = {};
+    for (const key of ["PATH", "SystemRoot", "WINDIR", "TMPDIR", "TEMP", "TMP"])
+        if (process.env[key])
+            env[key] = process.env[key];
+    for (const [key, value] of Object.entries(input))
+        if (/^[A-Z_][A-Z0-9_]*$/.test(key))
+            env[key] = value;
+    return env;
+}
+function denyElevation(command, args) {
+    const tokens = [path.basename(command), ...args].map((value) => value.toLowerCase());
+    if (tokens.some((value) => ["sudo", "su", "doas", "runas", "pkexec", "start-process -verb runas"].some((term) => value === term || value.includes(term)))) {
+        throw installationFailure("elevation-denied", "Installer elevation is not permitted.");
+    }
+}
+function terminateTree(pid) {
+    if (!pid)
+        return;
+    try {
+        process.kill(process.platform === "win32" ? pid : -pid, "SIGTERM");
+    }
+    catch { /* already exited */ }
+    const timer = setTimeout(() => { try {
+        process.kill(process.platform === "win32" ? pid : -pid, "SIGKILL");
+    }
+    catch { /* already exited */ } }, 2_000);
+    timer.unref();
+}
+async function verifyOne(verification, root) {
+    if (verification.kind === "container-image")
+        return;
+    const target = await containedPath(root, verification.target);
+    const info = await stat(target);
+    if (!info.isFile())
+        throw installationFailure("verification-failed", "Verification target is not a file.");
+    if (verification.expectedDigest && await hashFile(target) !== verification.expectedDigest)
+        throw installationFailure("verification-failed", "Verification digest mismatch.");
+}
+async function containedPath(root, relative) {
+    assertContainedRelative(relative, "managed path");
+    const candidate = path.resolve(root, relative);
+    const parent = await realpath(path.dirname(candidate));
+    if (parent !== root && !parent.startsWith(`${root}${path.sep}`))
+        throw installationFailure("artifact-escape", "Managed path escapes the artifact root.");
+    return candidate;
+}
+function assertContainedRelative(value, field) {
+    if (!value || path.isAbsolute(value) || value.split(/[\\/]/).includes(".."))
+        throw installationFailure("source-integrity-failed", `${field} escapes the managed root.`);
+}
+async function assertTreeSafe(root) {
+    const canonical = await realpath(root);
+    const visit = async (directory) => {
+        for (const entry of await readdir(directory, { withFileTypes: true })) {
+            const candidate = path.join(directory, entry.name);
+            const info = await lstat(candidate);
+            if (info.isSymbolicLink() || (!info.isFile() && !info.isDirectory()))
+                throw installationFailure("source-integrity-failed", "Source contains a symlink or special file.");
+            const resolved = await realpath(candidate);
+            if (resolved !== canonical && !resolved.startsWith(`${canonical}${path.sep}`))
+                throw installationFailure("source-integrity-failed", "Source escapes its staging root.");
+            if (info.isDirectory())
+                await visit(candidate);
+        }
+    };
+    await visit(root);
+}
+async function hashFile(file) {
+    return `sha256:${createHash("sha256").update(await readFile(file)).digest("hex")}`;
+}
+async function hashTree(root) {
+    const entries = [];
+    const walk = async (directory) => {
+        for (const entry of (await readdir(directory, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+            if (entry.name === ".git")
+                continue;
+            const candidate = path.join(directory, entry.name);
+            if (entry.isDirectory())
+                await walk(candidate);
+            else if (entry.isFile())
+                entries.push({ path: path.relative(root, candidate).split(path.sep).join("/"), digest: await hashFile(candidate) });
+            else
+                throw installationFailure("source-integrity-failed", "Source contains a link or special file.");
+        }
+    };
+    await walk(root);
+    return computeInstallationDigest(entries);
+}
+async function directoryBytes(root) {
+    let total = 0;
+    const walk = async (directory) => {
+        for (const entry of await readdir(directory, { withFileTypes: true })) {
+            const candidate = path.join(directory, entry.name);
+            if (entry.isDirectory())
+                await walk(candidate);
+            else if (entry.isFile())
+                total += (await stat(candidate)).size;
+        }
+    };
+    await walk(root);
+    return total;
+}
+function interpreterCommand(interpreter, entrypoint) {
+    if (interpreter === "executable")
+        return entrypoint;
+    if (interpreter === "powershell")
+        return process.platform === "win32" ? "powershell.exe" : "pwsh";
+    if (interpreter === "python")
+        return "python3";
+    return interpreter;
+}
+function platformSupported(recipe, platform, architecture) {
+    return (!recipe.platforms?.platforms || recipe.platforms.platforms.includes(platform))
+        && (!recipe.platforms?.architectures || recipe.platforms.architectures.includes(architecture));
+}
+function digestDirectory(digest) { return digest.slice("sha256:".length); }
+function escapeSandbox(value) { return value.replaceAll("\\", "\\\\").replaceAll('"', '\\"'); }
+function approvalKey(digest, cleanup = false) { return `${digest}:${cleanup}`; }
+async function exists(file) { try {
+    await lstat(file);
+    return true;
+}
+catch (error) {
+    if (error.code === "ENOENT")
+        return false;
+    throw error;
+} }
+function retryableReason(reason) { return ["source-unavailable", "limit-exceeded", "installation-failed", "attempt-interrupted"].includes(reason); }
+function installationReason(error) { return error instanceof InstallationExecutionError ? error.reasonCode : "installation-failed"; }
+export class InstallationExecutionError extends Error {
+    reasonCode;
+    constructor(reasonCode, message) {
+        super(message);
+        this.reasonCode = reasonCode;
+        this.name = `InstallationExecutionError[${reasonCode}]`;
+    }
+}
+function installationFailure(reason, message) { return new InstallationExecutionError(reason, message); }
+function freeze(value) { if (value && typeof value === "object") {
+    Object.freeze(value);
+    for (const child of Object.values(value))
+        if (child && typeof child === "object")
+            freeze(child);
+} return value; }
+//# sourceMappingURL=installation.js.map