Skip to content

armgit / rea

Public Imported from GitHub
0

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

11.8 KB
Raw Blame
import type { FileHandle } from "node:fs/promises";
import { readPyInstallerBytes } from "./PyInstallerBytes.js";

import { err, ok, type Result } from "../../domain/result.js";
import {
  pyInstallerFailure,
  type PyInstallerFailure,
} from "./PyInstallerFailure.js";

/** Magic at the start of a CArchive cookie. */
export const PYINSTALLER_COOKIE_MAGIC = Buffer.from("MEI\x0c\x0b\x0a\x0b\x0e");

/** PyInstaller 2.1+ cookie size, including the 64-byte library name. */
export const PYINSTALLER_COOKIE_V21_BYTES = 88;

/** PyInstaller 2.0 cookie size, without the library name. */
export const PYINSTALLER_COOKIE_V20_BYTES = 24;

/**
 * How far before EOF the cookie may sit. macOS code signatures are appended
 * after the cookie, and a large binary's signature hashes are larger than the
 * bootloader's own 8 KiB scan chunk, so detection uses one bounded tail.
 */
export const PYINSTALLER_COOKIE_SEARCH_BYTES = 16 * 1024 * 1024;

const MAX_TOC_BYTES = 32 * 1024 * 1024;
const MAX_TOC_ENTRIES = 100_000;
const TOC_HEADER_BYTES = 18;

/** Observed CArchive cookie. Offsets are relative to the archive start. */
export interface PyInstallerCookie {
  readonly layout: "2.0" | "2.1";
  readonly archiveStart: number;
  readonly packageLength: number;
  readonly tocOffset: number;
  readonly tocLength: number;
  readonly pythonVersion: number;
  readonly pythonLibrary: string | null;
  readonly cookieOffset: number;
}

/** One CArchive table entry. */
export interface CArchiveEntry {
  readonly index: number;
  readonly tocRecordOffset: number;
  readonly tocRecordLength: number;
  readonly name: string;
  readonly typeCode: string;
  readonly offset: number;
  readonly compressedSize: number;
  readonly uncompressedSize: number;
  readonly compressionFlag: number;
}

/** Runtime options and external dependencies are declarations, never local blobs. */
export const isCArchiveDeclaration = (
  entry: CArchiveEntry,
): entry is CArchiveEntry & { readonly typeCode: "o" | "d" } =>
  entry.typeCode === "o" || entry.typeCode === "d";

/** True when a native executable has a structurally valid CArchive cookie. */
export const containsPyInstallerArchive = async (
  handle: FileHandle,
  fileSize: number,
  signal?: AbortSignal,
): Promise<boolean> => {
  const found = await findPyInstallerCookie(handle, fileSize, signal);
  return found?.ok === true;
};

/** Locate a structurally valid cookie. Invalid magic copies are skipped. */
export const findPyInstallerCookie = async (
  handle: FileHandle,
  fileSize: number,
  signal?: AbortSignal,
): Promise<Result<PyInstallerCookie, PyInstallerFailure> | undefined> => {
  if (
    !Number.isSafeInteger(fileSize) ||
    fileSize < PYINSTALLER_COOKIE_V20_BYTES
  )
    return undefined;
  const tailSize = Math.min(fileSize, PYINSTALLER_COOKIE_SEARCH_BYTES);
  const read = await readPyInstallerBytes(handle, {
    position: fileSize - tailSize,
    length: tailSize,
    label: "CArchive tail",
    signal,
  });
  if (!read.ok) return read;
  const observed = read.value;
  let failure: PyInstallerFailure | undefined;
  let from = observed.length;
  while (from >= PYINSTALLER_COOKIE_MAGIC.length) {
    const relative = observed
      .subarray(0, from)
      .lastIndexOf(PYINSTALLER_COOKIE_MAGIC);
    if (relative < 0) break;
    const cookieOffset = fileSize - tailSize + relative;
    const parsed = parseCookieAt(observed, relative, cookieOffset, fileSize);
    if (parsed.ok) return parsed;
    failure = parsed.error;
    from = relative;
  }
  return failure === undefined ? undefined : err(failure);
};

