Skip to content
Python
34.8 KB
Raw Blame
import { createHash, randomUUID } from "node:crypto";
import { createReadStream } from "node:fs";
import {
  chmod,
  cp,
  lstat,
  mkdir,
  readdir,
  readFile,
  readlink,
  realpath,
  rename,
  rm,
  symlink,
} from "node:fs/promises";
import path from "node:path";
import {
  CLI_PROTOCOL,
  CLI_SUPPORTED_RUNTIME_PROTOCOL,
  type ProtocolRange,
  protocolIncludes,
  protocolRange,
} from "./release-contract.js";

export interface DistributionManifest {
  schema_version: 1;
  product: "one-memory-runtime";
  version: string;
  /** Monotonic ordering authority (docs/contracts/c0-anti-downgrade-versioning.md).
   * Optional while packages built before that contract still exist: when either
   * side of a transition omits it, ordering falls back to the pre-contract
   * exact-version behavior rather than inventing a number. */
  build_number?: number;
  git_commit?: string | null;
  runtime_protocol?: number;
  supported_cli_protocol?: ProtocolRange;
  platform: "darwin" | "linux" | "win32";
  arch: string;
  files: Record<string, string>;
}

export interface LocalInstallPlan {
  schema_version: 1;
  source: string;
  install_root: string;
  version_directory: string;
  current_link: string;
  version: string;
  build_number: number | null;
  /** Recorded so `applyLocalInstall` re-verifies with the same opt-in the plan
   * was created under; it does not itself authorize anything. */
  allow_downgrade: boolean;
  /** True when this plan replaces an equal `build_number` whose bytes differ.
   * The incoming build gets its own version directory and the superseded tree
   * is left in place, so the transition is still reversible. */
  same_build_replace: boolean;
  require_protocol_compatibility: boolean;
  platform: DistributionManifest["platform"];
  arch: string;
  files: number;
}

export interface LocalInstallReceipt extends LocalInstallPlan {
  previous_current_target: string | null;
  created_version: boolean;
}

export async function planLocalInstall(options: {
  source: string;
  installRoot: string;
  platform: NodeJS.Platform;
  arch: string;
  /** Explicit, per-invocation opt-in required to install a distribution whose
   * `build_number` is lower than the selected one. Default is refusal. */
  allowDowngrade?: boolean;
  /** Explicit, per-invocation opt-in required to replace an equal
   * `build_number` whose bytes differ. Default is refusal
   * (`installed_version_conflict`); see `inspectBuildNumberTransition`. */
  allowSameBuildReplace?: boolean;
  requireProtocolCompatibility?: boolean;
}): Promise<LocalInstallPlan> {
  if (!isPlatform(options.platform))
    throw new Error("distribution_platform_unsupported");
  const source = await realpath(options.source);
  const sourceInfo = await lstat(source);
  if (!sourceInfo.isDirectory() || sourceInfo.isSymbolicLink()) {
    throw new Error("distribution_source_invalid");
  }
  const manifest = await verifyDistribution(
    source,
    options.platform,
    options.arch,
  );
  if (options.requireProtocolCompatibility === true) {
    assertDistributionProtocolCompatibility(manifest);
  }
  const transition = await inspectBuildNumberTransition({
    installRoot: options.installRoot,
    incoming: manifest,
    incomingSource: source,
    allowDowngrade: options.allowDowngrade === true,
    allowSameBuildReplace: options.allowSameBuildReplace === true,
  });
  const files = Object.keys(manifest.files).sort();
  const installRoot = path.resolve(options.installRoot);
  if (overlaps(source, installRoot))
    throw new Error("distribution_install_overlap");
  // A numbered build must have its own version directory. Otherwise every
  // hourly package with the same displayed `version` (for example `0.0.0`)
  // lands in one path, and the equal-version same-tree check rejects a higher
  // build with `installed_version_conflict` before `current` can move.
  // Unnumbered pre-contract packages retain the legacy path.
  const id =
    manifest.build_number === undefined
      ? `${manifest.version}-${manifest.platform}-${manifest.arch}`
      : `${manifest.version}-b${manifest.build_number}-${manifest.platform}-${manifest.arch}`;
  return Object.freeze({
    schema_version: 1,
    source,
    install_root: installRoot,
    version_directory: path.join(
      installRoot,
      "versions",
      transition.sameBuildReplace
        ? `${id}-r${manifestFingerprint(manifest)}`
        : id,
    ),
    current_link: path.join(installRoot, "current"),
    version: manifest.version,
    build_number: manifest.build_number ?? null,
    allow_downgrade: options.allowDowngrade === true,
    same_build_replace: transition.sameBuildReplace,
    require_protocol_compatibility:
      options.requireProtocolCompatibility === true,
    platform: manifest.platform,
    arch: manifest.arch,
    files: files.length,
  });
}

