rea/src/artifacts/apple/KeyedArchiveReader.ts

import { createHash } from "node:crypto";
import { join } from "node:path";
import { parseBinary } from "plist";
import { z } from "zod";
import {
  AnalysisInputError,
  AnalysisUnsupportedTargetError,
} from "../../domain/analysisErrorCore.js";
import type { JsonValue } from "../../domain/jsonValue.js";
import { projectPlistValue } from "../../domain/apple/plistValue.js";
import { createPlistNumberProjection } from "../../domain/apple/plistNumbers.js";
import {
  binaryPlistNumberLiterals,
  xmlPlistNumberLiterals,
} from "./PlistNumberLiterals.js";
import {
  omittedPrototypeKeysLimitation,
  parseXmlPropertyList,
} from "../../domain/propertyListKeys.js";
import {
  KeyedArchiveKindError,
  keyedArchiveInputSchema,
  keyedArchiveResultSchema,
  projectKeyedArchive,
} from "../../domain/apple/keyedArchive.js";
import { DirectoryArtifactReader } from "../DirectoryArtifactReader.js";
import { ArtifactReaderFailure } from "../ArtifactReader.js";

import { decodeXmlPlistText } from "../../domain/propertyListXmlText.js";

const MAX_BYTES = 64 * 1024 * 1024;

/** Parse inert plist bytes, preserving data and dates with explicit typed values. */
export const decodeKeyedArchiveBytes = (
  bytes: Buffer,
  selection: { root?: string | undefined; offset: number; limit: number },
) => {
  if (bytes.length > MAX_BYTES)
    throw new RangeError("Keyed archive exceeds 64 MiB");
  if (bytes.subarray(0, 10).toString("ascii") === "NIBArchive")
    throw new KeyedArchiveKindError(
      "Selected file is a compiled NIBArchive, not a Foundation plist archive; decode it with decode_interface_builder",
      "nib-archive",
    );
  const binary = bytes.subarray(0, 8).toString("ascii") === "bplist00";
  const xmlText = binary ? undefined : decodeXmlPlistText(bytes);
  const parsed = binary
    ? { value: parseBinary(bytes), omittedPrototypeKeys: 0 }
    : parseXmlPropertyList(xmlText ?? "");
  const graph = projectKeyedArchive(normalizePlist(parsed.value), selection);
  const numbers = createPlistNumberProjection(
    binary
      ? binaryPlistNumberLiterals(bytes)
      : xmlPlistNumberLiterals(xmlText ?? ""),
  );
  // Classify the serialized graph before projecting values to typed decimals.
  // Numeric IDs, node kinds, references and pagination retain their original meaning.
  const roots = Object.fromEntries(
    Object.entries(graph.roots).map(([name, value]) => [
      name,
      numbers.project(value),
    ]),
  );
  const objects = graph.objects.map((object) => ({
    ...object,
    value: numbers.project(object.value),
  }));
  return {
    archive_format: binary ? ("binary-plist" as const) : ("xml-plist" as const),
    ...graph,
    roots,
    objects,
    limitations: [
      ...graph.limitations,
      ...numbers.limitations(),
      ...(parsed.omittedPrototypeKeys === 0
        ? []
        : [omittedPrototypeKeysLimitation(parsed.omittedPrototypeKeys)]),
    ],
  };
};

const normalizePlist = (value: unknown): JsonValue => {
  const projected = projectPlistValue(value);
  if (projected.unknownRealCount > 0)
    throw new RangeError("Keyed archive contains a non-finite real");
  return projected.value;
};

/**
 * Point to the workflow that reads the selected kind of file on this host.
 * decode_interface_builder is portable; inspect_plist requires macOS.
 */