/** Read and parse the TOC that a validated cookie names. */
export const readCArchiveToc = async (
  handle: FileHandle,
  cookie: PyInstallerCookie,
  signal?: AbortSignal,
): Promise<Result<readonly CArchiveEntry[], PyInstallerFailure>> => {
  if (cookie.tocLength > MAX_TOC_BYTES)
    return err(
      pyInstallerFailure(
        "limit",
        "CArchive table of contents exceeds its bound",
      ),
    );
  const position = cookie.archiveStart + cookie.tocOffset;
  const read = await readPyInstallerBytes(handle, {
    position,
    length: cookie.tocLength,
    label: "CArchive table of contents",
    signal,
  });
  if (!read.ok) return read;
  const parsed = parseCArchiveToc(read.value);
  if (!parsed.ok) return parsed;
  const valid = validateCArchiveMembers(parsed.value, cookie.tocOffset);
  return valid.ok ? parsed : valid;
};

/** Parse TOC bytes. Each entry is a big-endian header plus a NUL-padded name. */
export const parseCArchiveToc = (
  bytes: Buffer,
): Result<readonly CArchiveEntry[], PyInstallerFailure> => {
  const entries: CArchiveEntry[] = [];
  let offset = 0;
  while (offset < bytes.length) {
    if (entries.length >= MAX_TOC_ENTRIES)
      return err(
        pyInstallerFailure(
          "limit",
          "CArchive table of contents exceeds its entry bound",
        ),
      );
    if (offset + TOC_HEADER_BYTES > bytes.length)
      return err(
        pyInstallerFailure(
          "format",
          "CArchive table of contents entry is truncated",
        ),
      );
    const entryLength = bytes.readUInt32BE(offset);
    if (entryLength < TOC_HEADER_BYTES || offset + entryLength > bytes.length)
      return err(
        pyInstallerFailure(
          "format",
          "CArchive table of contents entry extends outside the table",
        ),
      );
    const nameBytes = bytes.subarray(
      offset + TOC_HEADER_BYTES,
      offset + entryLength,
    );
    const name = tocName(nameBytes);
    if (!name.ok) return name;
    const compressionFlag = bytes[offset + 16] ?? 0;
    if (compressionFlag !== 0 && compressionFlag !== 1)
      return err(
        pyInstallerFailure(
          "format",
          `CArchive compression flag ${String(compressionFlag)} is not stored or zlib`,
        ),
      );
    const typeCode = bytes[offset + 17] ?? 0;
    if (typeCode < 0x20 || typeCode > 0x7e)
      return err(
        pyInstallerFailure(
          "format",
          "CArchive type code is not a printable character",
        ),
      );
    entries.push({
      index: entries.length,
      tocRecordOffset: offset,
      tocRecordLength: entryLength,
      name: name.value,
      typeCode: String.fromCharCode(typeCode),
      offset: bytes.readUInt32BE(offset + 4),
      compressedSize: bytes.readUInt32BE(offset + 8),
      uncompressedSize: bytes.readUInt32BE(offset + 12),
      compressionFlag,
    });
    offset += entryLength;
  }
  return ok(entries);
};

const parseCookieAt = (
  tail: Buffer,
  relative: number,
  cookieOffset: number,
  fileSize: number,
): Result<PyInstallerCookie, PyInstallerFailure> => {
  const modern = parseCookie(tail, relative, cookieOffset, fileSize, "2.1");
  if (modern.ok) return modern;
  const legacy = parseCookie(tail, relative, cookieOffset, fileSize, "2.0");
  return legacy.ok ? legacy : modern;
};

const parseCookie = (
  tail: Buffer,
  relative: number,
  cookieOffset: number,
  fileSize: number,
  layout: "2.0" | "2.1",
): Result<PyInstallerCookie, PyInstallerFailure> => {
  const cookieBytes =
    layout === "2.1"
      ? PYINSTALLER_COOKIE_V21_BYTES
      : PYINSTALLER_COOKIE_V20_BYTES;
  if (relative + cookieBytes > tail.length)
    return err(
      pyInstallerFailure(
        "format",
        "CArchive cookie extends past the end of the file",
      ),
    );
  const view = tail.subarray(relative, relative + cookieBytes);
  const packageLength = view.readUInt32BE(8);
  const tocOffset = view.readUInt32BE(12);
  const tocLength = view.readUInt32BE(16);
  const pythonVersion = view.readUInt32BE(20);
  if (
    !safeSum(tocOffset, tocLength, cookieBytes) ||
    packageLength !== tocOffset + tocLength + cookieBytes
  )
    return err(
      pyInstallerFailure(
        "format",
        "CArchive cookie does not describe a table of contents inside the package",
      ),
    );
  const archiveStart = cookieOffset + cookieBytes - packageLength;
  if (archiveStart < 0 || archiveStart + packageLength > fileSize)
    return err(
      pyInstallerFailure("format", "CArchive cookie range is outside the file"),
    );
  const library =
    layout === "2.1" ? libraryName(view.subarray(24, 88)) : ok(null);
  if (!library.ok) return library;
  return ok({
    layout,
    archiveStart,
    packageLength,
    tocOffset,
    tocLength,
    pythonVersion,
    pythonLibrary: library.value,
    cookieOffset,
  });
};

