@runuai/host 0.9.14 → 0.9.43

package/lib/runtime-archive.ts

@@ -0,0 +1,1086 @@
+import { createHash } from "node:crypto";
+import { constants as fsConstants } from "node:fs";
+import {
+  chmod,
+  mkdir,
+  open,
+  symlink,
+} from "node:fs/promises";
+import path from "node:path";
+import { gzipSync, gunzipSync } from "node:zlib";
+
+import {
+  MAX_RELEASE_ARTIFACT_BYTES,
+  type ReleaseArtifact,
+  verifyReleaseArtifactIntegrity,
+} from "./release-manifest";
+
+const BLOCK_SIZE = 512;
+const MAX_UNCOMPRESSED_BYTES = 1024 * 1024 * 1024;
+const MAX_ARCHIVE_MEMBERS = 100_000;
+const MAX_MEMBER_PATH_BYTES = 4096;
+const MAX_PAX_BYTES = 64 * 1024;
+const MAX_RUNTIME_ASSET_MANIFEST_BYTES = 2 * 1024 * 1024;
+export const MAX_RUNTIME_ASSET_ENTRIES = 10_000;
+export const MAX_RUNTIME_ASSET_BYTES = 512 * 1024 * 1024;
+const ZERO_BLOCK = Buffer.alloc(BLOCK_SIZE);
+const BASE_TOP_LEVEL = Object.freeze(["agent", "bin", "node", "runtime.json"]);
+export const BUNDLED_RUNTIME_ROOT = "agent/bundled-runtime" as const;
+export const BUNDLED_RUNTIME_CAPABILITY =
+  "agent/bundled-runtime/capability.json" as const;
+/** Plugin directory == plugin binary name in Apple's signed pkg payload. */
+const APPLE_CONTAINER_PLUGINS = Object.freeze([
+  "container-core-images",
+  "container-network-vmnet",
+  "container-runtime-linux",
+  "k8s",
+  "machine-apiserver",
+]);
+const STANDARD_IMAGE_ASSETS = Object.freeze([
+  Object.freeze({ path: "Dockerfile", mode: 0o644 as const }),
+  Object.freeze({ path: "README.md", mode: 0o644 as const }),
+  Object.freeze({ path: "container/code-server-settings.json", mode: 0o644 as const }),
+  Object.freeze({ path: "container/corepack-version", mode: 0o644 as const }),
+  Object.freeze({ path: "container/uai-init", mode: 0o755 as const }),
+  Object.freeze({ path: "container/uai-materialize-runtimes", mode: 0o755 as const }),
+  Object.freeze({ path: "tool-versions", mode: 0o644 as const }),
+]);
+const RUNTIME_ASSET_ROOTS = Object.freeze([
+  "apple-container",
+  "host-assets",
+  "kernel",
+  "licenses",
+]);
+export const REQUIRED_RUNTIME_LICENSES = Object.freeze([
+  "Container-LICENSE",
+  "Kernel-GPL-2.0",
+]);
+const VERSION = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)$/;
+const SHA256 = /^[a-f0-9]{64}$/;
+
+interface RuntimeDescriptorCommon {
+  readonly hostVersion: string;
+  readonly platform: string;
+  readonly node: {
+    readonly version: string;
+    readonly modules: string;
+  };
+  readonly requirements: Readonly<Record<string, string>>;
+  readonly layout: {
+    readonly agent: "agent";
+    readonly launcher: "bin/uai-host";
+    readonly node: "node";
+  };
+}
+
+export interface RuntimeDescriptorV1 extends RuntimeDescriptorCommon {
+  readonly schemaVersion: 1;
+}
+
+export interface BundledRuntimeDescriptor {
+  readonly assetFingerprint: string;
+  readonly versions: {
+    readonly container: string;
+    readonly kata: string;
+    readonly guestKernel: string;
+  };
+  readonly requirements: {
+    readonly os: "darwin";
+    readonly arch: "arm64";
+    readonly minVersion: string;
+  };
+  readonly teamIdentifier: string;
+  readonly layout: {
+    readonly assetSourceRoot: "agent/bundled-runtime";
+    readonly assetManifest: "agent/bundled-runtime/assets.json";
+    readonly containerCli: "agent/bundled-runtime/apple-container/bin/container";
+    readonly apiserver: "agent/bundled-runtime/apple-container/bin/container-apiserver";
+    readonly plugins: "agent/bundled-runtime/apple-container/libexec/container/plugins";
+    readonly kernel: "agent/bundled-runtime/kernel/vmlinux";
+    readonly standardImage: "agent/bundled-runtime/host-assets/standard-image";
+    readonly licenses: "agent/bundled-runtime/licenses";
+  };
+}
+
+export interface RuntimeCapabilityDescriptorV3 {
+  readonly capabilitySchemaVersion: 3;
+  readonly bundledRuntime: BundledRuntimeDescriptor;
+}
+
+export type RuntimeDescriptor = RuntimeDescriptorV1;
+export type ResolvedRuntimeDescriptor = RuntimeDescriptor & (
+  | { readonly capabilitySchemaVersion: 1 }
+  | RuntimeCapabilityDescriptorV3
+);
+
+export interface RuntimeAssetManifestEntry {
+  readonly path: string;
+  readonly type: "file";
+  readonly mode: 0o644 | 0o755;
+  readonly size: number;
+  readonly sha256: string;
+}
+
+export interface RuntimeAssetManifest {
+  readonly schemaVersion: 1;
+  readonly fingerprint: string;
+  readonly entries: readonly RuntimeAssetManifestEntry[];
+}
+
+interface ArchiveEntry {
+  readonly memberPath: string;
+  readonly type: "0" | "2" | "5";
+  readonly mode: number;
+  readonly data: Buffer;
+  readonly linkTarget: string;
+  readonly resolvedLinkTarget: string | null;
+}
+
+export interface InspectedRuntimeArchive {
+  readonly descriptor: RuntimeDescriptor;
+  readonly capabilities:
+    | { readonly capabilitySchemaVersion: 1 }
+    | RuntimeCapabilityDescriptorV3;
+  readonly memberCount: number;
+}
+
+/**
+ * Read, count and hash one already-downloaded regular file through one open
+ * descriptor. Extraction consumes the exact returned bytes; there is no
+ * verify-by-name/reopen window in which the pathname could be swapped.
+ */
+export async function readVerifiedArtifactFile(
+  archivePath: string,
+  artifact: ReleaseArtifact,
+): Promise<Buffer> {
+  const noFollow = fsConstants.O_NOFOLLOW ?? 0;
+  const handle = await open(archivePath, fsConstants.O_RDONLY | noFollow);
+  try {
+    const before = await handle.stat();
+    if (!before.isFile()) throw new Error("runtime archive must be a regular file");
+    if (before.size > MAX_RELEASE_ARTIFACT_BYTES) {
+      throw new Error(`runtime archive exceeds ${MAX_RELEASE_ARTIFACT_BYTES} bytes`);
+    }
+
+    const hash = createHash("sha256");
+    const chunks: Buffer[] = [];
+    let size = 0;
+    for await (const raw of handle.createReadStream({ autoClose: false })) {
+      const chunk = Buffer.isBuffer(raw) ? raw : Buffer.from(raw);
+      size += chunk.length;
+      if (size > MAX_RELEASE_ARTIFACT_BYTES) {
+        throw new Error(`runtime archive exceeds ${MAX_RELEASE_ARTIFACT_BYTES} bytes`);
+      }
+      hash.update(chunk);
+      chunks.push(chunk);
+    }
+    const after = await handle.stat();
+    if (
+      before.dev !== after.dev ||
+      before.ino !== after.ino ||
+      before.size !== after.size ||
+      size !== after.size
+    ) {
+      throw new Error("runtime archive changed while it was being verified");
+    }
+    verifyReleaseArtifactIntegrity(artifact, {
+      size,
+      sha256: hash.digest(),
+    });
+    return Buffer.concat(chunks, size);
+  } finally {
+    await handle.close();
+  }
+}
+
+export async function extractVerifiedRuntimeArchive(
+  archiveBytes: Buffer,
+  destination: string,
+  expected: { version: string; platform: string },
+): Promise<InspectedRuntimeArchive> {
+  const { entries, descriptor, capabilities } = inspectRuntimeArchive(
+    archiveBytes,
+    expected,
+  );
+  // The caller gives us a fresh, private staging path. `recursive: false`
+  // refuses to merge archive contents into any pre-existing tree.
+  await mkdir(destination, { mode: 0o700, recursive: false });
+  const directories = [destination];
+
+  for (const entry of entries) {
+    const output = path.join(destination, ...entry.memberPath.split("/"));
+    if (entry.type === "5") {
+      await mkdir(output, { mode: 0o755, recursive: false });
+      await chmod(output, 0o755);
+      directories.push(output);
+    } else if (entry.type === "0") {
+      const handle = await open(output, "wx", entry.mode);
+      try {
+        await handle.writeFile(entry.data);
+        await handle.chmod(entry.mode);
+        await handle.sync();
+      } finally {
+        await handle.close();
+      }
+    }
+  }
+  // Create links only after every regular target exists. Archive validation
+  // has already rejected absolute/escaping targets and any child below a link.
+  for (const entry of entries) {
+    if (entry.type !== "2") continue;
+    const output = path.join(destination, ...entry.memberPath.split("/"));
+    await symlink(entry.linkTarget, output);
+  }
+  // Persist children before parents so activation never points at a directory
+  // whose archive contents only existed in the page cache at power loss.
+  for (const directory of directories.reverse()) {
+    await syncDirectory(directory);
+  }
+  return { descriptor, capabilities, memberCount: entries.length };
+}
+
+export function inspectRuntimeArchive(
+  archiveBytes: Buffer,
+  expected: { version: string; platform: string },
+): {
+  entries: readonly ArchiveEntry[];
+  descriptor: RuntimeDescriptor;
+  capabilities:
+    | { readonly capabilitySchemaVersion: 1 }
+    | RuntimeCapabilityDescriptorV3;
+} {
+  assertCanonicalGzipHeader(archiveBytes);
+  const tar = gunzipSync(archiveBytes, { maxOutputLength: MAX_UNCOMPRESSED_BYTES });
+  // The release builder emits a single deterministic gzip stream. Rebuilding
+  // it under the packaged, exactly-pinned Node rejects concatenated streams,
+  // trailing bytes and alternate encodings before any filesystem mutation.
+  // Modern Node always writes a zero gzip mtime (the option was removed from
+  // its public typings); the builder runs the same pinned Node patch.
+  const canonical = gzipSync(tar, { level: 9 });
+  canonical[9] = 255;
+  if (!archiveBytes.equals(canonical)) {
+    throw new Error("runtime archive gzip stream is not canonical");
+  }
+
+  const entries: ArchiveEntry[] = [];
+  const byPath = new Map<string, ArchiveEntry>();
+  let offset = 0;
+  let pendingPax: { path?: string; linkpath?: string } | null = null;
+  let previousMember: string | null = null;
+  let terminated = false;
+
+  while (offset + BLOCK_SIZE <= tar.length) {
+    const header = tar.subarray(offset, offset + BLOCK_SIZE);
+    if (header.equals(ZERO_BLOCK)) {
+      if (
+        offset + 2 * BLOCK_SIZE !== tar.length ||
+        !tar.subarray(offset + BLOCK_SIZE).equals(ZERO_BLOCK)
+      ) {
+        throw new Error("runtime archive has trailing bytes or an invalid terminator");
+      }
+      offset += 2 * BLOCK_SIZE;
+      terminated = true;
+      break;
+    }
+
+    validateHeaderChecksum(header);
+    if (parseString(header, 257, 6) !== "ustar") {
+      throw new Error("runtime archive is not ustar");
+    }
+    const name = parseString(header, 0, 100);
+    const prefix = parseString(header, 345, 155);
+    const headerPath = prefix ? `${prefix}/${name}` : name;
+    const mode = parseOctal(header, 100, 8, "mode");
+    const uid = parseOctal(header, 108, 8, "uid");
+    const gid = parseOctal(header, 116, 8, "gid");
+    const size = parseOctal(header, 124, 12, "size");
+    const mtime = parseOctal(header, 136, 12, "mtime");
+    const type = (parseString(header, 156, 1) || "0") as string;
+    const rawLinkTarget = parseString(header, 157, 100);
+    if (
+      uid !== 0 ||
+      gid !== 0 ||
+      mtime !== 0 ||
+      parseString(header, 265, 32) !== "root" ||
+      parseString(header, 297, 32) !== "root" ||
+      parseOctal(header, 329, 8, "devmajor") !== 0 ||
+      parseOctal(header, 337, 8, "devminor") !== 0
+    ) {
+      throw new Error("runtime archive metadata is not canonical");
+    }
+    if (!Number.isSafeInteger(size) || size < 0 || size > MAX_UNCOMPRESSED_BYTES) {
+      throw new Error("runtime archive member size is invalid");
+    }
+    const dataStart = offset + BLOCK_SIZE;
+    const dataEnd = dataStart + size;
+    const paddedEnd = dataStart + Math.ceil(size / BLOCK_SIZE) * BLOCK_SIZE;
+    if (dataEnd > tar.length || paddedEnd > tar.length) {
+      throw new Error("runtime archive member exceeds input");
+    }
+    if (tar.subarray(dataEnd, paddedEnd).some((byte) => byte !== 0)) {
+      throw new Error(`runtime archive member padding is not zero: ${headerPath}`);
+    }
+    const data = tar.subarray(dataStart, dataEnd);
+    offset = paddedEnd;
+
+    if (type === "x") {
+      if (pendingPax) throw new Error("runtime archive has consecutive pax headers");
+      if (size > MAX_PAX_BYTES || mode !== 0o644) {
+        throw new Error("runtime archive pax header is invalid");
+      }
+      pendingPax = parsePax(data);
+      continue;
+    }
+    if (type !== "0" && type !== "2" && type !== "5") {
+      throw new Error(`unsupported runtime archive member type: ${type}`);
+    }
+    const rawMemberPath = pendingPax?.path ?? headerPath;
+    if ((type === "5") !== rawMemberPath.endsWith("/")) {
+      throw new Error(`runtime archive member path/type mismatch: ${rawMemberPath}`);
+    }
+    const memberPath = safeMemberPath(rawMemberPath);
+    if (
+      previousMember !== null &&
+      Buffer.compare(Buffer.from(previousMember), Buffer.from(memberPath)) >= 0
+    ) {
+      throw new Error(`runtime archive members are not strictly sorted: ${memberPath}`);
+    }
+    previousMember = memberPath;
+    if (byPath.has(memberPath)) {
+      throw new Error(`duplicate runtime archive member: ${memberPath}`);
+    }
+    if (entries.length >= MAX_ARCHIVE_MEMBERS) {
+      throw new Error(`runtime archive exceeds ${MAX_ARCHIVE_MEMBERS} members`);
+    }
+    if (type !== "0" && size !== 0) {
+      throw new Error(`non-file runtime archive member carries data: ${memberPath}`);
+    }
+    const expectedMode = type === "5" ? 0o755 : type === "2" ? 0o777 : mode;
+    if (
+      mode !== expectedMode ||
+      (type === "0" && mode !== 0o644 && mode !== 0o755)
+    ) {
+      throw new Error(`runtime archive member mode is invalid: ${memberPath}`);
+    }
+    const linkTarget = pendingPax?.linkpath ?? rawLinkTarget;
+    const resolvedLinkTarget =
+      type === "2" ? safeLinkTarget(memberPath, linkTarget) : null;
+    const entry: ArchiveEntry = {
+      memberPath,
+      type,
+      mode,
+      data,
+      linkTarget,
+      resolvedLinkTarget,
+    };
+    entries.push(entry);
+    byPath.set(memberPath, entry);
+    pendingPax = null;
+  }
+
+  if (!terminated || offset !== tar.length || pendingPax) {
+    throw new Error("runtime archive is truncated");
+  }
+  validateEntryGraph(entries, byPath);
+  const descriptorEntry = byPath.get("runtime.json");
+  if (!descriptorEntry || descriptorEntry.data.length > MAX_PAX_BYTES) {
+    throw new Error("runtime archive descriptor is missing or too large");
+  }
+  let rawDescriptor: unknown;
+  try {
+    rawDescriptor = JSON.parse(descriptorEntry.data.toString("utf8"));
+  } catch {
+    throw new Error("runtime archive descriptor is invalid JSON");
+  }
+  const descriptor = validateRuntimeDescriptor(rawDescriptor, expected);
+  const capabilities = validateEntryLayout(entries, byPath, descriptor);
+  return { entries, descriptor, capabilities };
+}
+
+function validateEntryGraph(
+  entries: readonly ArchiveEntry[],
+  byPath: ReadonlyMap<string, ArchiveEntry>,
+): void {
+  for (const entry of entries) {
+    const parts = entry.memberPath.split("/");
+    for (let length = 1; length < parts.length; length += 1) {
+      const ancestor = parts.slice(0, length).join("/");
+      const parent = byPath.get(ancestor);
+      if (!parent || parent.type !== "5") {
+        throw new Error(`runtime archive parent is not a directory: ${ancestor}`);
+      }
+    }
+    if (
+      entry.type === "2" &&
+      (!entry.resolvedLinkTarget || !byPath.has(entry.resolvedLinkTarget))
+    ) {
+      throw new Error(`runtime archive symlink target does not exist: ${entry.memberPath}`);
+    }
+  }
+}
+
+function validateEntryLayout(
+  entries: readonly ArchiveEntry[],
+  byPath: ReadonlyMap<string, ArchiveEntry>,
+  descriptor: RuntimeDescriptor,
+): { readonly capabilitySchemaVersion: 1 } | RuntimeCapabilityDescriptorV3 {
+  const topLevel = new Set(entries.map((entry) => entry.memberPath.split("/")[0]!));
+  if (
+    [...topLevel].sort().join("\0") !== [...BASE_TOP_LEVEL].sort().join("\0")
+  ) {
+    throw new Error("runtime archive top-level layout is invalid");
+  }
+  const requiredFiles = [
+    "agent/bin/uai-host.mjs",
+    "agent/scripts/agent/task-up.sh",
+    "agent/scripts/agent/task-down.sh",
+    "agent/scripts/agent/task-status.sh",
+    "bin/uai-host",
+    "node/bin/node",
+    "runtime.json",
+  ];
+  const requiredDirectories = ["agent", "bin", "node"];
+  const executables = [
+    "bin/uai-host",
+    "node/bin/node",
+    "agent/scripts/agent/task-up.sh",
+    "agent/scripts/agent/task-down.sh",
+    "agent/scripts/agent/task-status.sh",
+  ];
+  const capabilities = validateArchivedRuntimeCapability(byPath, descriptor);
+  if (capabilities.capabilitySchemaVersion === 3) {
+    const bundled = capabilities.bundledRuntime;
+    const pluginBinaries = APPLE_CONTAINER_PLUGINS.map(
+      (plugin) => `${bundled.layout.plugins}/${plugin}/bin/${plugin}`,
+    );
+    requiredFiles.push(
+      BUNDLED_RUNTIME_CAPABILITY,
+      bundled.layout.assetManifest,
+      bundled.layout.containerCli,
+      bundled.layout.apiserver,
+      ...pluginBinaries,
+      bundled.layout.kernel,
+      ...STANDARD_IMAGE_ASSETS.map(
+        ({ path: relative }) => `${bundled.layout.standardImage}/${relative}`,
+      ),
+      ...REQUIRED_RUNTIME_LICENSES.map(
+        (license) => `${bundled.layout.licenses}/${license}`,
+      ),
+    );
+    requiredDirectories.push(
+      BUNDLED_RUNTIME_ROOT,
+      `${BUNDLED_RUNTIME_ROOT}/apple-container`,
+      `${BUNDLED_RUNTIME_ROOT}/apple-container/bin`,
+      `${BUNDLED_RUNTIME_ROOT}/apple-container/libexec`,
+      `${BUNDLED_RUNTIME_ROOT}/apple-container/libexec/container`,
+      bundled.layout.plugins,
+      ...APPLE_CONTAINER_PLUGINS.flatMap((plugin) => [
+        `${bundled.layout.plugins}/${plugin}`,
+        `${bundled.layout.plugins}/${plugin}/bin`,
+      ]),
+      `${BUNDLED_RUNTIME_ROOT}/kernel`,
+      `${BUNDLED_RUNTIME_ROOT}/host-assets`,
+      bundled.layout.standardImage,
+      `${bundled.layout.standardImage}/container`,
+      bundled.layout.licenses,
+    );
+    validateArchivedRuntimeAssets(byPath, capabilities);
+    executables.push(
+      bundled.layout.containerCli,
+      bundled.layout.apiserver,
+      ...pluginBinaries,
+    );
+  }
+  for (const required of requiredFiles) {
+    if (byPath.get(required)?.type !== "0") {
+      throw new Error(`runtime archive is missing regular file ${required}`);
+    }
+  }
+  for (const required of requiredDirectories) {
+    if (byPath.get(required)?.type !== "5") {
+      throw new Error(`runtime archive is missing directory ${required}`);
+    }
+  }
+  for (const executable of executables) {
+    if (byPath.get(executable)?.mode !== 0o755) {
+      throw new Error(`runtime archive executable mode is invalid: ${executable}`);
+    }
+  }
+  return capabilities;
+}
+
+function validateArchivedRuntimeCapability(
+  byPath: ReadonlyMap<string, ArchiveEntry>,
+  descriptor: RuntimeDescriptor,
+): { readonly capabilitySchemaVersion: 1 } | RuntimeCapabilityDescriptorV3 {
+  const hasBundledSubtree = [...byPath.keys()].some(
+    (member) =>
+      member === BUNDLED_RUNTIME_ROOT ||
+      member.startsWith(`${BUNDLED_RUNTIME_ROOT}/`),
+  );
+  if (!descriptor.platform.startsWith("darwin-")) {
+    if (hasBundledSubtree) {
+      throw new Error("Linux runtime archive must not contain bundled Darwin assets");
+    }
+    return { capabilitySchemaVersion: 1 };
+  }
+  if (!hasBundledSubtree) return { capabilitySchemaVersion: 1 };
+  const entry = byPath.get(BUNDLED_RUNTIME_CAPABILITY);
+  if (entry?.type !== "0" || entry.data.length > MAX_PAX_BYTES) {
+    throw new Error("runtime capability descriptor is missing or too large");
+  }
+  let rawCapability: unknown;
+  try {
+    rawCapability = JSON.parse(entry.data.toString("utf8"));
+  } catch {
+    throw new Error("runtime capability descriptor is invalid JSON");
+  }
+  return validateRuntimeCapabilityDescriptor(rawCapability, descriptor.platform);
+}
+
+export function validateRuntimeDescriptor(
+  value: unknown,
+  expected: { version: string; platform: string },
+): RuntimeDescriptor {
+  const object = strictObject(
+    value,
+    ["schemaVersion", "hostVersion", "platform", "node", "requirements", "layout"],
+    "runtime descriptor",
+  );
+  if (object.schemaVersion !== 1) {
+    throw new Error("unsupported runtime descriptor schema");
+  }
+  if (object.hostVersion !== expected.version || !VERSION.test(expected.version)) {
+    throw new Error("runtime descriptor version does not match the authenticated release");
+  }
+  if (object.platform !== expected.platform) {
+    throw new Error("runtime descriptor platform does not match this host");
+  }
+  const node = strictObject(object.node, ["version", "modules"], "runtime descriptor node");
+  if (typeof node.version !== "string" || !VERSION.test(node.version)) {
+    throw new Error("runtime descriptor Node version is invalid");
+  }
+  if (typeof node.modules !== "string" || !/^\d+$/.test(node.modules)) {
+    throw new Error("runtime descriptor Node ABI is invalid");
+  }
+  const layout = strictObject(
+    object.layout,
+    ["agent", "launcher", "node"],
+    "runtime descriptor layout",
+  );
+  if (
+    layout.agent !== "agent" ||
+    layout.launcher !== "bin/uai-host" ||
+    layout.node !== "node"
+  ) {
+    throw new Error("runtime descriptor layout is invalid");
+  }
+  const requirements = strictStringObject(object.requirements, "runtime requirements");
+  validateRequirements(expected.platform, requirements);
+  return {
+    schemaVersion: 1,
+    hostVersion: expected.version,
+    platform: expected.platform,
+    node: { version: node.version, modules: node.modules },
+    requirements,
+    layout: { agent: "agent", launcher: "bin/uai-host", node: "node" } as const,
+  };
+}
+
+export function validateRuntimeCapabilityDescriptor(
+  value: unknown,
+  platform: string,
+): RuntimeCapabilityDescriptorV3 {
+  // ADR-106: the Apple container payload exists only on Apple Silicon.
+  if (platform !== "darwin-arm64") {
+    throw new Error("bundled runtime capability is supported only on darwin-arm64");
+  }
+  const object = strictObject(
+    value,
+    ["capabilitySchemaVersion", "bundledRuntime"],
+    "runtime capability descriptor",
+  );
+  if (object.capabilitySchemaVersion !== 3) {
+    throw new Error("unsupported runtime capability schema");
+  }
+  return {
+    capabilitySchemaVersion: 3,
+    bundledRuntime: validateBundledRuntimeDescriptor(object.bundledRuntime),
+  };
+}
+
+function validateBundledRuntimeDescriptor(
+  value: unknown,
+): BundledRuntimeDescriptor {
+  const object = strictObject(
+    value,
+    ["assetFingerprint", "versions", "requirements", "teamIdentifier", "layout"],
+    "bundled runtime descriptor",
+  );
+  if (typeof object.assetFingerprint !== "string" || !SHA256.test(object.assetFingerprint)) {
+    throw new Error("bundled runtime asset fingerprint is invalid");
+  }
+  const versions = strictObject(
+    object.versions,
+    ["container", "kata", "guestKernel"],
+    "bundled runtime versions",
+  );
+  for (const [name, version] of Object.entries(versions)) {
+    if (typeof version !== "string" || !VERSION.test(version)) {
+      throw new Error(`bundled runtime ${name} version is invalid`);
+    }
+  }
+  const requirements = strictObject(
+    object.requirements,
+    ["os", "arch", "minVersion"],
+    "bundled runtime requirements",
+  );
+  if (
+    requirements.os !== "darwin" ||
+    requirements.arch !== "arm64" ||
+    typeof requirements.minVersion !== "string" ||
+    !/^\d+\.\d+$/.test(requirements.minVersion)
+  ) {
+    throw new Error("bundled runtime requirements are invalid");
+  }
+  if (
+    typeof object.teamIdentifier !== "string" ||
+    !/^[A-Z0-9]{10}$/.test(object.teamIdentifier)
+  ) {
+    throw new Error("bundled runtime signing team identifier is invalid");
+  }
+  const layout = strictObject(
+    object.layout,
+    [
+      "assetSourceRoot",
+      "assetManifest",
+      "containerCli",
+      "apiserver",
+      "plugins",
+      "kernel",
+      "standardImage",
+      "licenses",
+    ],
+    "bundled runtime layout",
+  );
+  const expectedLayout = {
+    assetSourceRoot: BUNDLED_RUNTIME_ROOT,
+    assetManifest: `${BUNDLED_RUNTIME_ROOT}/assets.json`,
+    containerCli: `${BUNDLED_RUNTIME_ROOT}/apple-container/bin/container`,
+    apiserver: `${BUNDLED_RUNTIME_ROOT}/apple-container/bin/container-apiserver`,
+    plugins: `${BUNDLED_RUNTIME_ROOT}/apple-container/libexec/container/plugins`,
+    kernel: `${BUNDLED_RUNTIME_ROOT}/kernel/vmlinux`,
+    standardImage: `${BUNDLED_RUNTIME_ROOT}/host-assets/standard-image`,
+    licenses: `${BUNDLED_RUNTIME_ROOT}/licenses`,
+  } as const;
+  for (const [name, expectedValue] of Object.entries(expectedLayout)) {
+    if (layout[name] !== expectedValue) {
+      throw new Error(`bundled runtime layout ${name} is invalid`);
+    }
+  }
+  return {
+    assetFingerprint: object.assetFingerprint,
+    versions: {
+      container: versions.container as string,
+      kata: versions.kata as string,
+      guestKernel: versions.guestKernel as string,
+    },
+    requirements: {
+      os: "darwin",
+      arch: "arm64",
+      minVersion: requirements.minVersion,
+    },
+    teamIdentifier: object.teamIdentifier,
+    layout: expectedLayout,
+  };
+}
+
+function compareNames(left: string, right: string): number {
+  return Buffer.compare(Buffer.from(left), Buffer.from(right));
+}
+
+function runtimeAssetFingerprint(entries: readonly RuntimeAssetManifestEntry[]): string {
+  return createHash("sha256").update(JSON.stringify(entries)).digest("hex");
+}
+
+export function validateRuntimeAssetManifest(
+  value: unknown,
+  expectedFingerprint: string,
+): RuntimeAssetManifest {
+  const object = strictObject(
+    value,
+    ["schemaVersion", "fingerprint", "entries"],
+    "runtime asset manifest",
+  );
+  if (object.schemaVersion !== 1) {
+    throw new Error("unsupported runtime asset manifest schema");
+  }
+  if (
+    typeof object.fingerprint !== "string" ||
+    !SHA256.test(object.fingerprint) ||
+    object.fingerprint !== expectedFingerprint
+  ) {
+    throw new Error("runtime asset manifest fingerprint does not match runtime descriptor");
+  }
+  if (
+    !Array.isArray(object.entries) ||
+    object.entries.length === 0 ||
+    object.entries.length > MAX_RUNTIME_ASSET_ENTRIES
+  ) {
+    throw new Error("runtime asset manifest entry count is invalid");
+  }
+  const entries: RuntimeAssetManifestEntry[] = [];
+  let totalBytes = 0;
+  let previous: string | null = null;
+  let hasAppleContainer = false;
+  let hasKernel = false;
+  let hasHostAssets = false;
+  for (const rawEntry of object.entries) {
+    const entry = strictObject(
+      rawEntry,
+      ["path", "type", "mode", "size", "sha256"],
+      "runtime asset manifest entry",
+    );
+    const entryPath = entry.path;
+    if (
+      typeof entryPath !== "string" ||
+      entryPath.length === 0 ||
+      Buffer.byteLength(entryPath) > MAX_MEMBER_PATH_BYTES ||
+      entryPath.startsWith("/") ||
+      /[\x00-\x1f\x7f]/.test(entryPath) ||
+      entryPath.split("/").some((part) => !part || part === "." || part === "..") ||
+      path.posix.normalize(entryPath) !== entryPath ||
+      !RUNTIME_ASSET_ROOTS.some((root) => entryPath.startsWith(`${root}/`))
+    ) {
+      throw new Error(`runtime asset manifest path is invalid: ${String(entryPath)}`);
+    }
+    if (previous !== null && compareNames(previous, entryPath) >= 0) {
+      throw new Error("runtime asset manifest entries must be unique and bytewise sorted");
+    }
+    previous = entryPath;
+    if (entry.type !== "file") {
+      throw new Error(`runtime asset manifest entry is not a regular file: ${entryPath}`);
+    }
+    if (entry.mode !== 0o644 && entry.mode !== 0o755) {
+      throw new Error(`runtime asset manifest mode is invalid: ${entryPath}`);
+    }
+    if (!Number.isSafeInteger(entry.size) || (entry.size as number) < 0) {
+      throw new Error(`runtime asset manifest size is invalid: ${entryPath}`);
+    }
+    totalBytes += entry.size as number;
+    if (!Number.isSafeInteger(totalBytes) || totalBytes > MAX_RUNTIME_ASSET_BYTES) {
+      throw new Error(`runtime assets exceed ${MAX_RUNTIME_ASSET_BYTES} bytes`);
+    }
+    if (typeof entry.sha256 !== "string" || !SHA256.test(entry.sha256)) {
+      throw new Error(`runtime asset manifest sha256 is invalid: ${entryPath}`);
+    }
+    hasAppleContainer ||= entryPath.startsWith("apple-container/");
+    hasKernel ||= entryPath.startsWith("kernel/");
+    hasHostAssets ||= entryPath.startsWith("host-assets/");
+    entries.push({
+      path: entryPath,
+      type: "file",
+      mode: entry.mode,
+      size: entry.size as number,
+      sha256: entry.sha256,
+    });
+  }
+  if (!hasAppleContainer || !hasKernel || !hasHostAssets) {
+    throw new Error(
+      "runtime asset manifest must include Apple container, guest kernel, and host files",
+    );
+  }
+  const entryPaths = new Set(entries.map((entry) => entry.path));
+  for (const required of [
+    "apple-container/bin/container",
+    "apple-container/bin/container-apiserver",
+    ...APPLE_CONTAINER_PLUGINS.map(
+      (plugin) =>
+        `apple-container/libexec/container/plugins/${plugin}/bin/${plugin}`,
+    ),
+    "kernel/vmlinux",
+    ...STANDARD_IMAGE_ASSETS.map(
+      ({ path: relative }) => `host-assets/standard-image/${relative}`,
+    ),
+  ]) {
+    if (!entryPaths.has(required)) {
+      throw new Error(`runtime asset manifest is missing ${required}`);
+    }
+  }
+  for (const { path: relative, mode } of STANDARD_IMAGE_ASSETS) {
+    const assetPath = `host-assets/standard-image/${relative}`;
+    if (entries.find((entry) => entry.path === assetPath)?.mode !== mode) {
+      throw new Error(`runtime asset manifest mode is invalid: ${assetPath}`);
+    }
+  }
+  if (runtimeAssetFingerprint(entries) !== object.fingerprint) {
+    throw new Error("runtime asset manifest fingerprint is invalid for its entries");
+  }
+  return { schemaVersion: 1, fingerprint: object.fingerprint, entries };
+}
+
+function validateArchivedRuntimeAssets(
+  byPath: ReadonlyMap<string, ArchiveEntry>,
+  capabilities: RuntimeCapabilityDescriptorV3,
+): void {
+  const manifestEntry = byPath.get(capabilities.bundledRuntime.layout.assetManifest);
+  if (
+    manifestEntry?.type !== "0" ||
+    manifestEntry.data.length > MAX_RUNTIME_ASSET_MANIFEST_BYTES
+  ) {
+    throw new Error("runtime asset manifest is missing or too large");
+  }
+  let rawManifest: unknown;
+  try {
+    rawManifest = JSON.parse(manifestEntry.data.toString("utf8"));
+  } catch {
+    throw new Error("runtime asset manifest is invalid JSON");
+  }
+  const manifest = validateRuntimeAssetManifest(
+    rawManifest,
+    capabilities.bundledRuntime.assetFingerprint,
+  );
+  const actual: RuntimeAssetManifestEntry[] = [];
+  for (const [memberPath, entry] of byPath) {
+    if (
+      !RUNTIME_ASSET_ROOTS.some(
+        (root) =>
+          memberPath === `${BUNDLED_RUNTIME_ROOT}/${root}` ||
+          memberPath.startsWith(`${BUNDLED_RUNTIME_ROOT}/${root}/`),
+      )
+    ) {
+      continue;
+    }
+    if (entry.type === "5") continue;
+    if (entry.type !== "0") {
+      throw new Error(`runtime asset is not a regular file: ${memberPath}`);
+    }
+    actual.push({
+      path: memberPath.slice(`${BUNDLED_RUNTIME_ROOT}/`.length),
+      type: "file",
+      mode: entry.mode as 0o644 | 0o755,
+      size: entry.data.length,
+      sha256: createHash("sha256").update(entry.data).digest("hex"),
+    });
+  }
+  actual.sort((left, right) => compareNames(left.path, right.path));
+  if (JSON.stringify(actual) !== JSON.stringify(manifest.entries)) {
+    throw new Error("runtime asset manifest does not close the archived asset tree");
+  }
+  validateArchivedBundledSubtreeClosure(byPath, capabilities, manifest);
+}
+
+function expectedBundledRuntimeFiles(
+  capabilities: RuntimeCapabilityDescriptorV3,
+  manifest: RuntimeAssetManifest,
+): ReadonlySet<string> {
+  const bundled = capabilities.bundledRuntime;
+  // Every staged payload file is a manifest entry; only the two metadata
+  // documents live outside the digest closure.
+  return new Set([
+    BUNDLED_RUNTIME_CAPABILITY,
+    bundled.layout.assetManifest,
+    ...manifest.entries.map(
+      (entry) => `${bundled.layout.assetSourceRoot}/${entry.path}`,
+    ),
+  ]);
+}
+
+function validateArchivedBundledSubtreeClosure(
+  byPath: ReadonlyMap<string, ArchiveEntry>,
+  capabilities: RuntimeCapabilityDescriptorV3,
+  manifest: RuntimeAssetManifest,
+): void {
+  const expected = expectedBundledRuntimeFiles(capabilities, manifest);
+  const actual = new Set<string>();
+  for (const [memberPath, entry] of byPath) {
+    if (!memberPath.startsWith(`${BUNDLED_RUNTIME_ROOT}/`)) continue;
+    if (entry.type === "5") {
+      if (![...expected].some((file) => file.startsWith(`${memberPath}/`))) {
+        throw new Error(
+          `runtime bundled subtree has an unexpected directory: ${memberPath}`,
+        );
+      }
+      continue;
+    }
+    if (entry.type !== "0") {
+      throw new Error(`runtime bundled subtree has an unsafe entry: ${memberPath}`);
+    }
+    actual.add(memberPath);
+  }
+  if (
+    [...actual].sort(compareNames).join("\0") !==
+    [...expected].sort(compareNames).join("\0")
+  ) {
+    throw new Error("runtime bundled subtree is not closed by its descriptor and manifest");
+  }
+}
+
+function validateRequirements(platform: string, value: Readonly<Record<string, string>>): void {
+  const [os, arch] = platform.split("-");
+  if (value.os !== os || value.arch !== arch) {
+    throw new Error("runtime descriptor requirements do not match its platform");
+  }
+  const keys = Object.keys(value).sort().join("\0");
+  if (os === "darwin") {
+    if (keys !== ["arch", "minVersion", "os"].join("\0") || value.minVersion !== "13.5") {
+      throw new Error("runtime descriptor macOS requirements are invalid");
+    }
+  } else if (
+    os !== "linux" ||
+    keys !== ["arch", "libc", "minKernel", "minLibcVersion", "os"].join("\0") ||
+    value.libc !== "glibc" ||
+    value.minKernel !== "4.18" ||
+    value.minLibcVersion !== "2.29"
+  ) {
+    throw new Error("runtime descriptor Linux requirements are invalid");
+  }
+}
+
+function strictObject(
+  value: unknown,
+  expectedKeys: readonly string[],
+  label: string,
+): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} must be an object`);
+  }
+  const object = value as Record<string, unknown>;
+  if (Object.getPrototypeOf(object) !== Object.prototype) {
+    throw new Error(`${label} must be a plain object`);
+  }
+  if (Object.keys(object).sort().join("\0") !== [...expectedKeys].sort().join("\0")) {
+    throw new Error(`${label} fields are invalid`);
+  }
+  return object;
+}
+
+function strictStringObject(value: unknown, label: string): Readonly<Record<string, string>> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} must be an object`);
+  }
+  const output: Record<string, string> = {};
+  for (const [key, item] of Object.entries(value)) {
+    if (typeof item !== "string") throw new Error(`${label}.${key} must be a string`);
+    output[key] = item;
+  }
+  return output;
+}
+
+function assertCanonicalGzipHeader(bytes: Buffer): void {
+  if (
+    bytes.length < 18 ||
+    bytes[0] !== 0x1f ||
+    bytes[1] !== 0x8b ||
+    bytes[2] !== 8 ||
+    bytes[3] !== 0 ||
+    bytes.readUInt32LE(4) !== 0 ||
+    bytes[8] !== 2 ||
+    bytes[9] !== 255
+  ) {
+    throw new Error("runtime archive gzip header is not canonical");
+  }
+}
+
+function validateHeaderChecksum(header: Buffer): void {
+  const expected = parseOctal(header, 148, 8, "checksum");
+  const copy = Buffer.from(header);
+  copy.fill(0x20, 148, 156);
+  const actual = copy.reduce((sum, byte) => sum + byte, 0);
+  if (actual !== expected) throw new Error("runtime archive header checksum mismatch");
+}
+
+function parseString(block: Buffer, offset: number, length: number): string {
+  const end = block.indexOf(0, offset);
+  const stop = end === -1 || end > offset + length ? offset + length : end;
+  const bytes = block.subarray(offset, stop);
+  const decoded = bytes.toString("utf8");
+  if (!Buffer.from(decoded, "utf8").equals(bytes)) {
+    throw new Error("runtime archive header contains invalid UTF-8");
+  }
+  return decoded;
+}
+
+function parseOctal(block: Buffer, offset: number, length: number, label: string): number {
+  const raw = parseString(block, offset, length).trim();
+  if (!/^[0-7]+$/.test(raw)) throw new Error(`runtime archive has invalid ${label}`);
+  const value = Number.parseInt(raw, 8);
+  if (!Number.isSafeInteger(value)) throw new Error(`runtime archive has invalid ${label}`);
+  return value;
+}
+
+function parsePax(body: Buffer): { path?: string; linkpath?: string } {
+  const values: { path?: string; linkpath?: string } = {};
+  let offset = 0;
+  while (offset < body.length) {
+    const space = body.indexOf(0x20, offset);
+    if (space === -1) throw new Error("runtime archive pax record has no length");
+    const rawLength = body.subarray(offset, space).toString("ascii");
+    if (!/^[1-9]\d*$/.test(rawLength)) throw new Error("runtime archive pax length is invalid");
+    const length = Number.parseInt(rawLength, 10);
+    if (!Number.isSafeInteger(length) || offset + length > body.length) {
+      throw new Error("runtime archive pax boundary is invalid");
+    }
+    const record = body.subarray(space + 1, offset + length);
+    if (record.at(-1) !== 0x0a) throw new Error("runtime archive pax terminator is invalid");
+    const text = record.subarray(0, -1).toString("utf8");
+    const equals = text.indexOf("=");
+    if (equals <= 0) throw new Error("runtime archive pax record is invalid");
+    const key = text.slice(0, equals);
+    const value = text.slice(equals + 1);
+    if ((key !== "path" && key !== "linkpath") || Object.hasOwn(values, key)) {
+      throw new Error(`unsupported or duplicate runtime archive pax key: ${key}`);
+    }
+    values[key] = value;
+    offset += length;
+  }
+  return values;
+}
+
+function safeMemberPath(value: string): string {
+  const normalizedValue = value.endsWith("/") ? value.slice(0, -1) : value;
+  if (
+    !normalizedValue ||
+    Buffer.byteLength(normalizedValue) > MAX_MEMBER_PATH_BYTES ||
+    normalizedValue.startsWith("/") ||
+    /[\x00-\x1f\x7f]/.test(normalizedValue) ||
+    normalizedValue
+      .split("/")
+      .some((part) => !part || part === "." || part === "..") ||
+    path.posix.normalize(normalizedValue) !== normalizedValue
+  ) {
+    throw new Error(`unsafe runtime archive member path: ${JSON.stringify(value)}`);
+  }
+  return normalizedValue;
+}
+
+function safeLinkTarget(memberPath: string, target: string): string {
+  if (
+    !target ||
+    Buffer.byteLength(target) > MAX_MEMBER_PATH_BYTES ||
+    target.startsWith("/") ||
+    /[\x00-\x1f\x7f]/.test(target)
+  ) {
+    throw new Error(`unsafe runtime archive symlink target: ${JSON.stringify(target)}`);
+  }
+  const resolved = path.posix.normalize(path.posix.join(path.posix.dirname(memberPath), target));
+  if (resolved === ".." || resolved.startsWith("../") || resolved.startsWith("/")) {
+    throw new Error(`runtime archive symlink escapes the payload: ${memberPath}`);
+  }
+  return resolved;
+}
+
+async function syncDirectory(directory: string): Promise<void> {
+  let handle;
+  try {
+    handle = await open(directory, fsConstants.O_RDONLY);
+    await handle.sync();
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code !== "EINVAL" && code !== "ENOTSUP" && code !== "EISDIR") {
+      throw error;
+    }
+  } finally {
+    await handle?.close();
+  }
+}