export async function applyLocalInstall(
  plan: LocalInstallPlan,
): Promise<LocalInstallReceipt> {
  if (process.platform === "win32")
    throw new Error("windows_install_not_verified");
  const installRoot = path.resolve(plan.install_root);
  const versions = path.join(installRoot, "versions");
  const versionDirectory = path.resolve(plan.version_directory);
  const expectedParent = path.resolve(versions);
  const verified = await planLocalInstall({
    source: plan.source,
    installRoot,
    platform: plan.platform,
    arch: plan.arch,
    allowDowngrade: plan.allow_downgrade,
    allowSameBuildReplace: plan.same_build_replace,
    requireProtocolCompatibility: plan.require_protocol_compatibility,
  });
  if (
    path.dirname(versionDirectory) !== expectedParent ||
    versionDirectory !== verified.version_directory ||
    path.resolve(plan.current_link) !== verified.current_link ||
    plan.version !== verified.version ||
    plan.build_number !== verified.build_number ||
    plan.same_build_replace !== verified.same_build_replace ||
    plan.require_protocol_compatibility !==
      verified.require_protocol_compatibility ||
    plan.files !== verified.files
  ) {
    throw new Error("install_plan_invalid");
  }
  const installRootExisted = await lstat(installRoot).catch(() => null);
  const versionsExisted = await lstat(versions).catch(() => null);
  await assertExistingDirectoryAncestrySafe(installRoot);
  await mkdir(versions, { recursive: true, mode: 0o700 });
  if (!installRootExisted) await chmod(installRoot, 0o700);
  if (!versionsExisted) await chmod(versions, 0o700);
  await assertPrivateDirectory(installRoot);
  await assertPrivateDirectory(versions);
  await assertExistingDirectoryAncestrySafe(installRoot);
  const current = await lstat(plan.current_link).catch(() => null);
  let previousCurrentTarget: string | null = null;
  if (current) {
    if (!current.isSymbolicLink()) throw new Error("install_current_unmanaged");
    previousCurrentTarget = await readlink(plan.current_link);
    const target = path.resolve(installRoot, previousCurrentTarget);
    const relative = path.relative(versions, target);
    if (relative.startsWith("..") || path.isAbsolute(relative)) {
      throw new Error("install_current_unmanaged");
    }
  }
  const stage = `${versionDirectory}.stage.${randomUUID()}`;
  const temporaryLink = path.join(installRoot, `.current.${randomUUID()}`);
  let createdVersion = false;
  try {
    await cp(plan.source, stage, {
      recursive: true,
      dereference: false,
      verbatimSymlinks: true,
      errorOnExist: true,
      force: false,
    });
    await verifyDistribution(stage, plan.platform, plan.arch);
    const existing = await lstat(versionDirectory).catch(() => null);
    createdVersion = existing === null;
    if (existing) {
      if (!existing.isDirectory() || existing.isSymbolicLink()) {
        throw new Error("installed_version_unsafe");
      }
      await verifySameTree(stage, versionDirectory);
      await rm(stage, { recursive: true });
    } else {
      await rename(stage, versionDirectory);
    }
    await symlink(
      path.relative(installRoot, versionDirectory),
      temporaryLink,
      "dir",
    );
    await rename(temporaryLink, plan.current_link);
    const receipt = Object.freeze({
      ...plan,
      previous_current_target: previousCurrentTarget,
      created_version: createdVersion,
    });
    return receipt;
  } catch (error) {
    await rm(stage, { recursive: true, force: true });
    await rm(temporaryLink, { force: true });
    if (createdVersion) {
      await rm(versionDirectory, { recursive: true, force: true });
    }
    throw error;
  }
}

