Skip to content
Python
24.3 KB
Raw Blame
import { createHash } from "node:crypto";
import { createReadStream } from "node:fs";
import {
  chmod,
  lstat,
  mkdir,
  mkdtemp,
  open,
  readdir,
  readFile,
  realpath,
  rm,
  statfs,
} from "node:fs/promises";
import os from "node:os";
import path from "node:path";
import type { Readable } from "node:stream";
import axios from "axios";
import { HttpsProxyAgent } from "https-proxy-agent";
// proxy-from-env 2.1.0 ships ESM/CJS entrypoints but no TypeScript declarations.
// The one exported function used here is pinned by the package version and by
// the real HTTPS_PROXY/NO_PROXY acceptance test.
// @ts-expect-error upstream package has no declaration file
import { getProxyForUrl } from "proxy-from-env";
import * as tar from "tar";
import { verifyInstalledDistribution } from "./local-install.js";
import {
  CLI_PROTOCOL,
  CLI_SUPPORTED_RUNTIME_PROTOCOL,
  type ProtocolRange,
  protocolIncludes,
  protocolRange,
} from "./release-contract.js";

const SEMVER =
  /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
const SHA256 = /^[a-f0-9]{64}$/;
const COMMIT = /^[0-9a-f]{40}$/;
const SAFE_FILE_NAME = /^[0-9A-Za-z][0-9A-Za-z._-]{0,255}$/;
const REDIRECTS = new Set([301, 302, 303, 307, 308]);
const GITHUB_RELEASE_REDIRECT_HOSTS = [
  "release-assets.githubusercontent.com",
  "objects.githubusercontent.com",
] as const;

export type ReleaseChannel = "stable" | "prerelease";
export type RuntimeReleasePlatform = "darwin" | "linux";
export type RuntimeReleaseArch = "x64" | "arm64";

export interface RuntimeReleaseArtifact {
  kind: "runtime";
  platform: RuntimeReleasePlatform;
  arch: RuntimeReleaseArch;
  format: "tar.gz";
  filename: string;
  url: string;
  bytes: number;
  unpacked_bytes: number;
  sha256: string;
  runtime_manifest_schema: 1;
}

export interface DesktopReleaseArtifact {
  kind: "desktop";
  platform: "darwin";
  arch: RuntimeReleaseArch;
  format: "dmg";
  filename: string;
  url: string;
  bytes: number;
  sha256: string;
  minimum_system_version: string;
}

export interface MetadataReleaseArtifact {
  kind: "metadata";
  role: "sbom" | "notices";
  format: "spdx-json" | "markdown";
  filename: string;
  url: string;
  bytes: number;
  sha256: string;
}

export type ReleaseArtifact =
  | RuntimeReleaseArtifact
  | DesktopReleaseArtifact
  | MetadataReleaseArtifact;

export interface RuntimeReleaseManifest {
  schema_version: 1;
  product: "memhub-release";
  version: string;
  build_number: number;
  git_commit: string;
  channel: ReleaseChannel;
  cli_protocol: number;
  supported_runtime_protocol: ProtocolRange;
  runtime_protocol: number;
  supported_cli_protocol: ProtocolRange;
  published_at: string;
  artifacts: ReleaseArtifact[];
}

export interface HttpGetResponse {
  status: number;
  headers: Record<string, string | undefined>;
  body: AsyncIterable<Uint8Array>;
}

export type HttpGet = (
  url: string,
  options: { signal: AbortSignal; timeoutMs: number },
) => Promise<HttpGetResponse>;

export type StatfsAvailable = (
  directory: string,
) => Promise<{ bavail: number | bigint; bsize: number | bigint }>;

export interface AcquiredRuntimeDistribution {
  release: RuntimeReleaseManifest;
  artifact: RuntimeReleaseArtifact;
  temporary_root: string;
  distribution: string;
  cleanup(): Promise<void>;
  [Symbol.asyncDispose](): Promise<void>;
}

export interface ResolvedRuntimeRelease {
  release: RuntimeReleaseManifest;
  artifact: RuntimeReleaseArtifact;
  manifest_url: string;
  allowed_hosts: readonly string[];
}

