ipa-forge 0.1.0__py3-none-any.whl

ipa_forge/machO/arch.py

@@ -0,0 +1,94 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Read-only fat/universal Mach-O architecture selection, backed by LIEF."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import lief
+
+# Enum members are hashable at runtime (mypy agrees); Pyright's reportUnhashable
+# does not special-case enum members as dict keys (false positive).
+_ARCH_NAMES: dict[lief.MachO.Header.CPU_TYPE, str] = {
+    lief.MachO.Header.CPU_TYPE.ARM64: "arm64",  # pyright: ignore[reportUnhashable]
+    lief.MachO.Header.CPU_TYPE.ARM: "armv7",  # pyright: ignore[reportUnhashable]
+    lief.MachO.Header.CPU_TYPE.X86_64: "x86_64",  # pyright: ignore[reportUnhashable]
+    lief.MachO.Header.CPU_TYPE.X86: "i386",  # pyright: ignore[reportUnhashable]
+}
+
+
+class NotMachOError(Exception):
+    """Raised when the target file cannot be parsed as Mach-O at all."""
+
+
+class AmbiguousArchError(Exception):
+    """Raised when a fat/universal binary is targeted without an explicit `arch:` selector."""
+
+
+class ArchNotFoundError(Exception):
+    """Raised when an explicit `arch:` selector does not match any slice in the binary."""
+
+
+def arch_name(binary: lief.MachO.Binary) -> str:
+    """Canonical arch name (e.g. "arm64") for a parsed Mach-O slice."""
+    return _ARCH_NAMES.get(binary.header.cpu_type, str(binary.header.cpu_type))
+
+
+def require_slice(fat: lief.MachO.FatBinary, index: int) -> lief.MachO.Binary:
+    """LIEF's FatBinary.at() is typed as Optional; callers only use it after a
+    non-empty length check, so a None here means the file changed under us."""
+    binary = fat.at(index)
+    if binary is None:
+        raise NotMachOError(f"Mach-O slice {index} unexpectedly missing")
+    return binary
+
+
+def load_macho(path: Path, arch: str | None = None) -> lief.MachO.Binary:
+    """Return the single Mach-O slice to operate on.
+
+    Thin binaries are returned directly. Fat/universal binaries require an
+    explicit `arch` selector -- silently picking "the first slice" would make
+    patches applied to the wrong architecture on a per-device basis.
+    """
+    fat = lief.MachO.parse(str(path))
+    if fat is None or len(fat) == 0:
+        raise NotMachOError(f"{path} is not a valid Mach-O file")
+
+    if len(fat) == 1:
+        return require_slice(fat, 0)
+
+    available = [arch_name(require_slice(fat, i)) for i in range(len(fat))]
+    if arch is None:
+        raise AmbiguousArchError(
+            f"{path} is a universal binary with architectures {available}; "
+            "an explicit `arch:` selector is required in the patch definition"
+        )
+    for i in range(len(fat)):
+        binary = require_slice(fat, i)
+        if arch_name(binary) == arch:
+            return binary
+    raise ArchNotFoundError(f"Architecture '{arch}' not found in {path}; available: {available}")
+
+
+def available_archs(path: Path) -> list[str]:
+    fat = lief.MachO.parse(str(path))
+    if fat is None or len(fat) == 0:
+        raise NotMachOError(f"{path} is not a valid Mach-O file")
+    return [arch_name(require_slice(fat, i)) for i in range(len(fat))]
+
+
+def slice_byte_range(path: Path, arch: str | None = None) -> tuple[int, int]:
+    """Return the (start, end) byte offsets of the selected arch's slice within
+    the on-disk file. For thin (non-fat) binaries this is the whole file --
+    used to bound binary-pattern search/replace to the correct architecture
+    so a patch never silently lands in the wrong slice of a universal binary.
+    """
+    fat = lief.MachO.parse(str(path))
+    if fat is None or len(fat) == 0:
+        raise NotMachOError(f"{path} is not a valid Mach-O file")
+
+    if len(fat) == 1:
+        return 0, path.stat().st_size
+
+    binary = load_macho(path, arch)
+    return binary.fat_offset, binary.fat_offset + binary.original_size

ipa_forge/machO/detect.py