async function assertExistingDirectoryAncestrySafe(
  target: string,
): Promise<void> {
  const resolved = path.resolve(target);
  const root = path.parse(resolved).root;
  const parts = resolved.slice(root.length).split(path.sep).filter(Boolean);
  let current = root;
  for (const part of parts) {
    current = path.join(current, part);
    let info: Awaited<ReturnType<typeof lstat>>;
    try {
      info = await lstat(current);
    } catch (error) {
      if (
        error instanceof Error &&
        "code" in error &&
        error.code === "ENOENT"
      ) {
        return;
      }
      throw error;
    }
    if (
      info.isSymbolicLink() &&
      process.platform === "darwin" &&
      ["/tmp", "/var", "/etc"].includes(current)
    ) {
      current = await realpath(current);
      continue;
    }
    if (info.isSymbolicLink() || !info.isDirectory()) {
      throw new Error("install_root_unsafe");
    }
  }
}

export async function rollbackLocalInstall(
  receipt: LocalInstallReceipt,
): Promise<void> {
  if (
    !receipt ||
    receipt.schema_version !== 1 ||
    typeof receipt.install_root !== "string" ||
    typeof receipt.version_directory !== "string" ||
    typeof receipt.current_link !== "string" ||
    (receipt.previous_current_target !== null &&
      typeof receipt.previous_current_target !== "string") ||
    typeof receipt.created_version !== "boolean"
  ) {
    throw new Error("install_receipt_invalid");
  }
  if (process.platform === "win32")
    throw new Error("windows_install_not_verified");
  const installRoot = path.resolve(receipt.install_root);
  const versions = path.join(installRoot, "versions");
  const versionDirectory = path.resolve(receipt.version_directory);
  if (
    path.dirname(versionDirectory) !== versions ||
    path.resolve(receipt.current_link) !== path.join(installRoot, "current")
  ) {
    throw new Error("install_receipt_invalid");
  }
  const current = await lstat(receipt.current_link).catch(() => null);
  if (!current?.isSymbolicLink()) throw new Error("install_current_changed");
  const target = path.resolve(
    installRoot,
    await readlink(receipt.current_link),
  );
  if (target !== versionDirectory) throw new Error("install_current_changed");

  if (receipt.previous_current_target === null) {
    await rm(receipt.current_link);
  } else {
    const previous = path.resolve(installRoot, receipt.previous_current_target);
    const relative = path.relative(versions, previous);
    if (relative.startsWith("..") || path.isAbsolute(relative)) {
      throw new Error("install_receipt_invalid");
    }
    const temporaryLink = path.join(
      installRoot,
      `.current.rollback.${randomUUID()}`,
    );
    await symlink(receipt.previous_current_target, temporaryLink, "dir");
    await rename(temporaryLink, receipt.current_link);
  }
  if (receipt.created_version) {
    await rm(versionDirectory, { recursive: true });
  }
}

/**
 * Enforce the release anti-downgrade rule before any write.
 *
 * Ordering authority is `build_number` alone (see
 * `docs/contracts/c0-anti-downgrade-versioning.md`); version strings and
 * directory names are never compared. A lower incoming build is refused unless
 * the caller explicitly opted in. An equal build is only allowed when the
 * selected version directory already contains byte-identical content —
 * otherwise the install would silently swap an equal-build package, which the
 * contract classifies as `installed_version_conflict`.
 *
 * `allowSameBuildReplace` is an explicit, per-invocation escape from that last
 * rule, and it is off by default: a silent equal-build swap is precisely what
 * the refusal protects against. It exists for one caller shape — a runtime
 * shipped inside an app bundle that the OS has already signed and notarized.
 * Such a payload is trusted by construction, and refusing it leaves an affected
 * machine with an app that cannot start at all after a same-build re-release.
 * The replacement never edits the selected tree in place: the incoming build
 * lands in its own version directory and `current` moves atomically, so the
 * superseded tree stays available as a rollback.
 */