export function parseRuntimeReleaseManifest(
  value: unknown,
): RuntimeReleaseManifest {
  if (!isObject(value)) throw new Error("release_manifest_invalid");
  const artifacts = value.artifacts;
  if (
    value.schema_version !== 1 ||
    value.product !== "memhub-release" ||
    typeof value.version !== "string" ||
    !SEMVER.test(value.version) ||
    !isBuildNumber(value.build_number) ||
    typeof value.git_commit !== "string" ||
    !COMMIT.test(value.git_commit) ||
    (value.channel !== "stable" && value.channel !== "prerelease") ||
    !isProtocolVersion(value.cli_protocol) ||
    !protocolRange(value.supported_runtime_protocol) ||
    !isProtocolVersion(value.runtime_protocol) ||
    !protocolRange(value.supported_cli_protocol) ||
    typeof value.published_at !== "string" ||
    !validTimestamp(value.published_at) ||
    !Array.isArray(artifacts) ||
    artifacts.length === 0 ||
    artifacts.length > 32
  ) {
    throw new Error("release_manifest_invalid");
  }
  if (
    value.cli_protocol !== CLI_PROTOCOL ||
    !protocolIncludes(CLI_SUPPORTED_RUNTIME_PROTOCOL, value.runtime_protocol) ||
    !protocolIncludes(
      value.supported_runtime_protocol,
      value.runtime_protocol,
    ) ||
    !protocolIncludes(value.supported_cli_protocol, CLI_PROTOCOL)
  ) {
    throw new Error("release_protocol_incompatible");
  }
  const parsed = artifacts.map(parseArtifact);
  const identities = new Set<string>();
  for (const artifact of parsed) {
    const identity =
      artifact.kind === "metadata"
        ? `${artifact.kind}/${artifact.role}`
        : `${artifact.kind}/${artifact.platform}/${artifact.arch}`;
    if (identities.has(identity)) throw new Error("release_manifest_invalid");
    identities.add(identity);
  }
  return Object.freeze({
    schema_version: 1,
    product: "memhub-release",
    version: value.version,
    build_number: value.build_number,
    git_commit: value.git_commit,
    channel: value.channel,
    cli_protocol: value.cli_protocol,
    supported_runtime_protocol: Object.freeze({
      min: value.supported_runtime_protocol.min,
      max: value.supported_runtime_protocol.max,
    }),
    runtime_protocol: value.runtime_protocol,
    supported_cli_protocol: Object.freeze({
      min: value.supported_cli_protocol.min,
      max: value.supported_cli_protocol.max,
    }),
    published_at: value.published_at,
    artifacts: Object.freeze(
      parsed.map((artifact) => Object.freeze(artifact)),
    ) as unknown as ReleaseArtifact[],
  });
}

export function selectRuntimeReleaseArtifact(
  release: RuntimeReleaseManifest,
  options: {
    version: string;
    channel: ReleaseChannel;
    platform: NodeJS.Platform;
    arch: string;
  },
): RuntimeReleaseArtifact {
  if (release.version !== options.version) {
    throw new Error("release_version_mismatch");
  }
  if (release.channel !== options.channel) {
    throw new Error("release_channel_mismatch");
  }
  if (options.platform !== "darwin" && options.platform !== "linux") {
    throw new Error("release_platform_unsupported");
  }
  if (options.arch !== "x64" && options.arch !== "arm64") {
    throw new Error("release_arch_unsupported");
  }
  const artifact = release.artifacts.find(
    (candidate): candidate is RuntimeReleaseArtifact =>
      candidate.kind === "runtime" &&
      candidate.platform === options.platform &&
      candidate.arch === options.arch,
  );
  if (!artifact) throw new Error("release_artifact_unavailable");
  return artifact;
}