const libraryName = (
  bytes: Buffer,
): Result<string | null, PyInstallerFailure> => {
  const end = bytes.indexOf(0);
  const text = end < 0 ? bytes : bytes.subarray(0, end);
  if (end >= 0 && bytes.subarray(end).some((byte) => byte !== 0))
    return err(
      pyInstallerFailure(
        "format",
        "CArchive Python library name is not NUL-padded",
      ),
    );
  if (text.length === 0) return ok(null);
  try {
    return ok(
      new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(text),
    );
  } catch {
    return err(
      pyInstallerFailure(
        "format",
        "CArchive Python library name is not valid UTF-8",
      ),
    );
  }
};

const tocName = (bytes: Buffer): Result<string, PyInstallerFailure> => {
  const end = bytes.indexOf(0);
  const text = end < 0 ? bytes : bytes.subarray(0, end);
  if (text.length === 0)
    return err(pyInstallerFailure("format", "CArchive entry name is empty"));
  try {
    return ok(
      new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(text),
    );
  } catch {
    return err(
      pyInstallerFailure("format", "CArchive entry name is not valid UTF-8"),
    );
  }
};

const safeSum = (left: number, middle: number, right: number): boolean =>
  Number.isSafeInteger(left) &&
  Number.isSafeInteger(middle) &&
  Number.isSafeInteger(right) &&
  left >= 0 &&
  middle >= 0 &&
  right >= 0 &&
  left + middle + right <= Number.MAX_SAFE_INTEGER;

/** Source directory semantics are validated once before any consumer projects paths. */
const validateCArchiveMembers = (
  entries: readonly CArchiveEntry[],
  tocOffset: number,
): Result<null, PyInstallerFailure> => {
  const names = new Set<string>();
  for (const entry of entries) {
    if (isCArchiveDeclaration(entry)) {
      if (
        entry.compressedSize !== 0 ||
        entry.uncompressedSize !== 0 ||
        entry.compressionFlag !== 0
      )
        return err(
          pyInstallerFailure(
            "integrity",
            `CArchive declaration at table index ${String(entry.index)} has local payload or compression`,
          ),
        );
    } else {
      if (names.has(entry.name))
        return err(
          pyInstallerFailure(
            "integrity",
            `Duplicate CArchive member name at table index ${String(entry.index)}`,
          ),
        );
      names.add(entry.name);
    }
    if (
      entry.compressionFlag === 0 &&
      entry.compressedSize !== entry.uncompressedSize
    )
      return err(
        pyInstallerFailure(
          "integrity",
          `Stored CArchive member size disagrees with its table entry at table index ${String(entry.index)}`,
        ),
      );
    if (entry.offset > tocOffset)
      return err(
        pyInstallerFailure(
          "format",
          `CArchive member offset is outside the archive at table index ${String(entry.index)}`,
        ),
      );
  }
  const ranges = entries
    .filter((entry) => entry.compressedSize > 0)
    .map((entry) => ({
      index: entry.index,
      start: entry.offset,
      end: entry.offset + entry.compressedSize,
    }))
    .sort((left, right) => left.start - right.start);
  let occupied = 0;
  for (const range of ranges) {
    if (
      !Number.isSafeInteger(range.end) ||
      range.end > tocOffset ||
      range.start < occupied
    )
      return err(
        pyInstallerFailure(
          "integrity",
          `CArchive member extends outside the archive or overlaps another member at table index ${String(range.index)}`,
        ),
      );
    occupied = range.end;
  }
  return ok(null);
};