Skip to content

armgit / rea

Public Imported from GitHub
0

Reverse engineer anything with agents, from app behavior down to native binaries.

13.1 KB
Raw Blame
import { z } from "zod";
import { parseBinary } from "plist";

import {
  AnalysisOutputError,
  AnalysisResourceConstraintError,
} from "../../domain/analysisErrorCore.js";
import { fixedAllowanceOptions } from "../../domain/fixedAllowanceRemediation.js";
import type { JsonValue } from "../../domain/jsonValue.js";
import {
  binaryDatePrecisionOverlapLimitation,
  negativeZeroReal,
  negativeZeroRealLimitation,
  nonFiniteRealLimitation,
  projectPlistValue,
  unknownDateLimitation,
  unknownScalarLimitation,
  type ProjectedPlistValue,
} from "../../domain/apple/plistValue.js";
import {
  omitPrototypeKeys,
  omittedPrototypeKeysLimitation,
  parseXmlPropertyList,
} from "../../domain/propertyListKeys.js";
import { err, ok, type Result } from "../../domain/result.js";

import {
  incompletePlistNumberLimitation,
  createPlistNumberProjection,
  type PlistNumberLiterals,
} from "../../domain/apple/plistNumbers.js";
import {
  decodeBinaryPlistScalars,
  scanBinaryPlistScalars,
} from "../../artifacts/apple/PlistScalars.js";
import {
  estimateBinaryPlistExpansion,
  MAX_BINARY_PLIST_NESTING_DEPTH,
  PropertyListDecodeBudgetFailure,
} from "../../artifacts/apple/PropertyListDecodeBudget.js";
import { hasBinaryPlistSignature } from "../../domain/apple/appleArchiveFormat.js";

/**
 * Input ceiling matches native command output; projection is bounded separately.
 * Provisional byte allowance. This release has no runtime override.
 */
export const MAX_NATIVE_PLIST_BYTES = 64 * 1024 * 1024;
/** Provisional decode allowance. This release has no runtime override. */
const MAX_NATIVE_PLIST_DECODE_BYTES = 64 * 1024 * 1024;

const mebibytes = (bytes: number): string =>
  `${String(bytes / (1024 * 1024))} MiB`;

/** Recovery name for the fixed source-size ceiling. */
export const NATIVE_PLIST_INPUT_ALLOWANCE = `the fixed ${mebibytes(MAX_NATIVE_PLIST_BYTES)} (${String(MAX_NATIVE_PLIST_BYTES)}-byte) native plist input allowance (no runtime override)`;

const plistObject = z.record(z.string(), z.unknown());

/** Stable bundle metadata projected from one plist value. */
export interface PlistBundleMetadata {
  readonly identifier: string | null;
  readonly executable: string | null;
  readonly name: string | null;
  readonly version: string | null;
  readonly short_version: string | null;
}

/** One decoded plist with bundle metadata and decoding limitations. */
export interface ParsedPlist {
  readonly value: unknown;
  readonly bundle: PlistBundleMetadata;
  readonly limitations: readonly string[];
}

/** Digits of a JSON number literal that has no fraction or exponent. */
const INTEGRAL_LITERAL = /^-?\d+$/u;

/**
 * Decode plutil JSON, passing each integral number literal beyond the exact
 * range of a JavaScript number, with its source digits, to `unsafe`, and
 * each negative zero to `negativeZero`.
 */
const decodePlistJson = (
  output: string,
  unsafe: (item: number, digits: string) => unknown,
  negativeZero: (item: number) => unknown = (item) => item,
): unknown => {
  // plutil output can carry a UTF-8 BOM, which JSON.parse rejects outright.
  const text = output.replace(/^\uFEFF/u, "");
  return JSON.parse(
    text,
    (_key: string, item: unknown, context?: { readonly source?: string }) => {
      // A plist integer has no signed zero, so -0 can only come from a real.
      if (typeof item === "number" && Object.is(item, -0))
        return negativeZero(item);
      const source = context?.source;
      return typeof item !== "number" ||
        Number.isSafeInteger(item) ||
        source === undefined ||
        !INTEGRAL_LITERAL.test(source)
        ? item
        : unsafe(item, source);
    },
  );
};

/**
 * Whether plutil JSON holds an integral number beyond the exact range of a
 * JSON number. JSON prints an integral `<real>` and an `<integer>` alike, so
 * such a number's element type must be read from plutil's XML conversion.
 */
export const plistJsonNeedsNumberTypes = (output: string): boolean => {
  let found = false;
  try {
    decodePlistJson(output, (item) => {
      found = true;
      return item;
    });
  } catch {
    // Malformed JSON is reported by `parsePlistJson`.
  }
  return found;
};