export async function acquireRuntimeDistribution(options: {
  manifestUrl: string;
  expectedVersion: string;
  channel: ReleaseChannel;
  platform: NodeJS.Platform;
  arch: string;
  allowedHosts?: readonly string[];
  temporaryParent?: string;
  httpGet?: HttpGet;
  manifestTimeoutMs?: number;
  artifactTimeoutMs?: number;
  maxManifestBytes?: number;
  maxArtifactBytes?: number;
  maxUnpackedBytes?: number;
  maxRedirects?: number;
  statfsImpl?: StatfsAvailable;
}): Promise<AcquiredRuntimeDistribution> {
  const resolved = await resolveRuntimeRelease(options);
  const { release, artifact } = resolved;
  const allowedHosts = new Set(resolved.allowed_hosts);
  const httpGet = options.httpGet ?? defaultHttpGet;
  const artifactUrl = trustedUrl(artifact.url);
  const maxArtifactBytes = options.maxArtifactBytes ?? 2 * 1024 * 1024 * 1024;
  const maxUnpackedBytes = options.maxUnpackedBytes ?? 4 * 1024 * 1024 * 1024;
  if (
    artifact.bytes > maxArtifactBytes ||
    artifact.unpacked_bytes > maxUnpackedBytes
  ) {
    throw new Error("release_artifact_too_large");
  }

  const temporaryParent = path.resolve(options.temporaryParent ?? os.tmpdir());
  await assertDiskSpace(
    temporaryParent,
    artifact.bytes + artifact.unpacked_bytes,
    options.statfsImpl ?? statfs,
  );
  const temporaryRoot = await mkdtemp(
    path.join(temporaryParent, "memhub-runtime-"),
  );
  await chmod(temporaryRoot, 0o700);
  const archive = path.join(temporaryRoot, artifact.filename);
  const extracted = path.join(temporaryRoot, "extracted");
  try {
    await downloadArtifact(artifactUrl, archive, artifact, {
      httpGet,
      allowedHosts,
      timeoutMs: options.artifactTimeoutMs ?? 5 * 60_000,
      maxRedirects: options.maxRedirects ?? 3,
      maxBytes: maxArtifactBytes,
    });
    await mkdir(extracted, { mode: 0o700 });
    await extractRuntimeArchive(archive, extracted, artifact.unpacked_bytes);
    const distribution = await locateDistribution(extracted);
    const runtimeManifest = await verifyInstalledDistribution(
      distribution,
      options.platform,
      options.arch,
    );
    if (
      runtimeManifest.version !== release.version ||
      runtimeManifest.build_number !== release.build_number ||
      runtimeManifest.git_commit !== release.git_commit ||
      runtimeManifest.runtime_protocol !== release.runtime_protocol ||
      runtimeManifest.supported_cli_protocol?.min !==
        release.supported_cli_protocol.min ||
      runtimeManifest.supported_cli_protocol?.max !==
        release.supported_cli_protocol.max
    ) {
      throw new Error("release_runtime_identity_mismatch");
    }
    return Object.freeze({
      release,
      artifact,
      temporary_root: temporaryRoot,
      distribution,
      cleanup: () => rm(temporaryRoot, { recursive: true, force: true }),
      [Symbol.asyncDispose]: () =>
        rm(temporaryRoot, { recursive: true, force: true }),
    });
  } catch (error) {
    await rm(temporaryRoot, { recursive: true, force: true });
    throw error;
  }
}

export async function resolveRuntimeRelease(options: {
  manifestUrl: string;
  expectedVersion: string;
  channel: ReleaseChannel;
  platform: NodeJS.Platform;
  arch: string;
  allowedHosts?: readonly string[];
  httpGet?: HttpGet;
  manifestTimeoutMs?: number;
  maxManifestBytes?: number;
  maxRedirects?: number;
}): Promise<ResolvedRuntimeRelease> {
  const manifestUrl = trustedUrl(options.manifestUrl);
  const defaultHosts =
    normalizedHost(manifestUrl.hostname) === "github.com"
      ? [manifestUrl.hostname, ...GITHUB_RELEASE_REDIRECT_HOSTS]
      : [manifestUrl.hostname];
  const allowedHosts = new Set(
    (options.allowedHosts ?? defaultHosts).map(normalizedHost),
  );
  if (!allowedHosts.has(normalizedHost(manifestUrl.hostname))) {
    throw new Error("release_url_untrusted");
  }
  const httpGet = options.httpGet ?? defaultHttpGet;
  const manifestBytes = await fetchBytes(manifestUrl, {
    httpGet,
    allowedHosts,
    timeoutMs: options.manifestTimeoutMs ?? 15_000,
    maxBytes: options.maxManifestBytes ?? 1024 * 1024,
    maxRedirects: options.maxRedirects ?? 3,
  });
  let releaseValue: unknown;
  try {
    releaseValue = JSON.parse(
      new TextDecoder("utf-8", { fatal: true }).decode(manifestBytes),
    );
  } catch {
    throw new Error("release_manifest_invalid");
  }
  const release = parseRuntimeReleaseManifest(releaseValue);
  const artifact = selectRuntimeReleaseArtifact(release, {
    version: options.expectedVersion,
    channel: options.channel,
    platform: options.platform,
    arch: options.arch,
  });
  const artifactUrl = trustedUrl(artifact.url);
  if (!allowedHosts.has(normalizedHost(artifactUrl.hostname))) {
    throw new Error("release_url_untrusted");
  }
  return Object.freeze({
    release,
    artifact,
    manifest_url: manifestUrl.href,
    allowed_hosts: Object.freeze([...allowedHosts]),
  });
}