async function inspectBuildNumberTransition(options: {
  installRoot: string;
  incoming: DistributionManifest;
  incomingSource: string;
  allowDowngrade: boolean;
  allowSameBuildReplace: boolean;
}): Promise<{ sameBuildReplace: boolean }> {
  const installRoot = path.resolve(options.installRoot);
  const current = await lstat(path.join(installRoot, "current")).catch(
    () => null,
  );
  if (!current) return { sameBuildReplace: false };
  if (!current.isSymbolicLink()) throw new Error("install_current_unmanaged");
  const target = path.resolve(
    installRoot,
    await readlink(path.join(installRoot, "current")),
  );
  const versions = path.join(installRoot, "versions");
  const relative = path.relative(versions, target);
  if (relative.startsWith("..") || path.isAbsolute(relative)) {
    throw new Error("install_current_unmanaged");
  }
  let selectedVerified = true;
  let selected = await readManifest(target).catch(() => null);
  if (options.allowSameBuildReplace) {
    // The opt-in may replace a dirty tree, but only one whose build it can
    // still read: without a manifest the downgrade check below has nothing to
    // compare, and a newer runtime would be overwritten by an older one.
    if (selected === null) throw new Error("distribution_manifest_invalid");
    try {
      selected = await verifyDistribution(
        target,
        options.incoming.platform,
        options.incoming.arch,
      );
    } catch {
      selectedVerified = false;
    }
  }
  if (selected === null) return { sameBuildReplace: false };
  // Pre-contract packages have no `build_number`. Comparing them against an
  // invented ordinal would either break the hourly chain or manufacture a
  // downgrade; fall back to the prior exact-version behavior until both sides
  // are numbered.
  if (options.incoming.build_number === undefined)
    return { sameBuildReplace: false };
  if (selected.build_number === undefined) return { sameBuildReplace: false };
  if (options.incoming.build_number > selected.build_number)
    return { sameBuildReplace: false };
  if (options.incoming.build_number === selected.build_number) {
    if (!selectedVerified && options.allowSameBuildReplace) {
      return { sameBuildReplace: true };
    }
    // Same build: an idempotent reinstall is fine only if the bytes match. The
    // incoming source is verified, so compare it against the selected tree.
    try {
      await verifySameTree(options.incomingSource, target);
    } catch {
      if (!options.allowSameBuildReplace) {
        throw new Error("installed_version_conflict");
      }
      if (
        !isReleaseCommit(selected.git_commit) ||
        !isReleaseCommit(options.incoming.git_commit)
      ) {
        throw new Error("installed_version_conflict");
      }
      return { sameBuildReplace: true };
    }
    return { sameBuildReplace: false };
  }
  if (!options.allowDowngrade) {
    throw new Error("distribution_downgrade_refused");
  }
  return { sameBuildReplace: false };
}

/** Short, stable digest of the complete normalized manifest identity.
 *
 * Two packages of the same `build_number` whose bytes differ must not share a
 * version directory: `applyLocalInstall` compares the staged tree against the
 * directory it is about to occupy and would refuse the replacement before
 * `current` could move. Suffixing the directory with a payload fingerprint
 * keeps the equal-build replacement a plain "install then switch" operation. */
function manifestFingerprint(manifest: DistributionManifest): string {
  const packageId = (
    manifest as DistributionManifest & {
      package_id?: unknown;
    }
  ).package_id;
  const identity = {
    schema_version: manifest.schema_version,
    product: manifest.product,
    version: manifest.version,
    build_number: manifest.build_number ?? null,
    git_commit: manifest.git_commit ?? null,
    runtime_protocol: manifest.runtime_protocol ?? null,
    supported_cli_protocol: manifest.supported_cli_protocol ?? null,
    platform: manifest.platform,
    arch: manifest.arch,
    package_id: typeof packageId === "string" ? packageId : null,
    files: Object.fromEntries(
      Object.entries(manifest.files).sort(([left], [right]) =>
        left.localeCompare(right),
      ),
    ),
  };
  return createHash("sha256")
    .update(JSON.stringify(identity))
    .digest("hex")
    .slice(0, 16);
}

function isReleaseCommit(value: string | null | undefined): value is string {
  return typeof value === "string" && /^[0-9a-f]{40}$/.test(value);
}

async function assertPrivateDirectory(target: string): Promise<void> {
  const info = await lstat(target);
  if (
    !info.isDirectory() ||
    info.isSymbolicLink() ||
    (info.mode & 0o022) !== 0 ||
    (typeof process.getuid === "function" && info.uid !== process.getuid())
  ) {
    throw new Error("install_root_unsafe");
  }
}