const keyedArchiveKindRemediation = (
  kind: KeyedArchiveKindError["kind"],
  platform: NodeJS.Platform,
): string => {
  if (kind === "nib-archive")
    return "Decode compiled NIBArchive files with decode_interface_builder on the app bundle.";
  return platform === "darwin"
    ? "Inspect an ordinary property list with inspect_plist; inspect_keyed_archive decodes NSKeyedArchiver archives only."
    : "Select an NSKeyedArchiver archive; inspect_keyed_archive decodes only those. inspect_plist, which reads ordinary property lists, requires a macOS host.";
};

/** Read exactly one regular, contained bundle entry without following symlinks. */
export const inspectBundleKeyedArchive = async (input: {
  bundlePath: string;
  targetSha256: string;
  parameters: unknown;
  signal?: AbortSignal;
  /** Host whose available workflows the remediation names. */
  platform?: NodeJS.Platform;
}) => {
  const selected = keyedArchiveInputSchema.parse(input.parameters);
  if (
    selected.path.startsWith("/") ||
    selected.path
      .split("/")
      .some((part) => part === ".." || part === "." || part.length === 0)
  )
    throw archivePathError(
      "invalid_format",
      selected.path === "."
        ? "Select a keyed archive path relative to the active app bundle."
        : `Archive path must be a canonical relative bundle path without empty, '.', or '..' segments: ${selected.path}`,
    );
  const reader = new DirectoryArtifactReader(input.bundlePath);
  try {
    for await (const entry of reader.entries(input.signal)) {
      if (entry.path !== selected.path) continue;
      if (entry.kind !== "file")
        throw archivePathError(
          "invalid_value",
          `Archive path selects a ${entry.kind}, not a regular file: ${selected.path}`,
        );
      if ((entry.declaredSize ?? 0) > MAX_BYTES)
        throw new ArtifactReaderFailure(
          "limit",
          "Keyed archive exceeds 64 MiB",
        );
      const stream = await reader.open(entry, input.signal);
      const chunks: Buffer[] = [];
      let size = 0;
      for await (const chunk of stream) {
        if (input.signal?.aborted) {
          stream.destroy();
          throw new ArtifactReaderFailure(
            "cancelled",
            "Archive inspection cancelled",
          );
        }
        const bytes = z.instanceof(Buffer).parse(chunk);
        size += bytes.length;
        if (size > MAX_BYTES) {
          stream.destroy();
          throw new ArtifactReaderFailure(
            "limit",
            "Keyed archive exceeds 64 MiB",
          );
        }
        chunks.push(bytes);
      }
      const bytes = Buffer.concat(chunks, size);
      try {
        return keyedArchiveResultSchema.parse({
          target_sha256: input.targetSha256,
          archive_path: entry.path,
          archive_sha256: createHash("sha256").update(bytes).digest("hex"),
          ...decodeKeyedArchiveBytes(bytes, selected),
        });
      } catch (cause) {
        if (cause instanceof AnalysisInputError) throw cause;
        // An intact file of another kind is not a damaged archive.
        if (cause instanceof KeyedArchiveKindError)
          throw new AnalysisUnsupportedTargetError(
            "inspect_keyed_archive",
            join(input.bundlePath, entry.path),
            cause.message,
            {
              cause,
              remediationAction: keyedArchiveKindRemediation(
                cause.kind,
                input.platform ?? process.platform,
              ),
            },
          );
        throw new ArtifactReaderFailure(
          cause instanceof RangeError ? "limit" : "format",
          `Cannot decode selected Foundation keyed archive: ${cause instanceof Error ? cause.message : String(cause)}`,
          { cause },
        );
      }
    }
    throw archivePathError(
      "invalid_value",
      `No regular file exists at ${selected.path} in the active app bundle.`,
    );
  } finally {
    await reader.close();
  }
};

/** A caller-selected archive path, not the artifact, failed its constraint. */
const archivePathError = (
  reason: "invalid_format" | "invalid_value",
  message: string,
) =>
  new AnalysisInputError("inspect_keyed_archive", undefined, [
    { path: ["path"], reason, message },
  ]);