async function defaultHttpGet(
  url: string,
  options: { signal: AbortSignal; timeoutMs: number },
): Promise<HttpGetResponse> {
  const proxyUrl = getProxyForUrl(url);
  const httpsAgent = proxyUrl ? trustedProxyAgent(proxyUrl) : undefined;
  const response = await axios.get<Readable>(url, {
    responseType: "stream",
    timeout: options.timeoutMs,
    signal: options.signal,
    maxRedirects: 0,
    proxy: false,
    ...(httpsAgent ? { httpsAgent } : {}),
    validateStatus: () => true,
  });
  const headers: Record<string, string | undefined> = {};
  for (const [name, value] of Object.entries(response.headers)) {
    headers[name.toLowerCase()] = Array.isArray(value)
      ? value.join(", ")
      : value === undefined
        ? undefined
        : String(value);
  }
  return { status: response.status, headers, body: response.data };
}

function trustedProxyAgent(raw: string): HttpsProxyAgent<string> {
  let proxy: URL;
  try {
    proxy = new URL(raw);
  } catch {
    throw new Error("release_proxy_invalid");
  }
  if (
    (proxy.protocol !== "http:" && proxy.protocol !== "https:") ||
    proxy.hash !== "" ||
    (proxy.pathname !== "" && proxy.pathname !== "/") ||
    proxy.search !== ""
  ) {
    throw new Error("release_proxy_invalid");
  }
  return new HttpsProxyAgent(proxy);
}

async function fetchBytes(
  initial: URL,
  options: {
    httpGet: HttpGet;
    allowedHosts: Set<string>;
    timeoutMs: number;
    maxBytes: number;
    maxRedirects: number;
  },
): Promise<Uint8Array> {
  const chunks: Uint8Array[] = [];
  let total = 0;
  await forResponse(initial, options, async (response) => {
    const declared = contentLength(response.headers);
    if (declared !== null && declared > options.maxBytes) {
      throw new Error("release_response_too_large");
    }
    for await (const chunk of response.body) {
      total += chunk.byteLength;
      if (total > options.maxBytes)
        throw new Error("release_response_too_large");
      chunks.push(chunk);
    }
  });
  const body = new Uint8Array(total);
  let offset = 0;
  for (const chunk of chunks) {
    body.set(chunk, offset);
    offset += chunk.byteLength;
  }
  return body;
}

async function downloadArtifact(
  initial: URL,
  destination: string,
  artifact: RuntimeReleaseArtifact,
  options: {
    httpGet: HttpGet;
    allowedHosts: Set<string>;
    timeoutMs: number;
    maxRedirects: number;
    maxBytes: number;
  },
): Promise<void> {
  const digest = createHash("sha256");
  let total = 0;
  const file = await open(destination, "wx", 0o600);
  try {
    await forResponse(initial, options, async (response) => {
      const declared = contentLength(response.headers);
      if (declared !== null && declared !== artifact.bytes) {
        throw new Error("release_artifact_size_mismatch");
      }
      for await (const chunk of response.body) {
        total += chunk.byteLength;
        if (total > options.maxBytes || total > artifact.bytes) {
          throw new Error("release_response_too_large");
        }
        digest.update(chunk);
        await writeAll(file, chunk);
      }
    });
  } finally {
    await file.close();
  }
  if (total !== artifact.bytes)
    throw new Error("release_artifact_size_mismatch");
  if (digest.digest("hex") !== artifact.sha256) {
    throw new Error("release_artifact_hash_mismatch");
  }
}