async function readManifest(source: string): Promise<DistributionManifest> {
  let value: unknown;
  try {
    value = JSON.parse(
      await readFile(path.join(source, "manifest.json"), "utf8"),
    );
  } catch {
    throw new Error("distribution_manifest_invalid");
  }
  if (!value || typeof value !== "object")
    throw new Error("distribution_manifest_invalid");
  const manifest = value as Partial<DistributionManifest>;
  if (
    manifest.schema_version !== 1 ||
    manifest.product !== "one-memory-runtime" ||
    typeof manifest.version !== "string" ||
    !manifest.version ||
    (manifest.build_number !== undefined &&
      !isBuildNumber(manifest.build_number)) ||
    (manifest.git_commit !== undefined &&
      manifest.git_commit !== null &&
      (typeof manifest.git_commit !== "string" ||
        !/^[0-9a-f]{40}$/.test(manifest.git_commit))) ||
    (manifest.runtime_protocol !== undefined &&
      (!Number.isSafeInteger(manifest.runtime_protocol) ||
        manifest.runtime_protocol < 1)) ||
    (manifest.supported_cli_protocol !== undefined &&
      !protocolRange(manifest.supported_cli_protocol)) ||
    !isPlatform(manifest.platform) ||
    typeof manifest.arch !== "string" ||
    !manifest.arch ||
    !manifest.files ||
    typeof manifest.files !== "object" ||
    Array.isArray(manifest.files) ||
    Object.values(manifest.files).some(
      (digest) => typeof digest !== "string" || !/^[a-f0-9]{64}$/.test(digest),
    )
  ) {
    throw new Error("distribution_manifest_invalid");
  }
  return manifest as DistributionManifest;
}

export function assertDistributionProtocolCompatibility(
  manifest: DistributionManifest,
): void {
  if (
    manifest.runtime_protocol === undefined ||
    manifest.supported_cli_protocol === undefined
  ) {
    throw new Error("distribution_protocol_missing");
  }
  if (
    !protocolIncludes(
      CLI_SUPPORTED_RUNTIME_PROTOCOL,
      manifest.runtime_protocol,
    ) ||
    !protocolIncludes(manifest.supported_cli_protocol, CLI_PROTOCOL)
  ) {
    throw new Error("distribution_protocol_incompatible");
  }
}

/** A monotonically increasing, JS-safe non-negative integer. Not a boolean. */
function isBuildNumber(value: unknown): value is number {
  return (
    typeof value === "number" &&
    Number.isSafeInteger(value) &&
    value >= 0 &&
    !Number.isNaN(value)
  );
}

/** Verify an existing distribution without installation or repair. */
export async function verifyInstalledDistribution(
  directory: string,
  platform: NodeJS.Platform,
  arch: string,
): Promise<DistributionManifest> {
  return verifyDistribution(directory, platform, arch);
}

async function verifyDistribution(
  source: string,
  platform: NodeJS.Platform,
  arch: string,
): Promise<DistributionManifest> {
  const manifest = await readManifest(source);
  if (manifest.platform !== platform || manifest.arch !== arch) {
    throw new Error("distribution_target_mismatch");
  }
  await verifyPayloadArchitecture(source, manifest);
  const files = Object.keys(manifest.files).sort();
  if (
    !/^[0-9A-Za-z][0-9A-Za-z._-]{0,63}$/.test(manifest.version) ||
    !/^[0-9A-Za-z][0-9A-Za-z._-]{0,31}$/.test(manifest.arch) ||
    files.length === 0 ||
    files.some((file) => !safeRelative(file))
  ) {
    throw new Error("distribution_manifest_invalid");
  }
  const actual = await treeFiles(source);
  const expected = [...files, "manifest.json"].sort();
  if (JSON.stringify(actual) !== JSON.stringify(expected)) {
    throw new Error("distribution_manifest_incomplete");
  }
  for (const file of files) {
    if ((await sha256(path.join(source, file))) !== manifest.files[file]) {
      throw new Error("distribution_hash_mismatch");
    }
  }
  return manifest;
}

/** Native payloads whose Mach-O architecture must agree with the manifest.
 * `bin/node` is the bundled interpreter and `core/one-memory` is the packaged
 * Core; both are platform binaries. A forged `manifest.arch` must not be able
 * to smuggle an arm64 payload into an "x64" install. */
const NATIVE_PAYLOAD_FILES: Record<string, string[]> = {
  darwin: ["bin/node", "core/one-memory"],
};

/**
 * Refuse a distribution whose declared `arch` is not actually present in its
 * native binaries. Only reported on darwin today: other platforms keep their
 * existing manifest/hash validations until a real binary-format probe is
 * verified for them.
 */