/**
 * Parse plutil JSON output and project stable bundle metadata. An integer
 * beyond the exact range of a JSON number keeps its decimal text when
 * `xmlConversion`, plutil's XML form of the same plist, shows that it came
 * from an `<integer>` rather than a `<real>`.
 */
export const parsePlistJson = (
  output: string,
  xmlConversion?: string,
): Result<ParsedPlist, AnalysisOutputError> => {
  let literals: PlistNumberLiterals | undefined;
  let exactIntegerCount = 0;
  let ambiguousNumberCount = 0;
  let negativeZeroRealCount = 0;
  const signedZero = (): unknown => {
    negativeZeroRealCount += 1;
    return negativeZeroReal();
  };
  const classify = (item: number, digits: string): unknown => {
    const exact = BigInt(digits).toString();
    const integer =
      literals?.incomplete === false &&
      literals.integers.get(item)?.has(exact) === true;
    const real = literals?.incomplete === false && literals.reals.has(item);
    if (integer && !real) {
      exactIntegerCount += 1;
      return { $plist_type: "integer", decimal: digits };
    }
    // An integral <real> decodes exactly; only its JSON spelling is integral.
    if (real && !integer) return item;
    ambiguousNumberCount += 1;
    return item;
  };
  let decoded: ReturnType<typeof omitPrototypeKeys>;
  try {
    literals =
      xmlConversion === undefined
        ? undefined
        : parseXmlPropertyList(xmlConversion).numberLiterals;
    decoded = omitPrototypeKeys(decodePlistJson(output, classify, signedZero));
  } catch (cause: unknown) {
    return err(
      new AnalysisOutputError(
        "inspect_plist",
        cause instanceof Error ? cause.message : String(cause),
        { cause },
      ),
    );
  }
  const { value } = decoded;
  return ok({
    value,
    bundle: projectPlistBundle(value),
    limitations: [
      ...negativeZeroLimitations(negativeZeroRealCount),
      ...(literals?.incomplete === true
        ? [incompletePlistNumberLimitation]
        : []),
      ...numberLimitations(exactIntegerCount, ambiguousNumberCount),
      ...prototypeKeyLimitations(decoded.omittedPrototypeKeys),
    ],
  });
};

/**
 * Parse plutil XML output for a plist that JSON cannot express, such as one
 * containing data, dates, or non-finite reals.
 */
export const parsePlistXml = (
  output: string,
): Result<ParsedPlist, AnalysisOutputError> => {
  let projected: ProjectedPlistValue;
  let omittedPrototypeKeys: number;
  let literals: PlistNumberLiterals;
  try {
    const decoded = parseXmlPropertyList(output);
    omittedPrototypeKeys = decoded.omittedPrototypeKeys;
    literals = decoded.numberLiterals;
    projected = projectPlistValue(decoded.value);
  } catch (cause: unknown) {
    return err(
      new AnalysisOutputError(
        "inspect_plist",
        "plutil XML conversion was not a readable plist",
        { cause },
      ),
    );
  }
  // The XML decoder turns <integer> and <real> into numbers before REA sees
  // them, rounding integers beyond the exact range.
  let exactIntegerCount = 0;
  let ambiguousNumberCount = 0;
  const value = mapJsonNumbers(projected.value, (item) => {
    const decimals = literals.integers.get(item);
    if (decimals === undefined) return item;
    const [decimal] = decimals;
    if (
      literals.incomplete ||
      decimals.size !== 1 ||
      decimal === undefined ||
      literals.reals.has(item)
    ) {
      ambiguousNumberCount += 1;
      return item;
    }
    exactIntegerCount += 1;
    return { $plist_type: "integer", decimal };
  });
  return ok({
    value,
    bundle: projectPlistBundle(value),
    limitations: [
      'plutil cannot express this plist as JSON, so it was decoded from plutil\'s XML conversion; data and date values are typed objects such as { "$plist_type": "data", "base64": ... }.',
      ...projectedScalarLimitations(projected),
      ...(literals.incomplete ? [incompletePlistNumberLimitation] : []),
      ...numberLimitations(exactIntegerCount, ambiguousNumberCount),
      ...prototypeKeyLimitations(omittedPrototypeKeys),
    ],
  });
};

/** Decode binary plist source bytes before conversion can erase scalar facts. */
export const parsePlistBinary = (
  bytes: Buffer,
): Result<
  ParsedPlist,
  AnalysisOutputError | AnalysisResourceConstraintError