async function forResponse(
  initial: URL,
  options: {
    httpGet: HttpGet;
    allowedHosts: Set<string>;
    timeoutMs: number;
    maxRedirects: number;
  },
  consume: (response: HttpGetResponse) => Promise<void>,
): Promise<void> {
  let current = initial;
  for (let redirect = 0; ; redirect += 1) {
    if (!options.allowedHosts.has(normalizedHost(current.hostname))) {
      throw new Error("release_url_untrusted");
    }
    const controller = new AbortController();
    const timeout = setTimeout(() => controller.abort(), options.timeoutMs);
    try {
      const response = await options.httpGet(current.href, {
        signal: controller.signal,
        timeoutMs: options.timeoutMs,
      });
      if (REDIRECTS.has(response.status)) {
        if (redirect >= options.maxRedirects) {
          throw new Error("release_redirect_limit");
        }
        const location = response.headers.location;
        if (!location) throw new Error("release_redirect_invalid");
        current = trustedUrl(new URL(location, current).href);
        continue;
      }
      if (response.status !== 200) {
        throw new Error(`release_http_status_${response.status}`);
      }
      await consume(response);
      return;
    } catch (error) {
      if (controller.signal.aborted)
        throw new Error("release_download_timeout");
      throw error;
    } finally {
      clearTimeout(timeout);
    }
  }
}

async function extractRuntimeArchive(
  archive: string,
  destination: string,
  maxUnpackedBytes: number,
): Promise<void> {
  const seen = new Set<string>();
  let total = 0;
  let validationError: Error | null = null;
  await tar.t({
    file: archive,
    gzip: true,
    strict: true,
    onentry(entry) {
      if (validationError !== null) return;
      try {
        validateTarEntry(entry.path, entry.type, entry.linkpath);
        if (seen.has(entry.path)) {
          throw new Error("release_archive_duplicate_path");
        }
        seen.add(entry.path);
        total += entry.size;
        if (total > maxUnpackedBytes) {
          throw new Error("release_archive_too_large");
        }
      } catch (error) {
        validationError =
          error instanceof Error ? error : new Error("release_archive_invalid");
      }
    },
  });
  if (validationError !== null) throw validationError;
  await tar.x({
    file: archive,
    cwd: destination,
    gzip: true,
    strict: true,
    preservePaths: false,
    noChmod: false,
    preserveOwner: false,
  });
}

async function writeAll(
  file: Awaited<ReturnType<typeof open>>,
  chunk: Uint8Array,
): Promise<void> {
  let offset = 0;
  while (offset < chunk.byteLength) {
    const { bytesWritten } = await file.write(
      chunk,
      offset,
      chunk.byteLength - offset,
    );
    if (bytesWritten <= 0) throw new Error("release_artifact_write_failed");
    offset += bytesWritten;
  }
}

export function validateTarEntry(
  entryPath: string,
  type: string,
  linkPath: string | undefined,
): void {
  if (!safeArchivePath(entryPath))
    throw new Error("release_archive_path_invalid");
  if (!["File", "Directory", "SymbolicLink", "Link"].includes(type)) {
    throw new Error("release_archive_type_invalid");
  }
  if (type === "SymbolicLink" || type === "Link") {
    if (
      !linkPath ||
      path.posix.isAbsolute(linkPath) ||
      linkPath.includes("\\")
    ) {
      throw new Error("release_archive_link_escapes");
    }
    const base = type === "Link" ? "." : path.posix.dirname(entryPath);
    const resolved = path.posix.normalize(path.posix.join(base, linkPath));
    if (!safeArchivePath(resolved))
      throw new Error("release_archive_link_escapes");
  }
}

async function locateDistribution(extracted: string): Promise<string> {
  if (await regularFile(path.join(extracted, "manifest.json")))
    return extracted;
  const entries = await readdir(extracted, { withFileTypes: true });
  const directories = entries.filter((entry) => entry.isDirectory());
  if (entries.length !== 1 || directories.length !== 1) {
    throw new Error("release_archive_layout_invalid");
  }
  const candidate = await realpath(path.join(extracted, directories[0].name));
  if (!(await regularFile(path.join(candidate, "manifest.json")))) {
    throw new Error("release_archive_layout_invalid");
  }
  return candidate;
}

async function regularFile(file: string): Promise<boolean> {
  const info = await lstat(file).catch(() => null);
  return info?.isFile() === true && !info.isSymbolicLink();
}

async function assertDiskSpace(
  directory: string,
  required: number,
  statfsImpl: StatfsAvailable,
): Promise<void> {
  const stats = await statfsImpl(directory);
  const available = Number(stats.bavail) * Number(stats.bsize);
  if (!Number.isSafeInteger(required) || required < 0 || available < required) {
    throw new Error("release_disk_space_insufficient");
  }
}