async function verifyPayloadArchitecture(
  source: string,
  manifest: DistributionManifest,
): Promise<void> {
  const targets = NATIVE_PAYLOAD_FILES[manifest.platform];
  if (!targets) return;
  let verifiedSlices = 0;
  for (const relative of targets) {
    const file = path.join(source, relative);
    const info = await lstat(file).catch(() => null);
    if (!info) continue;
    const architectures = await machoArchitectures(file);
    // Some legitimate layouts replace a native payload with a launcher script
    // (the packaged-App installer writes `bin/node` as a shell launcher that
    // execs Electron). Those carry no architecture of their own, so they are
    // skipped -- but at least one real Mach-O slice must still be verified, and
    // any Mach-O that IS present must contain the declared architecture.
    if (architectures === null) continue;
    if (!architectures.includes(manifest.arch)) {
      throw new Error("distribution_arch_mismatch");
    }
    verifiedSlices += 1;
  }
  if (targets.length > 0 && verifiedSlices === 0) {
    // A darwin distribution with no inspectable native payload cannot prove its
    // declared architecture; fail closed rather than pass vacuously.
    throw new Error("distribution_arch_mismatch");
  }
}

// Mach-O file magic numbers. `*_CIGAM*` are the byte-swapped variants, which is
// how a little-endian host tells that a big-endian image follows.
const MH_MAGIC = 0xfeedface;
const MH_MAGIC_64 = 0xfeedfacf;
const MH_CIGAM = 0xcefaedfe;
const MH_CIGAM_64 = 0xcffaedfe;
const FAT_MAGIC = 0xcafebabe;
const FAT_CIGAM = 0xbebafeca;
const FAT_MAGIC_64 = 0xcafebabf;
const FAT_CIGAM_64 = 0xbfbafeca;

const CPU_ARCH_ABI64 = 0x01000000;
const CPU_TYPE_X86 = 7;
const CPU_TYPE_ARM = 12;
const CPU_TYPE_ARM64_32 = 12 | 0x02000000;

/** Map a Mach-O `cputype` to the architecture token used in manifests. */
function archName(cputype: number): string | null {
  switch (cputype) {
    case CPU_TYPE_X86:
      return "i386";
    case CPU_TYPE_X86 | CPU_ARCH_ABI64:
      return "x86_64";
    case CPU_TYPE_ARM:
      return "arm";
    case CPU_TYPE_ARM | CPU_ARCH_ABI64:
      return "arm64";
    case CPU_TYPE_ARM64_32:
      return "arm64_32";
    default:
      return null;
  }
}

/** Read the architecture list of a thin or fat Mach-O directly from its header.
 *
 * Deliberately does not shell out to `lipo`: the header is the authoritative
 * statement of the slice architecture, and parsing it keeps this check usable
 * on stripped build artifacts and in unit tests. Returns null when the file is
 * not a Mach-O this parser understands. */
async function machoArchitectures(file: string): Promise<string[] | null> {
  const bytes = await readFile(file).catch(() => null);
  if (bytes === null || bytes.length < 8) return null;
  const magic = bytes.readUInt32BE(0);
  if (
    magic === FAT_MAGIC ||
    magic === FAT_CIGAM ||
    magic === FAT_MAGIC_64 ||
    magic === FAT_CIGAM_64
  ) {
    // Fat headers store the byte order in the magic; read the count with the
    // matching endianness, then walk the fat_arch entries.
    const little = magic === FAT_CIGAM || magic === FAT_CIGAM_64;
    const read = (offset: number) =>
      little ? bytes.readUInt32LE(offset) : bytes.readUInt32BE(offset);
    const entrySize =
      magic === FAT_MAGIC_64 || magic === FAT_CIGAM_64 ? 32 : 20;
    const count = read(4);
    const architectures: string[] = [];
    for (let index = 0; index < count; index += 1) {
      const offset = 8 + index * entrySize;
      if (offset + 4 > bytes.length) return null;
      const name = archName(read(offset));
      if (name !== null) architectures.push(name);
    }
    return architectures.length > 0 ? architectures : null;
  }
  if (
    magic !== MH_MAGIC &&
    magic !== MH_MAGIC_64 &&
    magic !== MH_CIGAM &&
    magic !== MH_CIGAM_64
  ) {
    return null;
  }
  // A little-endian Mach-O stores `MH_MAGIC_64` (0xfeedfacf) as bytes
  // `cf fa ed fe`, which a big-endian read reports as `MH_CIGAM_64`. So the
  // byte-swapped magic is what marks a little-endian image on this host.
  const little = magic === MH_CIGAM || magic === MH_CIGAM_64;
  const cputype = little ? bytes.readUInt32LE(4) : bytes.readUInt32BE(4);
  const name = archName(cputype);
  return name === null ? null : [name];
}

