knodin 0.5.0

package/dist/src/update-policy.js

@@ -0,0 +1,944 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { verifyReleaseAttestation } from "./release-attestation.js";
+import { canonicalizeUpdateMetadata, verifyTargetArtifact, verifyUpdateMetadataBundle, verifyUpdateRootChain, } from "./update-trust.js";
+const DEFAULT_TIMEOUT_MS = 2_000;
+const MAX_TIMEOUT_MS = 10_000;
+const MAX_METADATA_BYTES = 512 * 1_024;
+const MAX_RELEASE_EVIDENCE_BYTES = 16 * 1_024 * 1_024;
+const MAX_STATE_BYTES = 4 * 1_024 * 1_024;
+const MAX_ARTIFACT_BYTES = 512 * 1_024 * 1_024;
+const MAX_ROOT_ROTATIONS_PER_CHECK = 32;
+const MAX_CROSS_CHECK_MIRRORS = 4;
+const SHA256 = /^[a-f0-9]{64}$/;
+const SAFE_TARGET_TEMPLATE = /^[A-Za-z0-9._/{}-]+$/;
+/** Conservative manager ownership detection; an inconclusive path remains unknown. */
+export function detectUpdateInstallMethod(runtimeCommand, env = process.env) {
+    if (env.MISE_DATA_DIR || env.MISE_ENV)
+        return "mise";
+    if (env.VOLTA_HOME)
+        return "volta";
+    if (env.NVM_BIN || env.NVM_DIR)
+        return "nvm";
+    if (env.FNM_DIR || env.FNM_MULTISHELL_PATH)
+        return "fnm";
+    if (env.ASDF_DIR || env.ASDF_DATA_DIR)
+        return "asdf";
+    if (env.HOMEBREW_PREFIX)
+        return "homebrew";
+    const command = runtimeCommand.join(" ").toLowerCase();
+    if (command.includes("/homebrew/") || command.includes("/cellar/"))
+        return "homebrew";
+    if (command.includes("/.local/share/mise/"))
+        return "mise";
+    if (command.includes("/.volta/"))
+        return "volta";
+    if (command.includes("/.nvm/"))
+        return "nvm";
+    if (command.includes("/fnm"))
+        return "fnm";
+    if (command.includes("/.asdf/"))
+        return "asdf";
+    if (command.includes("node_modules/knodin/"))
+        return "npm";
+    return "unknown";
+}
+function statePath(stateHome) {
+    const root = stateHome ?? process.env.XDG_STATE_HOME ?? path.join(os.homedir(), ".local", "state");
+    return path.join(root, "knodin", "trusted-update-state.json");
+}
+function checkLeasePath(stateHome) {
+    return path.join(path.dirname(statePath(stateHome)), "update-check.lock");
+}
+function configPath(configHome) {
+    const root = configHome ?? process.env.XDG_CONFIG_HOME ?? path.join(os.homedir(), ".config");
+    return path.join(root, "knodin", "update.json");
+}
+function privateWrite(file, value) {
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    try {
+        fs.chmodSync(path.dirname(file), 0o700);
+    }
+    catch {
+        // Best effort on filesystems without POSIX modes (not a trust decision).
+    }
+    const temporary = `${file}.${process.pid}.${Date.now()}.tmp`;
+    fs.writeFileSync(temporary, `${JSON.stringify(value)}\n`, { mode: 0o600, flag: "wx" });
+    fs.renameSync(temporary, file);
+    try {
+        fs.chmodSync(file, 0o600);
+    }
+    catch {
+        // Best effort on filesystems without POSIX modes (not a trust decision).
+    }
+}
+function safeJson(file, maximumBytes = MAX_METADATA_BYTES) {
+    try {
+        const stat = fs.statSync(file);
+        if (stat.size > maximumBytes)
+            return null;
+        return JSON.parse(fs.readFileSync(file, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+export function readTrustedUpdateState(stateHome) {
+    const value = safeJson(statePath(stateHome), MAX_STATE_BYTES);
+    if (!value ||
+        typeof value !== "object" ||
+        value.schemaVersion !== 1)
+        return null;
+    return value;
+}
+/** Atomically claim a due background check without putting network latency on ordinary commands. */
+export function claimScheduledUpdateCheck(options) {
+    const config = loadConfig(options);
+    const env = options.env ?? process.env;
+    if (!config ||
+        !config.enabled ||
+        config.offline ||
+        env.RECKON_UPDATE_CHECK === "0" ||
+        env.RECKON_OFFLINE === "1")
+        return false;
+    const now = options.now?.() ?? new Date();
+    const checkedAt = readTrustedUpdateState(options.stateHome)?.checkedAt;
+    if (checkedAt && now.getTime() - Date.parse(checkedAt) < config.checkIntervalHours * 3_600_000)
+        return false;
+    const lease = checkLeasePath(options.stateHome);
+    fs.mkdirSync(path.dirname(lease), { recursive: true, mode: 0o700 });
+    try {
+        fs.writeFileSync(lease, `${process.pid} ${now.toISOString()}\n`, { flag: "wx", mode: 0o600 });
+        return true;
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            return false;
+        try {
+            const recorded = fs.readFileSync(lease, "utf-8").trim().split(/\s+/, 2)[1];
+            const recordedAt = recorded ? Date.parse(recorded) : Number.NaN;
+            const age = now.getTime() - (Number.isFinite(recordedAt) ? recordedAt : fs.statSync(lease).mtimeMs);
+            if (age <= Math.max(config.timeoutMs * 4, 60_000))
+                return false;
+            fs.unlinkSync(lease);
+            fs.writeFileSync(lease, `${process.pid} ${now.toISOString()}\n`, { flag: "wx", mode: 0o600 });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+export function releaseScheduledUpdateCheck(stateHome) {
+    try {
+        fs.unlinkSync(checkLeasePath(stateHome));
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function validateConfig(value) {
+    if (!isRecord(value) || value.schemaVersion !== 1 || !isRecord(value.policy))
+        return null;
+    const candidate = value;
+    if (typeof candidate.enabled !== "boolean" ||
+        typeof candidate.offline !== "boolean" ||
+        typeof candidate.metadataBaseUrl !== "string" ||
+        typeof candidate.trustedRootPath !== "string" ||
+        !SHA256.test(candidate.trustedRootSha256) ||
+        typeof candidate.targetPathTemplate !== "string" ||
+        !SAFE_TARGET_TEMPLATE.test(candidate.targetPathTemplate) ||
+        !candidate.targetPathTemplate.includes("{version}") ||
+        typeof candidate.channel !== "string" ||
+        !/^[a-z][a-z0-9-]{0,31}$/.test(candidate.channel) ||
+        !Number.isFinite(candidate.checkIntervalHours) ||
+        candidate.checkIntervalHours < 1 ||
+        !Number.isInteger(candidate.timeoutMs) ||
+        candidate.timeoutMs < 100 ||
+        candidate.timeoutMs > MAX_TIMEOUT_MS ||
+        !["notify-only", "download-verify-only", "apply-patch", "apply-minor"].includes(candidate.policy.mode) ||
+        !Number.isFinite(candidate.policy.minimumReleaseAgeHours) ||
+        candidate.policy.minimumReleaseAgeHours < 0 ||
+        !Array.isArray(candidate.policy.approvedChannels) ||
+        !candidate.policy.approvedChannels.every((channel) => typeof channel === "string")) {
+        return null;
+    }
+    try {
+        targetPath(candidate.targetPathTemplate, "0.0.0");
+        const base = new URL(candidate.metadataBaseUrl);
+        if (base.protocol !== "https:" ||
+            !base.pathname.endsWith("/") ||
+            base.username !== "" ||
+            base.password !== "" ||
+            base.search !== "" ||
+            base.hash !== "")
+            return null;
+        const approved = new Set(candidate.approvedMirrorOrigins ?? []);
+        if (candidate.enterpriseMirrorOnly && !approved.has(base.origin))
+            return null;
+        if ((candidate.crossCheckMetadataBaseUrls?.length ?? 0) > MAX_CROSS_CHECK_MIRRORS)
+            return null;
+        for (const mirror of candidate.crossCheckMetadataBaseUrls ?? []) {
+            const parsed = new URL(mirror);
+            if (parsed.protocol !== "https:" ||
+                !parsed.pathname.endsWith("/") ||
+                parsed.username !== "" ||
+                parsed.password !== "" ||
+                parsed.search !== "" ||
+                parsed.hash !== "")
+                return null;
+            if (candidate.enterpriseMirrorOnly && !approved.has(parsed.origin))
+                return null;
+        }
+        for (const window of candidate.policy.maintenanceWindows ?? []) {
+            if (!Array.isArray(window.days) ||
+                window.days.length === 0 ||
+                !window.days.every((day) => Number.isInteger(day) && day >= 0 && day <= 6) ||
+                !/^([01]\d|2[0-3]):[0-5]\d$/.test(window.startUtc) ||
+                !/^([01]\d|2[0-3]):[0-5]\d$/.test(window.endUtc) ||
+                window.startUtc >= window.endUtc)
+                return null;
+        }
+    }
+    catch {
+        return null;
+    }
+    return candidate;
+}
+function loadConfig(options) {
+    if (options.config)
+        return validateConfig(options.config);
+    // The policy file is deliberately inert until the release team completes the
+    // offline root ceremony and the independently reviewed root + pin are embedded
+    // in the shipped package. Trusting a root path and its digest from the same
+    // mutable user file would collapse the trust boundary. Keep reading bounded so
+    // malformed files are harmless, but do not promote them to trust configuration.
+    safeJson(configPath(options.configHome));
+    return null;
+}
+function installMethod(options) {
+    return options.installMethod ?? "unknown";
+}
+function baseResult(options, status) {
+    return {
+        schemaVersion: 1,
+        status,
+        installedVersion: options.currentVersion,
+        installMethod: installMethod(options),
+        networkUsed: false,
+    };
+}
+function parseVersion(version) {
+    const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(version);
+    if (!match)
+        return null;
+    const prerelease = match[4]?.split(".") ?? null;
+    if (prerelease?.some((part) => part === "" || (/^\d+$/.test(part) && part.length > 1 && part.startsWith("0"))))
+        return null;
+    return {
+        core: [Number(match[1]), Number(match[2]), Number(match[3])],
+        prerelease,
+    };
+}
+function compareVersions(left, right) {
+    const a = parseVersion(left);
+    const b = parseVersion(right);
+    if (!a || !b)
+        return compareStrings(left, right);
+    const core = compareCore(a, b);
+    return core === 0 ? comparePrereleases(a.prerelease, b.prerelease) : core;
+}
+function compareStrings(left, right) {
+    if (left === right)
+        return 0;
+    return left < right ? -1 : 1;
+}
+function compareCore(left, right) {
+    for (let index = 0; index < 3; index++) {
+        const difference = (left.core[index] ?? 0) - (right.core[index] ?? 0);
+        if (difference !== 0)
+            return difference;
+    }
+    return 0;
+}
+function comparePrereleases(left, right) {
+    if (left === null)
+        return right === null ? 0 : 1;
+    if (right === null)
+        return -1;
+    for (let index = 0; index < Math.max(left.length, right.length); index++) {
+        const difference = compareOptionalPrereleaseParts(left[index], right[index]);
+        if (difference !== 0)
+            return difference;
+    }
+    return 0;
+}
+function compareOptionalPrereleaseParts(left, right) {
+    if (left === undefined)
+        return right === undefined ? 0 : -1;
+    if (right === undefined)
+        return 1;
+    if (left === right)
+        return 0;
+    return comparePrereleaseParts(left, right);
+}
+function comparePrereleaseParts(left, right) {
+    const leftNumeric = /^\d+$/.test(left);
+    const rightNumeric = /^\d+$/.test(right);
+    if (leftNumeric && rightNumeric)
+        return Number(left) - Number(right);
+    if (leftNumeric !== rightNumeric)
+        return leftNumeric ? -1 : 1;
+    return compareStrings(left, right);
+}
+function targetPath(template, version) {
+    if (!parseVersion(version))
+        throw new Error("signed target version is not valid SemVer");
+    const rendered = template.replaceAll("{version}", version);
+    if (rendered.startsWith("/") ||
+        rendered.includes("\\") ||
+        rendered.split("/").some((part) => part === "" || part === "." || part === "..")) {
+        throw new Error("configured target template produced an unsafe path");
+    }
+    return rendered;
+}
+function selectCandidate(bundle, config) {
+    const candidates = Object.entries(bundle.targets.signed.targets)
+        .filter(([, target]) => target.custom.channel === config.channel)
+        .filter(([, target]) => parseVersion(target.custom.version) !== null)
+        .filter(([name, target]) => name === targetPath(config.targetPathTemplate, target.custom.version))
+        .sort(([, left], [, right]) => compareVersions(right.custom.version, left.custom.version));
+    const selected = candidates[0];
+    if (!selected)
+        throw new Error(`signed targets contain no ${config.channel} release`);
+    return selected[0];
+}
+async function defaultFetchBytes(url, options) {
+    const response = await fetch(url, {
+        signal: options.signal,
+        redirect: "error",
+        headers: { accept: "application/octet-stream, application/json" },
+    });
+    if (!response.ok)
+        throw new Error(`update source returned HTTP ${response.status}`);
+    const declared = Number(response.headers.get("content-length"));
+    if (Number.isFinite(declared) && declared > options.maxBytes)
+        throw new Error("update response exceeds byte limit");
+    if (!response.body)
+        return new Uint8Array();
+    const chunks = [];
+    let total = 0;
+    const reader = response.body.getReader();
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.byteLength;
+        if (total > options.maxBytes) {
+            await reader.cancel();
+            throw new Error("update response exceeds byte limit");
+        }
+        chunks.push(value);
+    }
+    return Buffer.concat(chunks.map((chunk) => Buffer.from(chunk)), total);
+}
+function safeUrl(base, relative) {
+    const root = new URL(base);
+    const result = new URL(relative, root);
+    if (result.protocol !== "https:" ||
+        result.origin !== root.origin ||
+        !result.pathname.startsWith(root.pathname))
+        throw new Error("update URL escaped the approved HTTPS origin/path");
+    return result.href;
+}
+async function fetchWithDeadline(options, config, url, maxBytes) {
+    const controller = new AbortController();
+    let timeout;
+    try {
+        const deadline = new Promise((_resolve, reject) => {
+            timeout = setTimeout(() => {
+                controller.abort();
+                reject(new Error("update request exceeded its timeout"));
+            }, config.timeoutMs || DEFAULT_TIMEOUT_MS);
+        });
+        const bytes = await Promise.race([
+            (options.fetchBytes ?? defaultFetchBytes)(url, { signal: controller.signal, maxBytes }),
+            deadline,
+        ]);
+        if (bytes.byteLength > maxBytes)
+            throw new Error("update response exceeds byte limit");
+        return bytes;
+    }
+    finally {
+        if (timeout)
+            clearTimeout(timeout);
+    }
+}
+function parseEnvelope(bytes, label) {
+    try {
+        return JSON.parse(Buffer.from(bytes).toString("utf-8"));
+    }
+    catch {
+        throw new Error(`${label} is not valid JSON`);
+    }
+}
+async function fetchBundleAt(options, config, base) {
+    const records = {};
+    const digests = {};
+    for (const role of ["timestamp", "snapshot", "targets", "root"]) {
+        const bytes = await fetchWithDeadline(options, config, safeUrl(base, `${role}.json`), MAX_METADATA_BYTES);
+        records[role] = parseEnvelope(bytes, `${role}.json`);
+        digests[role] = createHash("sha256").update(bytes).digest("hex");
+    }
+    return { bundle: records, digests };
+}
+function rootVersion(value, label) {
+    if (!isRecord(value) || !isRecord(value.signed))
+        throw new Error(`${label} has no signed root`);
+    const version = value.signed.version;
+    if (!Number.isSafeInteger(version) || Number(version) <= 0)
+        throw new Error(`${label} has an invalid root version`);
+    return Number(version);
+}
+async function fetchRootChainAt(options, config, base, initialRoot, terminalRoot) {
+    const initialVersion = rootVersion(initialRoot, "trusted root");
+    const terminalVersion = rootVersion(terminalRoot, "root.json");
+    const gap = terminalVersion - initialVersion;
+    if (gap > MAX_ROOT_ROTATIONS_PER_CHECK) {
+        throw new Error(`root rotation gap ${gap} exceeds the per-check limit ${MAX_ROOT_ROTATIONS_PER_CHECK}`);
+    }
+    const roots = [];
+    const digests = {};
+    for (let version = initialVersion + 1; version <= terminalVersion; version++) {
+        const name = `${version}.root.json`;
+        const bytes = await fetchWithDeadline(options, config, safeUrl(base, name), MAX_METADATA_BYTES);
+        const root = parseEnvelope(bytes, name);
+        if (rootVersion(root, name) !== version)
+            throw new Error(`${name} has the wrong root version`);
+        roots.push(root);
+        digests[name] = createHash("sha256").update(bytes).digest("hex");
+    }
+    if (terminalVersion === initialVersion) {
+        const terminalDigest = createHash("sha256")
+            .update(canonicalizeUpdateMetadata(terminalRoot))
+            .digest("hex");
+        const initialDigest = createHash("sha256")
+            .update(canonicalizeUpdateMetadata(initialRoot))
+            .digest("hex");
+        if (terminalDigest !== initialDigest)
+            throw new Error("root.json disagrees with the pinned root at the same version");
+    }
+    else if (createHash("sha256")
+        .update(canonicalizeUpdateMetadata(roots.at(-1)))
+        .digest("hex") !==
+        createHash("sha256").update(canonicalizeUpdateMetadata(terminalRoot)).digest("hex")) {
+        throw new Error(`root.json disagrees with ${terminalVersion}.root.json`);
+    }
+    return { roots, digests };
+}
+async function fetchBundle(options, config, initialRoot, initialRootSha256, now) {
+    const primary = await fetchBundleAt(options, config, config.metadataBaseUrl);
+    const primaryRoots = await fetchRootChainAt(options, config, config.metadataBaseUrl, initialRoot, primary.bundle.root);
+    Object.assign(primary.digests, primaryRoots.digests);
+    for (const mirror of config.crossCheckMetadataBaseUrls ?? []) {
+        const checked = await fetchBundleAt(options, config, mirror);
+        const checkedRoots = await fetchRootChainAt(options, config, mirror, initialRoot, checked.bundle.root);
+        Object.assign(checked.digests, checkedRoots.digests);
+        const names = new Set([...Object.keys(primary.digests), ...Object.keys(checked.digests)]);
+        for (const name of names) {
+            if (checked.digests[name] !== primary.digests[name]) {
+                throw new Error(`cross-channel metadata mismatch for ${name}`);
+            }
+        }
+    }
+    const recoveredRoot = verifyUpdateRootChain(initialRoot, initialRootSha256, primaryRoots.roots, now);
+    return { bundle: primary.bundle, recoveredRoot, rootChain: primaryRoots.roots };
+}
+function trustedRoot(config) {
+    const value = safeJson(path.resolve(config.trustedRootPath));
+    if (!value)
+        throw new Error("trusted root is missing or unreadable");
+    return value;
+}
+function releaseAge(bundle, now) {
+    return Math.max(0, (now.getTime() - Date.parse(bundle.targets.signed.generatedAt)) / 3_600_000);
+}
+async function checkedUpdate(options) {
+    const config = loadConfig(options);
+    if (!config)
+        return baseResult(options, "trust-unconfigured");
+    const env = options.env ?? process.env;
+    if (!config.enabled || env.RECKON_UPDATE_CHECK === "0")
+        return baseResult(options, "disabled");
+    if (config.offline || env.RECKON_OFFLINE === "1")
+        return baseResult(options, "offline");
+    const now = options.now?.() ?? new Date();
+    const previous = readTrustedUpdateState(options.stateHome);
+    try {
+        const initialRoot = trustedRoot(config);
+        const { bundle, recoveredRoot, rootChain } = await fetchBundle(options, config, initialRoot, config.trustedRootSha256, now);
+        const selectedPath = selectCandidate(bundle, config);
+        const verified = verifyUpdateMetadataBundle(bundle, {
+            trustedRoot: recoveredRoot,
+            trustedRootSha256: createHash("sha256")
+                .update(canonicalizeUpdateMetadata(recoveredRoot))
+                .digest("hex"),
+            targetPath: selectedPath,
+            previous: previous?.trustedMetadata,
+            now,
+        });
+        const age = releaseAge(bundle, now);
+        const latest = verified.target.custom.version;
+        const state = {
+            schemaVersion: 1,
+            installedVersion: options.currentVersion,
+            latestTrustedVersion: latest,
+            channel: verified.target.custom.channel,
+            checkedAt: now.toISOString(),
+            releaseGeneratedAt: bundle.targets.signed.generatedAt,
+            targetPath: selectedPath,
+            trustedMetadata: verified.state,
+            trustedRoot: verified.rootEnvelope,
+            rollback: previous?.rollback,
+            lastApplied: previous?.lastApplied,
+        };
+        privateWrite(statePath(options.stateHome), state);
+        return {
+            config,
+            bundle,
+            recoveredRoot,
+            rootChain,
+            target: verified.target,
+            targetPath: selectedPath,
+            state,
+            result: {
+                ...baseResult(options, compareVersions(latest, options.currentVersion) > 0 ? "update-available" : "up-to-date"),
+                latestTrustedVersion: latest,
+                channel: verified.target.custom.channel,
+                releaseAgeHours: age,
+                checkedAt: now.toISOString(),
+                networkUsed: true,
+                acknowledged: config.acknowledgedVersion === latest,
+            },
+        };
+    }
+    catch (error) {
+        return {
+            ...baseResult(options, "check-failed"),
+            latestTrustedVersion: previous?.latestTrustedVersion,
+            channel: previous?.channel,
+            checkedAt: now.toISOString(),
+            networkUsed: true,
+            error: {
+                code: error instanceof Error && "code" in error ? String(error.code) : "verification-failed",
+                message: error instanceof Error ? error.message : String(error),
+            },
+        };
+    }
+}
+export function trustedUpdateStatus(options) {
+    const config = loadConfig(options);
+    if (!config)
+        return baseResult(options, "trust-unconfigured");
+    if (!config.enabled)
+        return baseResult(options, "disabled");
+    if (config.offline)
+        return baseResult(options, "offline");
+    const state = readTrustedUpdateState(options.stateHome);
+    if (!state)
+        return baseResult(options, "never-checked");
+    const now = options.now?.() ?? new Date();
+    return {
+        ...baseResult(options, compareVersions(state.latestTrustedVersion, options.currentVersion) > 0
+            ? "update-available"
+            : "up-to-date"),
+        latestTrustedVersion: state.latestTrustedVersion,
+        channel: state.channel,
+        releaseAgeHours: Math.max(0, (now.getTime() - Date.parse(state.releaseGeneratedAt)) / 3_600_000),
+        checkedAt: state.checkedAt,
+        acknowledged: config.acknowledgedVersion === state.latestTrustedVersion,
+    };
+}
+export async function checkTrustedUpdate(options) {
+    const checked = await checkedUpdate(options);
+    return "result" in checked ? checked.result : checked;
+}
+export function explainTrustedUpdate(options) {
+    const config = loadConfig(options);
+    return {
+        ...trustedUpdateStatus(options),
+        networkUsed: false,
+        policy: config?.policy ?? {
+            mode: "notify-only",
+            minimumReleaseAgeHours: 0,
+            approvedChannels: [],
+        },
+        metadataBaseUrl: config ? new URL(config.metadataBaseUrl).origin : null,
+        enterpriseMirrorOnly: config?.enterpriseMirrorOnly === true,
+        guarantees: [
+            "unsigned sources are never eligible",
+            "metadata and artifacts are bounded, signed, and digest-verified",
+            "repository identity, source paths, and usage data are never sent",
+            "manager-owned files are changed only through their owning package manager",
+        ],
+        limitations: [
+            "production use remains unavailable until the offline root ceremony installs a trust anchor",
+            "Homebrew activation is recommendation-only until a signed bottle rollback adapter is certified",
+        ],
+    };
+}
+function policyAllows(config, current, latest, age, now) {
+    if (!config.policy.approvedChannels.includes(config.channel))
+        return "release channel is not approved";
+    if (age < config.policy.minimumReleaseAgeHours)
+        return "release has not reached the minimum age";
+    if (config.policy.mode === "notify-only")
+        return "policy is notify-only";
+    if (config.policy.mode === "download-verify-only")
+        return null;
+    const from = parseVersion(current);
+    const to = parseVersion(latest);
+    if (!from || !to || compareVersions(latest, current) <= 0)
+        return "release is not a monotonic semantic version update";
+    if (from.core[0] !== to.core[0])
+        return "major updates require manual approval";
+    if (config.policy.mode === "apply-patch" && from.core[1] !== to.core[1])
+        return "policy permits patch releases only";
+    const windows = config.policy.maintenanceWindows;
+    if (windows && windows.length > 0) {
+        const hhmm = `${String(now.getUTCHours()).padStart(2, "0")}:${String(now.getUTCMinutes()).padStart(2, "0")}`;
+        if (!windows.some((window) => window.days.includes(now.getUTCDay()) && hhmm >= window.startUtc && hhmm < window.endUtc))
+            return "outside the configured maintenance window";
+    }
+    return null;
+}
+function requiredReleaseEvidenceDigests(custom) {
+    const candidates = {
+        provenance: custom.provenanceSha256,
+        sbom: custom.sbomSha256,
+        sbomAttestation: custom.sbomAttestationSha256,
+        releaseAttestation: custom.releaseAttestationSha256,
+    };
+    for (const [label, value] of Object.entries(candidates)) {
+        if (!value)
+            throw new Error(`signed ${label} digest is required before apply`);
+    }
+    return candidates;
+}
+function verifyReleaseEvidenceDigests(evidence, expected) {
+    for (const label of Object.keys(expected)) {
+        const actual = createHash("sha256").update(evidence[label]).digest("hex");
+        if (actual !== expected[label])
+            throw new Error(`${label} digest mismatch`);
+    }
+}
+function validateStoredReleasePaths(paths, quarantineRoot) {
+    const resolvedRoot = path.resolve(quarantineRoot);
+    const canonicalRoot = fs.realpathSync(resolvedRoot);
+    for (const [label, storedPath] of Object.entries(paths)) {
+        if (!storedPath.startsWith(`${resolvedRoot}${path.sep}`))
+            throw new Error(`${label} rollback evidence is outside quarantine`);
+        const expectedCanonical = path.join(canonicalRoot, path.relative(resolvedRoot, storedPath));
+        if (fs.realpathSync(storedPath) !== expectedCanonical)
+            throw new Error(`${label} rollback evidence traverses a quarantine symlink`);
+        const stat = fs.lstatSync(storedPath);
+        if (!stat.isFile() || stat.isSymbolicLink())
+            throw new Error(`${label} rollback evidence is not a regular file`);
+        const maximum = label === "artifact" ? MAX_ARTIFACT_BYTES : MAX_RELEASE_EVIDENCE_BYTES;
+        if (stat.size === 0 || stat.size > maximum)
+            throw new Error(`${label} rollback evidence exceeds its byte budget`);
+    }
+}
+async function quarantine(options, config, bundle, verifiedRoot, version) {
+    const releasePath = targetPath(config.targetPathTemplate, version);
+    const verified = verifyUpdateMetadataBundle(bundle, {
+        trustedRoot: verifiedRoot,
+        trustedRootSha256: createHash("sha256")
+            .update(canonicalizeUpdateMetadata(verifiedRoot))
+            .digest("hex"),
+        targetPath: releasePath,
+        now: options.now?.() ?? new Date(),
+    });
+    const requiredDigests = requiredReleaseEvidenceDigests(verified.target.custom);
+    const bytes = await fetchWithDeadline(options, config, safeUrl(config.metadataBaseUrl, releasePath), MAX_ARTIFACT_BYTES);
+    verifyTargetArtifact(bytes, verified.target);
+    const evidencePaths = {
+        provenance: `${releasePath}.provenance.json`,
+        sbom: `${releasePath}.sbom.cdx.json`,
+        sbomAttestation: `${releasePath}.sbom.attestation.json`,
+        releaseAttestation: `${releasePath}.release-attestation.json`,
+    };
+    const evidence = {
+        provenance: await fetchWithDeadline(options, config, safeUrl(config.metadataBaseUrl, evidencePaths.provenance), MAX_RELEASE_EVIDENCE_BYTES),
+        sbom: await fetchWithDeadline(options, config, safeUrl(config.metadataBaseUrl, evidencePaths.sbom), MAX_RELEASE_EVIDENCE_BYTES),
+        sbomAttestation: await fetchWithDeadline(options, config, safeUrl(config.metadataBaseUrl, evidencePaths.sbomAttestation), MAX_RELEASE_EVIDENCE_BYTES),
+        releaseAttestation: await fetchWithDeadline(options, config, safeUrl(config.metadataBaseUrl, evidencePaths.releaseAttestation), MAX_RELEASE_EVIDENCE_BYTES),
+    };
+    verifyReleaseEvidenceDigests(evidence, requiredDigests);
+    const attested = verifyReleaseAttestation(parseEnvelope(evidence.releaseAttestation, "release attestation"), {
+        artifact: bytes,
+        provenance: evidence.provenance,
+        sbom: evidence.sbom,
+        sbomAttestation: evidence.sbomAttestation,
+    });
+    if (attested.status !== "verified")
+        throw new Error(`release attestation is ${attested.status}; apply requires verified`);
+    if (attested.version !== verified.target.custom.version ||
+        attested.sourceCommit !== verified.target.custom.sourceCommit)
+        throw new Error("release attestation version or source commit mismatch");
+    if (attested.provenance.path !== path.basename(evidencePaths.provenance) ||
+        attested.sbom.path !== path.basename(evidencePaths.sbom) ||
+        attested.sbom.attestationPath !== path.basename(evidencePaths.sbomAttestation))
+        throw new Error("release attestation evidence path mismatch");
+    for (const mirror of config.crossCheckMetadataBaseUrls ?? []) {
+        const mirroredArtifact = await fetchWithDeadline(options, config, safeUrl(mirror, releasePath), MAX_ARTIFACT_BYTES);
+        verifyTargetArtifact(mirroredArtifact, verified.target);
+        for (const [label, relativePath] of Object.entries(evidencePaths)) {
+            const mirrored = await fetchWithDeadline(options, config, safeUrl(mirror, relativePath), MAX_RELEASE_EVIDENCE_BYTES);
+            const primaryDigest = createHash("sha256")
+                .update(evidence[label])
+                .digest("hex");
+            if (createHash("sha256").update(mirrored).digest("hex") !== primaryDigest)
+                throw new Error(`cross-channel ${label} mismatch`);
+        }
+    }
+    const root = path.join(path.dirname(statePath(options.stateHome)), "quarantine");
+    fs.mkdirSync(root, { recursive: true, mode: 0o700 });
+    const rootStat = fs.lstatSync(root);
+    if (!rootStat.isDirectory() || rootStat.isSymbolicLink())
+        throw new Error("quarantine root is not a private directory");
+    try {
+        fs.chmodSync(root, 0o700);
+    }
+    catch {
+        // Best effort on filesystems without POSIX modes (exclusive writes remain mandatory).
+    }
+    const directory = fs.mkdtempSync(path.join(root, `${version}-`));
+    try {
+        fs.chmodSync(directory, 0o700);
+    }
+    catch {
+        // Best effort on filesystems without POSIX modes (exclusive writes remain mandatory).
+    }
+    const artifactPath = path.join(directory, path.basename(releasePath));
+    const provenancePath = `${artifactPath}.provenance.json`;
+    const sbomPath = `${artifactPath}.sbom.cdx.json`;
+    const sbomAttestationPath = `${artifactPath}.sbom.attestation.json`;
+    const releaseAttestationPath = `${artifactPath}.release-attestation.json`;
+    fs.writeFileSync(artifactPath, bytes, { mode: 0o600, flag: "wx" });
+    fs.writeFileSync(provenancePath, evidence.provenance, { mode: 0o600, flag: "wx" });
+    fs.writeFileSync(sbomPath, evidence.sbom, { mode: 0o600, flag: "wx" });
+    fs.writeFileSync(sbomAttestationPath, evidence.sbomAttestation, { mode: 0o600, flag: "wx" });
+    fs.writeFileSync(releaseAttestationPath, evidence.releaseAttestation, {
+        mode: 0o600,
+        flag: "wx",
+    });
+    return {
+        artifactPath,
+        provenancePath,
+        sbomPath,
+        sbomAttestationPath,
+        releaseAttestationPath,
+        targetPath: releasePath,
+        attestedRollback: attested.rollback,
+    };
+}
+function validateAttestedRollback(candidate, expectedVersion, rollback) {
+    const actualDigest = createHash("sha256")
+        .update(fs.readFileSync(rollback.artifactPath))
+        .digest("hex");
+    if (candidate.attestedRollback.version !== expectedVersion ||
+        candidate.attestedRollback.targetPath !== rollback.targetPath ||
+        candidate.attestedRollback.artifactSha256 !== actualDigest)
+        throw new Error("release attestation rollback target mismatch");
+}
+function managerArgv(method, artifactPath) {
+    if (method === "npm")
+        return ["npm", "install", "--global", "--ignore-scripts", artifactPath];
+    return null;
+}
+async function restoreWithManager(options, rollbackArgv, failureMessage) {
+    const runManager = options.runManager;
+    if (!runManager)
+        throw new Error("owning package manager adapter is unavailable");
+    const restored = await runManager(rollbackArgv);
+    if (restored.status !== 0)
+        throw new Error(failureMessage);
+    if (!(await (options.healthCheck ?? (async () => false))()))
+        throw new Error("automatic rollback completed but the restored installation is unhealthy");
+    return "rolled-back";
+}
+async function activateAndValidate(options, activationArgv, rollbackArgv) {
+    const runManager = options.runManager;
+    if (!runManager)
+        throw new Error("owning package manager adapter is unavailable");
+    const activation = await runManager(activationArgv);
+    if (activation.status !== 0)
+        return restoreWithManager(options, rollbackArgv, "package manager activation and automatic rollback both failed");
+    const healthy = await (options.healthCheck ?? (async () => false))();
+    if (healthy)
+        return "applied";
+    return restoreWithManager(options, rollbackArgv, "health check failed and automatic rollback failed");
+}
+export async function applyTrustedUpdate(options) {
+    const checked = await checkedUpdate(options);
+    if (!("result" in checked))
+        return checked;
+    if (checked.result.status !== "update-available")
+        return checked.result;
+    const now = options.now?.() ?? new Date();
+    const blocked = policyAllows(checked.config, options.currentVersion, checked.target.custom.version, checked.result.releaseAgeHours ?? 0, now);
+    if (blocked)
+        return { ...checked.result, status: "policy-blocked", remediation: blocked };
+    try {
+        const candidate = await quarantine(options, checked.config, checked.bundle, checked.recoveredRoot, checked.target.custom.version);
+        if (checked.config.policy.mode === "download-verify-only")
+            return { ...checked.result, status: "downloaded", artifactPath: candidate.artifactPath };
+        const rollback = await quarantine(options, checked.config, checked.bundle, checked.recoveredRoot, options.currentVersion);
+        validateAttestedRollback(candidate, options.currentVersion, rollback);
+        if (!(await (options.smokeTest ?? (async () => false))(candidate.artifactPath)))
+            return {
+                ...checked.result,
+                status: "policy-blocked",
+                error: { code: "smoke-failed", message: "quarantined artifact failed its smoke test" },
+            };
+        const argv = managerArgv(installMethod(options), candidate.artifactPath);
+        if (!argv || !options.runManager)
+            return {
+                ...checked.result,
+                status: "manager-action-required",
+                artifactPath: candidate.artifactPath,
+                remediation: "Use the owning package manager with the exact verified quarantined artifact.",
+            };
+        const { attestedRollback: _attestedRollback, ...rollbackState } = rollback;
+        const state = {
+            ...checked.state,
+            rollback: {
+                version: options.currentVersion,
+                ...rollbackState,
+                bundle: checked.bundle,
+                rootChain: checked.rootChain,
+            },
+        };
+        privateWrite(statePath(options.stateHome), state);
+        const rollbackArgv = managerArgv(installMethod(options), rollback.artifactPath);
+        if (!rollbackArgv)
+            throw new Error("owning package manager cannot consume rollback artifact");
+        const activationStatus = await activateAndValidate(options, argv, rollbackArgv);
+        if (activationStatus === "rolled-back")
+            return { ...checked.result, status: "rolled-back", artifactPath: rollback.artifactPath };
+        privateWrite(statePath(options.stateHome), {
+            ...state,
+            installedVersion: checked.target.custom.version,
+            lastApplied: {
+                version: checked.target.custom.version,
+                artifactPath: candidate.artifactPath,
+                appliedAt: now.toISOString(),
+            },
+        });
+        return { ...checked.result, status: "applied", artifactPath: candidate.artifactPath };
+    }
+    catch (error) {
+        return {
+            ...checked.result,
+            status: "policy-blocked",
+            error: {
+                code: "apply-refused",
+                message: error instanceof Error ? error.message : String(error),
+            },
+        };
+    }
+}
+function verifyStoredRollback(options, config, state) {
+    const rollback = state.rollback;
+    if (!rollback)
+        return false;
+    const quarantineRoot = path.join(path.dirname(statePath(options.stateHome)), "quarantine");
+    try {
+        const storedPaths = {
+            artifact: path.resolve(rollback.artifactPath),
+            provenance: path.resolve(rollback.provenancePath),
+            sbom: path.resolve(rollback.sbomPath),
+            sbomAttestation: path.resolve(rollback.sbomAttestationPath),
+            releaseAttestation: path.resolve(rollback.releaseAttestationPath),
+        };
+        validateStoredReleasePaths(storedPaths, quarantineRoot);
+        const initialRoot = trustedRoot(config);
+        const recoveredRoot = verifyUpdateRootChain(initialRoot, config.trustedRootSha256, rollback.rootChain, new Date(state.checkedAt));
+        const verified = verifyUpdateMetadataBundle(rollback.bundle, {
+            trustedRoot: recoveredRoot,
+            trustedRootSha256: createHash("sha256")
+                .update(canonicalizeUpdateMetadata(recoveredRoot))
+                .digest("hex"),
+            targetPath: rollback.targetPath,
+            // Rollback is an offline recovery operation. Revalidate the exact
+            // metadata at the time it was originally accepted, then validate the
+            // stored bytes again; a network freeze check belongs to update check.
+            now: new Date(state.checkedAt),
+        });
+        if (verified.target.custom.version !== rollback.version)
+            return false;
+        const bytes = {
+            artifact: fs.readFileSync(storedPaths.artifact),
+            provenance: fs.readFileSync(storedPaths.provenance),
+            sbom: fs.readFileSync(storedPaths.sbom),
+            sbomAttestation: fs.readFileSync(storedPaths.sbomAttestation),
+            releaseAttestation: fs.readFileSync(storedPaths.releaseAttestation),
+        };
+        verifyTargetArtifact(bytes.artifact, verified.target);
+        const expected = requiredReleaseEvidenceDigests(verified.target.custom);
+        verifyReleaseEvidenceDigests({
+            provenance: bytes.provenance,
+            sbom: bytes.sbom,
+            sbomAttestation: bytes.sbomAttestation,
+            releaseAttestation: bytes.releaseAttestation,
+        }, expected);
+        const attested = verifyReleaseAttestation(parseEnvelope(bytes.releaseAttestation, "release attestation"), {
+            artifact: bytes.artifact,
+            provenance: bytes.provenance,
+            sbom: bytes.sbom,
+            sbomAttestation: bytes.sbomAttestation,
+        });
+        return (attested.status === "verified" &&
+            attested.version === verified.target.custom.version &&
+            attested.sourceCommit === verified.target.custom.sourceCommit);
+    }
+    catch {
+        return false;
+    }
+}
+export async function rollbackTrustedUpdate(options) {
+    const state = readTrustedUpdateState(options.stateHome);
+    const config = loadConfig(options);
+    if (!config)
+        return baseResult(options, "trust-unconfigured");
+    if (!state?.rollback || !verifyStoredRollback(options, config, state))
+        return baseResult(options, "rollback-unavailable");
+    const argv = managerArgv(installMethod(options), state.rollback.artifactPath);
+    if (!argv || !options.runManager)
+        return {
+            ...baseResult(options, "manager-action-required"),
+            artifactPath: state.rollback.artifactPath,
+        };
+    const action = await options.runManager(argv);
+    if (action.status !== 0 || !(await (options.healthCheck ?? (async () => false))())) {
+        return {
+            ...baseResult(options, "rollback-unavailable"),
+            error: {
+                code: "rollback-failed",
+                message: "owning package manager or health check rejected rollback",
+            },
+        };
+    }
+    privateWrite(statePath(options.stateHome), {
+        ...state,
+        installedVersion: state.rollback.version,
+    });
+    return { ...baseResult(options, "rolled-back"), artifactPath: state.rollback.artifactPath };
+}