> => {
  try {
    if (!hasBinaryPlistSignature(bytes))
      throw new TypeError("selected file does not have a binary plist header");
    const expansion = estimateBinaryPlistExpansion(
      bytes,
      MAX_NATIVE_PLIST_DECODE_BYTES,
      {
        budget: "the native plist decode budget",
        numberProjection: true,
        fail: (kind, message) =>
          kind === "cycle"
            ? new TypeError(
                "binary plist object references form a cycle, which a property list cannot represent",
              )
            : new PropertyListDecodeBudgetFailure(kind, message),
      },
    );
    const scalarMetadata = scanBinaryPlistScalars(bytes, expansion);
    const decoded = parseBinary(
      decodeBinaryPlistScalars(bytes, scalarMetadata, expansion),
    );
    const projected = projectPlistValue(decoded);
    const numbers = createPlistNumberProjection(scalarMetadata.literals);
    const value = numbers.project(projected.value);
    return ok({
      value,
      bundle: projectPlistBundle(value),
      limitations: [
        ...projectedScalarLimitations(projected),
        ...(expansion.datePrecisionOverlapCount === 0
          ? []
          : [
              binaryDatePrecisionOverlapLimitation(
                expansion.datePrecisionOverlapCount,
              ),
            ]),
        ...numbers.limitations(),
        ...(expansion.binaryPrototypeKeyObserved
          ? [omittedPrototypeKeysLimitation(null)]
          : []),
      ],
    });
  } catch (cause: unknown) {
    if (cause instanceof PropertyListDecodeBudgetFailure)
      return err(
        new AnalysisResourceConstraintError(
          "inspect_plist",
          "memory",
          cause.message,
          cause.kind === "depth"
            ? { maximum_nesting_depth: MAX_BINARY_PLIST_NESTING_DEPTH }
            : { maximum_decoded_bytes: MAX_NATIVE_PLIST_DECODE_BYTES },
          {
            cause,
            ...fixedAllowanceOptions(
              cause.kind === "depth"
                ? `The ${String(MAX_BINARY_PLIST_NESTING_DEPTH)}-level native binary plist nesting allowance (no runtime override)`
                : `The ${mebibytes(MAX_NATIVE_PLIST_DECODE_BYTES)} (${String(MAX_NATIVE_PLIST_DECODE_BYTES)}-byte) native binary plist decode allowance (no runtime override)`,
              "parser",
            ),
          },
        ),
      );
    return err(
      new AnalysisOutputError(
        "inspect_plist",
        cause instanceof Error ? cause.message : String(cause),
        { cause },
      ),
    );
  }
};

const prototypeKeyLimitations = (count: number): string[] =>
  count === 0 ? [] : [omittedPrototypeKeysLimitation(count)];

const projectedScalarLimitations = (
  projected: ProjectedPlistValue,
): string[] => [
  ...(projected.nonFiniteRealCount === 0
    ? []
    : [nonFiniteRealLimitation(projected.nonFiniteRealCount)]),
  ...negativeZeroLimitations(projected.negativeZeroRealCount),
  ...(projected.unknownDateCount === 0
    ? []
    : [unknownDateLimitation(projected.unknownDateCount)]),
  ...(projected.unknownScalarCount === 0
    ? []
    : [unknownScalarLimitation(projected.unknownScalarCount)]),
];

const negativeZeroLimitations = (count: number): string[] =>
  count === 0 ? [] : [negativeZeroRealLimitation(count)];

const numberLimitations = (
  exactIntegerCount: number,
  ambiguousNumberCount: number,
): string[] => [
  ...(exactIntegerCount === 0
    ? []
    : [
        `${String(exactIntegerCount)} integer value(s) exceed the exact range of a JSON number and are reported as { "$plist_type": "integer", "decimal": "<exact digits>" }.`,
      ]),
  ...(ambiguousNumberCount === 0
    ? []
    : [
        `${String(ambiguousNumberCount)} number(s) beyond the exact range of a JSON number are reported as decoded because the XML literal they came from, a rounded <integer> or a <real>, cannot be identified.`,
      ]),
];

const mapJsonNumbers = (
  value: JsonValue,
  map: (item: number) => JsonValue,
): JsonValue => {
  if (typeof value === "number") return map(value);
  if (Array.isArray(value))
    return value.map((item) => mapJsonNumbers(item, map));
  if (value !== null && typeof value === "object")
    return Object.fromEntries(
      Object.entries(value).map(([key, item]) => [
        key,
        mapJsonNumbers(item, map),
      ]),
    );
  return value;
};

const projectPlistBundle = (value: unknown): PlistBundleMetadata => {
  const object = plistObject.safeParse(value);
  const field = (name: string): string | null => {
    if (!object.success) return null;
    const candidate = object.data[name];
    return typeof candidate === "string" ? candidate : null;
  };
  return {
    identifier: field("CFBundleIdentifier"),
    executable: field("CFBundleExecutable"),
    name: field("CFBundleName"),
    version: field("CFBundleVersion"),
    short_version: field("CFBundleShortVersionString"),
  };
};