async function treeFiles(root: string, current = root): Promise<string[]> {
  const { readdir } = await import("node:fs/promises");
  const entries = await readdir(current, { withFileTypes: true });
  entries.sort((left, right) => left.name.localeCompare(right.name));
  const result: string[] = [];
  for (const entry of entries) {
    // Finder may add this metadata file after installation. It is not Runtime
    // payload and must not make an otherwise verified install unreusable.
    if (entry.name === ".DS_Store") {
      if (!entry.isFile()) throw new Error("distribution_path_invalid");
      continue;
    }
    const target = path.join(current, entry.name);
    const relative = path.relative(root, target);
    if (!safeRelative(relative)) throw new Error("distribution_path_invalid");
    if (entry.isSymbolicLink()) {
      const link = await readlink(target);
      const resolved = path.resolve(path.dirname(target), link);
      if (path.relative(root, resolved).startsWith("..")) {
        throw new Error("distribution_link_escapes");
      }
      result.push(relative);
    } else if (entry.isDirectory()) {
      result.push(...(await treeFiles(root, target)));
    } else if (entry.isFile()) {
      result.push(relative);
    } else {
      throw new Error("distribution_path_invalid");
    }
  }
  return result.sort();
}

async function verifySameTree(left: string, right: string): Promise<void> {
  const leftFiles = await treeFiles(left);
  const rightFiles = await treeFiles(right);
  if (JSON.stringify(leftFiles) !== JSON.stringify(rightFiles)) {
    throw new Error("installed_version_conflict");
  }
  for (const file of leftFiles) {
    if (
      (await sha256(path.join(left, file))) !==
      (await sha256(path.join(right, file)))
    ) {
      throw new Error("installed_version_conflict");
    }
  }
}

async function sha256(file: string): Promise<string> {
  const digest = createHash("sha256");
  const info = await lstat(file);
  if (info.isSymbolicLink()) {
    digest.update("symlink\0");
    digest.update(await readlink(file));
    return digest.digest("hex");
  }
  for await (const chunk of createReadStream(file)) digest.update(chunk);
  return digest.digest("hex");
}

function safeRelative(value: string): boolean {
  return (
    value.length > 0 &&
    !path.isAbsolute(value) &&
    value !== ".." &&
    !value.startsWith(`..${path.sep}`) &&
    !value.includes("\0")
  );
}

function overlaps(left: string, right: string): boolean {
  const fromLeft = path.relative(left, right);
  const fromRight = path.relative(right, left);
  return (
    fromLeft === "" ||
    (!fromLeft.startsWith("..") && !path.isAbsolute(fromLeft)) ||
    (!fromRight.startsWith("..") && !path.isAbsolute(fromRight))
  );
}

function isPlatform(value: unknown): value is DistributionManifest["platform"] {
  return value === "darwin" || value === "linux" || value === "win32";
}

export interface LocalUninstallPlan {
  schema_version: 1;
  install_root: string;
  current_link: string;
  version_directories: string[];
  cli_link: string | null;
  /** Never touched. Stated in the plan so a reader can see the boundary. */
  preserved_data_dir: string | null;
  stops_service: boolean;
}

export interface LocalUninstallReceipt extends LocalUninstallPlan {
  removed_current_link: boolean;
  removed_version_directories: string[];
  removed_cli_link: boolean;
}

/**
 * Plan removing the managed installation.
 *
 * The rule this exists to enforce: uninstall removes the *program*, never the
 * *data*. `dataDir` is passed so the plan can name it as preserved — a reader
 * should be able to see the boundary rather than infer it — and it is also
 * checked against the subtree being deleted. If the user pointed the data
 * directory inside `<install-root>/versions/`, the recursive removal would
 * destroy their data while the plan still advertised it as preserved; refusing
 * here is the only honest outcome, and the CLI calls this before it stops the
 * service or touches any file, so the refusal is a no-op on disk.
 */