function parseArtifact(value: unknown): ReleaseArtifact {
  if (!isObject(value)) throw new Error("release_manifest_invalid");
  if (value.kind === "desktop") {
    if (
      value.platform !== "darwin" ||
      (value.arch !== "x64" && value.arch !== "arm64") ||
      value.format !== "dmg" ||
      typeof value.filename !== "string" ||
      !SAFE_FILE_NAME.test(value.filename) ||
      typeof value.url !== "string" ||
      !isPositiveSafeInteger(value.bytes) ||
      typeof value.sha256 !== "string" ||
      !SHA256.test(value.sha256) ||
      typeof value.minimum_system_version !== "string" ||
      !/^\d+\.\d+$/.test(value.minimum_system_version)
    ) {
      throw new Error("release_manifest_invalid");
    }
    trustedUrl(value.url);
    return value as unknown as DesktopReleaseArtifact;
  }
  if (value.kind === "metadata") {
    if (
      (value.role !== "sbom" && value.role !== "notices") ||
      (value.format !== "spdx-json" && value.format !== "markdown") ||
      typeof value.filename !== "string" ||
      !SAFE_FILE_NAME.test(value.filename) ||
      typeof value.url !== "string" ||
      !isPositiveSafeInteger(value.bytes) ||
      typeof value.sha256 !== "string" ||
      !SHA256.test(value.sha256)
    ) {
      throw new Error("release_manifest_invalid");
    }
    trustedUrl(value.url);
    return value as unknown as MetadataReleaseArtifact;
  }
  if (
    value.kind !== "runtime" ||
    (value.platform !== "darwin" && value.platform !== "linux") ||
    (value.arch !== "x64" && value.arch !== "arm64") ||
    value.format !== "tar.gz" ||
    typeof value.filename !== "string" ||
    !SAFE_FILE_NAME.test(value.filename) ||
    typeof value.url !== "string" ||
    !isPositiveSafeInteger(value.bytes) ||
    !isPositiveSafeInteger(value.unpacked_bytes) ||
    typeof value.sha256 !== "string" ||
    !SHA256.test(value.sha256) ||
    value.runtime_manifest_schema !== 1
  ) {
    throw new Error("release_manifest_invalid");
  }
  trustedUrl(value.url);
  return value as unknown as RuntimeReleaseArtifact;
}

function trustedUrl(raw: string): URL {
  let url: URL;
  try {
    url = new URL(raw);
  } catch {
    throw new Error("release_url_invalid");
  }
  if (
    url.protocol !== "https:" ||
    url.username !== "" ||
    url.password !== "" ||
    url.hash !== ""
  ) {
    throw new Error("release_url_invalid");
  }
  return url;
}

function safeArchivePath(value: string): boolean {
  if (
    value.length === 0 ||
    value.includes("\0") ||
    value.includes("\\") ||
    path.posix.isAbsolute(value)
  ) {
    return false;
  }
  const withoutTrailingSlash = value.endsWith("/") ? value.slice(0, -1) : value;
  const segments = withoutTrailingSlash.split("/");
  if (
    withoutTrailingSlash.length === 0 ||
    segments.some(
      (segment) => segment === "" || segment === "." || segment === "..",
    )
  ) {
    return false;
  }
  return path.posix.normalize(withoutTrailingSlash) === withoutTrailingSlash;
}

function contentLength(
  headers: Record<string, string | undefined>,
): number | null {
  const raw = headers["content-length"];
  if (raw === undefined) return null;
  if (!/^\d+$/.test(raw)) throw new Error("release_content_length_invalid");
  const value = Number(raw);
  if (!Number.isSafeInteger(value))
    throw new Error("release_content_length_invalid");
  return value;
}

function normalizedHost(value: string): string {
  return value.trim().toLowerCase();
}

function isObject(value: unknown): value is Record<string, unknown> {
  return value !== null && typeof value === "object" && !Array.isArray(value);
}

function isBuildNumber(value: unknown): value is number {
  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
}

function isPositiveSafeInteger(value: unknown): value is number {
  return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
}

function isProtocolVersion(value: unknown): value is number {
  return typeof value === "number" && Number.isSafeInteger(value) && value >= 1;
}

function validTimestamp(value: string): boolean {
  return (
    /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/.test(value) &&
    !Number.isNaN(Date.parse(value))
  );
}

export async function sha256File(file: string): Promise<string> {
  const digest = createHash("sha256");
  for await (const chunk of createReadStream(file)) digest.update(chunk);
  return digest.digest("hex");
}

export async function readReleaseManifestFile(
  file: string,
): Promise<RuntimeReleaseManifest> {
  return parseRuntimeReleaseManifest(JSON.parse(await readFile(file, "utf8")));
}