@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Lightweight Mach-O detection by magic number, used by the bundle inventory walker."""
+
+from __future__ import annotations
+
+import struct
+from pathlib import Path
+
+from ipa_forge.bundle.models import AppBundle, MachOKind
+
+_MACHO_MAGICS = {
+    0xFEEDFACE,  # MH_MAGIC (32-bit)
+    0xFEEDFACF,  # MH_MAGIC_64
+    0xCEFAEDFE,  # MH_CIGAM (32-bit, byte-swapped)
+    0xCFFAEDFE,  # MH_CIGAM_64
+    0xCAFEBABE,  # FAT_MAGIC
+    0xBEBAFECA,  # FAT_CIGAM
+}
+
+
+def is_macho_file(path: Path) -> bool:
+    if not path.is_file() or path.is_symlink():
+        return False
+    try:
+        with open(path, "rb") as f:
+            header = f.read(4)
+    except OSError:
+        return False
+    if len(header) < 4:
+        return False
+    (magic,) = struct.unpack(">I", header)
+    return magic in _MACHO_MAGICS
+
+
+def bundle_executable_paths(bundle: AppBundle, kinds: set[MachOKind] | None = None) -> list[Path]:
+    """Every on-disk executable in the bundle, main binary first: the main
+    executable plus each `MachOTarget` whose `kind` is in `kinds` (default:
+    every kind -- main, framework, dylib, appex, watch_app, other). Callers
+    doing a narrower analysis (e.g. hook verification, which only cares
+    about app code) pass an explicit, smaller `kinds` set."""
+    paths = [bundle.root / bundle.main_executable_name]
+    for target in bundle.executables:
+        # the main executable is always target.kind == "main" and already
+        # covered by the first line above -- skip it here or it'd be listed
+        # (and analyzed) twice.
+        if target.kind == "main":
+            continue
+        if kinds is None or target.kind in kinds:
+            paths.append(bundle.extraction_root / Path(target.bundle_relative))
+    return [p for p in paths if p.is_file()]

ipa_forge/machO/injector.py

@@ -0,0 +1,99 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""LIEF-backed dylib load-command injection.
+
+Modifies the target Mach-O's load commands only -- copying the dylib file
+into the bundle (if it isn't already present) is a separate `resource_add`
+patch operation, and re-signing (required because LIEF's rewrite invalidates
+any existing code signature) happens later in the pipeline's signing stage.
+Never silently continues past a load-command failure: every outcome maps to
+one of the four explicit statuses below.
+"""
+
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass
+from pathlib import Path
+
+import lief
+
+from ipa_forge.machO.arch import (
+    AmbiguousArchError,
+    ArchNotFoundError,
+    NotMachOError,
+    arch_name,
+    require_slice,
+)
+
+
+class InjectionStatus(enum.Enum):
+    INJECTED = "INJECTED"
+    INJECTION_SKIPPED = "INJECTION_SKIPPED"
+    INJECTION_UNSUPPORTED = "INJECTION_UNSUPPORTED"
+    INJECTION_FAILED = "INJECTION_FAILED"
+
+
+@dataclass
+class InjectionResult:
+    status: InjectionStatus
+    message: str = ""
+
+
+_FACTORY_BY_LOAD_COMMAND = {
+    "LC_LOAD_DYLIB": lief.MachO.DylibCommand.load_dylib,
+    "LC_LOAD_WEAK_DYLIB": lief.MachO.DylibCommand.weak_lib,
+}
+
+
+def _select_slice(fat: lief.MachO.FatBinary, arch: str | None) -> lief.MachO.Binary:
+    """Like machO.arch.load_macho, but keeps the FatBinary container so the
+    caller can write it back whole -- writing an individually-selected slice
+    directly (`binary.write(path)`) discards every *other* slice in a
+    universal binary, silently corrupting it."""
+    if len(fat) == 1:
+        return require_slice(fat, 0)
+
+    available = [arch_name(require_slice(fat, i)) for i in range(len(fat))]
+    if arch is None:
+        raise AmbiguousArchError(
+            f"universal binary with architectures {available}; an explicit `arch:` selector is required"
+        )
+    for i in range(len(fat)):
+        binary = require_slice(fat, i)
+        if arch_name(binary) == arch:
+            return binary
+    raise ArchNotFoundError(f"architecture '{arch}' not found; available: {available}")
+
+
+def inject_dylib(
+    target_path: Path,
+    dylib_install_name: str,
+    arch: str | None = None,
+    load_command: str = "LC_LOAD_DYLIB",
+) -> InjectionResult:
+    if load_command not in _FACTORY_BY_LOAD_COMMAND:
+        return InjectionResult(InjectionStatus.INJECTION_FAILED, f"unknown load_command '{load_command}'")
+
+    fat = lief.MachO.parse(str(target_path))
+    if fat is None or len(fat) == 0:
+        return InjectionResult(InjectionStatus.INJECTION_UNSUPPORTED, f"{target_path} is not a valid Mach-O file")
+
+    try:
+        binary = _select_slice(fat, arch)
+    except NotMachOError as e:
+        return InjectionResult(InjectionStatus.INJECTION_UNSUPPORTED, str(e))
+    except (AmbiguousArchError, ArchNotFoundError) as e:
+        return InjectionResult(InjectionStatus.INJECTION_FAILED, str(e))
+
+    if dylib_install_name in {lib.name for lib in binary.libraries}:
+        return InjectionResult(InjectionStatus.INJECTION_SKIPPED, f"{dylib_install_name} is already loaded")
+
+    try:
+        command = _FACTORY_BY_LOAD_COMMAND[load_command](dylib_install_name)
+        if binary.add(command) is None:
+            return InjectionResult(InjectionStatus.INJECTION_FAILED, "LIEF failed to add the load command")
+        fat.write(str(target_path))
+    except Exception as e:  # noqa: BLE001 -- LIEF raises broad/internal exception types on malformed input
+        return InjectionResult(InjectionStatus.INJECTION_FAILED, f"LIEF injection failed: {e}")
+
+    return InjectionResult(InjectionStatus.INJECTED, f"added {load_command} {dylib_install_name}")