export async function planLocalUninstall(options: {
  installRoot: string;
  home: string;
  dataDir: string | null;
  cliLinkPath: string | null;
  stopsService: boolean;
  /** Explicit per-invocation override for the "data inside the removed
   * subtree" refusal. It does NOT make the data safe: it only changes which
   * directory the plan is asked to protect, so the caller must have moved the
   * data out first. Recorded in the plan so a reader can audit the choice. */
  preserveDataDir?: boolean;
}): Promise<LocalUninstallPlan> {
  const installRoot = path.resolve(options.installRoot);
  const versions = path.join(installRoot, "versions");
  // The data directory is out of scope for uninstall. If it happens to live
  // inside the subtree we delete recursively (e.g. the user pointed --data-dir
  // at <install-root>/versions/<something>), removing that subtree would
  // silently destroy their data while the plan still advertises it as
  // preserved. Refuse instead of lying: moving it out is a user decision.
  // `preserveDataDir` is the escape hatch: when the user really did point the
  // data directory inside the subtree we delete recursively, the only ways out
  // are (a) move the data out and retry, or (b) explicitly confirm that THIS
  // invocation must not consider that directory. Without (b) the service could
  // never be uninstalled at all -- the guard would strand it. With (b) the
  // caller has stated, per invocation, what it is protecting, and the plan
  // records that stated boundary instead of silently deleting it.
  if (
    !options.preserveDataDir &&
    options.dataDir !== null &&
    overlaps(path.resolve(options.dataDir), versions)
  ) {
    throw new Error("uninstall_data_inside_install_root");
  }
  const entries = await readdir(versions).catch(() => []);
  // Never list the preserved data directory for deletion, even when it lives
  // under versions/. `preserved_data_dir` has to mean it, otherwise the plan
  // advertises protection while the same plan deletes the directory as if it
  // were a managed version.
  const protectedDataDir =
    options.dataDir === null ? null : path.resolve(options.dataDir);
  const versionDirectories: string[] = [];
  for (const entry of entries) {
    const candidate = path.join(versions, entry);
    if (protectedDataDir !== null && overlaps(candidate, protectedDataDir)) {
      continue;
    }
    const info = await lstat(candidate).catch(() => null);
    if (info?.isDirectory() && !info.isSymbolicLink()) {
      versionDirectories.push(candidate);
    }
  }
  versionDirectories.sort();
  return {
    schema_version: 1,
    install_root: installRoot,
    current_link: path.join(installRoot, "current"),
    version_directories: versionDirectories,
    cli_link: options.cliLinkPath,
    preserved_data_dir: options.dataDir,
    stops_service: options.stopsService,
  };
}

export async function applyLocalUninstall(
  plan: LocalUninstallPlan,
): Promise<LocalUninstallReceipt> {
  return applyLocalUninstallInternal(plan);
}

/** Internal safety harness for the future managed release implementation. */
export async function applyLocalUninstallInternal(
  plan: LocalUninstallPlan,
): Promise<LocalUninstallReceipt> {
  if (process.platform === "win32")
    throw new Error("windows_install_not_verified");
  const installRoot = path.resolve(plan.install_root);
  const versions = path.join(installRoot, "versions");
  const removedVersionDirectories: string[] = [];
  // Only paths under the install root are touched, and each is re-checked: a
  // plan is data, and data can be stale by the time it is applied.
  for (const directory of plan.version_directories) {
    const resolved = path.resolve(directory);
    if (path.dirname(resolved) !== versions)
      throw new Error("uninstall_path_unsafe");
    await rm(resolved, { recursive: true });
    removedVersionDirectories.push(resolved);
  }
  const current = path.resolve(plan.current_link);
  if (current !== path.join(installRoot, "current")) {
    throw new Error("uninstall_path_unsafe");
  }
  const info = await lstat(current).catch(() => null);
  const removedCurrentLink = Boolean(info);
  if (info) {
    await rm(current);
  }
  let removedCliLink = false;
  if (plan.cli_link) {
    // Only remove the PATH entry this product created: a symlink pointing at
    // `<install_root>/current/bin/one-memory`. A regular file, a directory or a
    // symlink to something else belongs to the user (or another tool) and must
    // survive an uninstall. Verified defect: the previous version removed any
    // object here, deleting a foreign `one-memory` file the user had put there.
    const linkInfo = await lstat(plan.cli_link).catch(() => null);
    if (linkInfo?.isSymbolicLink()) {
      const target = path.resolve(
        path.dirname(plan.cli_link),
        await readlink(plan.cli_link),
      );
      const expected = path.join(installRoot, "current", "bin", "one-memory");
      if (target === expected) {
        await rm(plan.cli_link);
        removedCliLink = true;
      }
    }
  }
  return {
    ...plan,
    removed_current_link: removedCurrentLink,
    removed_version_directories: removedVersionDirectories,
    removed_cli_link: removedCliLink,
  };
}