ipa-forge 0.1.0__py3-none-any.whl

ipa_forge/patch/binary.py

@@ -0,0 +1,131 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Deterministic byte-pattern binary patching, bounded to a specific arch slice."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from ipa_forge.machO.arch import (
+    AmbiguousArchError,
+    ArchNotFoundError,
+    NotMachOError,
+    slice_byte_range,
+)
+from ipa_forge.patch.base import PatchContext, PatchResult
+
+
+class PatternError(Exception):
+    pass
+
+
+def parse_hex_pattern(pattern: str) -> tuple[bytes, bytes]:
+    """Parse a space-separated hex byte pattern with `??` as a wildcard byte.
+
+    Returns (bytes, mask) where mask[i] == 0xFF means that byte must match
+    exactly and mask[i] == 0x00 means "don't care".
+    """
+    tokens = pattern.split()
+    if not tokens:
+        raise PatternError("empty pattern")
+    data = bytearray()
+    mask = bytearray()
+    for tok in tokens:
+        if tok == "??":
+            data.append(0)
+            mask.append(0)
+            continue
+        try:
+            value = int(tok, 16)
+        except ValueError as e:
+            raise PatternError(f"invalid hex byte token '{tok}'") from e
+        if not 0 <= value <= 0xFF:
+            raise PatternError(f"byte token '{tok}' out of range")
+        data.append(value)
+        mask.append(0xFF)
+    return bytes(data), bytes(mask)
+
+
+def find_matches(haystack: bytes, pattern: bytes, mask: bytes, start: int = 0, end: int | None = None) -> list[int]:
+    """Return absolute offsets in `haystack` where `pattern` (respecting `mask`)
+    matches, restricted to the [start, end) window."""
+    end = len(haystack) if end is None else end
+    plen = len(pattern)
+    offsets = []
+    for i in range(start, end - plen + 1):
+        window = haystack[i : i + plen]
+        if all((b & m) == (p & m) for b, p, m in zip(window, pattern, mask, strict=True)):
+            offsets.append(i)
+    return offsets
+
+
+@dataclass
+class BinaryReplaceOp:
+    op_id: str
+    executable: str
+    pattern: str
+    replacement: str
+    expected_matches: int = 1
+    arch: str | None = None
+
+    def _resolve_target(self, ctx: PatchContext) -> Path:
+        for target in ctx.bundle.executables:
+            if Path(target.bundle_relative).name == self.executable:
+                return target.path
+        raise FileNotFoundError(f"executable '{self.executable}' not found in bundle inventory")
+
+    def _plan(self, ctx: PatchContext) -> tuple[Path, bytes, bytes, bytes, list[int]]:
+        target_path = self._resolve_target(ctx)
+        start, end = slice_byte_range(target_path, self.arch)
+        data = target_path.read_bytes()
+        pattern, mask = parse_hex_pattern(self.pattern)
+        offsets = find_matches(data, pattern, mask, start=start, end=end)
+        return target_path, data, pattern, mask, offsets
+
+    def _check_match_count(self, offsets: list[int]) -> str | None:
+        if len(offsets) != self.expected_matches:
+            return f"expected {self.expected_matches} match(es), found {len(offsets)} at offsets {offsets}"
+        return None
+
+    def dry_run(self, ctx: PatchContext) -> PatchResult:
+        try:
+            _, _, _, _, offsets = self._plan(ctx)
+        except (FileNotFoundError, PatternError, NotMachOError, AmbiguousArchError, ArchNotFoundError) as e:
+            return PatchResult(op_id=self.op_id, status="failed", message=str(e))
+
+        error = self._check_match_count(offsets)
+        if error:
+            return PatchResult(op_id=self.op_id, status="failed", message=error)
+        return PatchResult(op_id=self.op_id, status="dry_run_ok")
+
+    def apply(self, ctx: PatchContext) -> PatchResult:
+        try:
+            target_path, data, pattern, _, offsets = self._plan(ctx)
+        except (FileNotFoundError, PatternError, NotMachOError, AmbiguousArchError, ArchNotFoundError) as e:
+            return PatchResult(op_id=self.op_id, status="failed", message=str(e))
+
+        error = self._check_match_count(offsets)
+        if error:
+            return PatchResult(op_id=self.op_id, status="failed", message=error)
+
+        replacement, _ = parse_hex_pattern(self.replacement)
+        if len(replacement) != len(pattern):
+            return PatchResult(
+                op_id=self.op_id,
+                status="failed",
+                message=f"replacement length ({len(replacement)}) must equal pattern length ({len(pattern)})",
+            )
+
+        buf = bytearray(data)
+        for offset in offsets:
+            buf[offset : offset + len(replacement)] = replacement
+        target_path.write_bytes(bytes(buf))
+
+        return PatchResult(
+            op_id=self.op_id,
+            status="applied",
+            message=f"replaced {len(offsets)} match(es) at {offsets}",
+            files_touched=[target_path],
+            macho_modified=True,
+            category="modified",
+        )

ipa_forge/patch/dylib.py

@@ -0,0 +1,59 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Dylib load-command injection patch operation.
+
+Assumes the dylib file is already present in the bundle (placed there by a
+separate resource_add operation, or shipped in the original app) -- this
+operation's only job is the Mach-O load-command edit itself.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from ipa_forge.machO.injector import InjectionStatus, inject_dylib
+from ipa_forge.patch.base import PatchContext, PatchResult
+
+
+@dataclass
+class DylibInjectOp:
+    op_id: str
+    executable: str
+    install_name: str
+    arch: str | None = None
+    load_command: str = "LC_LOAD_DYLIB"
+
+    def _resolve_target(self, ctx: PatchContext) -> Path:
+        for target in ctx.bundle.executables:
+            if Path(target.bundle_relative).name == self.executable:
+                return target.path
+        raise FileNotFoundError(f"executable '{self.executable}' not found in bundle inventory")
+
+    def dry_run(self, ctx: PatchContext) -> PatchResult:
+        try:
+            self._resolve_target(ctx)
+        except FileNotFoundError as e:
+            return PatchResult(op_id=self.op_id, status="failed", message=str(e))
+        return PatchResult(op_id=self.op_id, status="dry_run_ok")
+
+    def apply(self, ctx: PatchContext) -> PatchResult:
+        try:
+            target_path = self._resolve_target(ctx)
+        except FileNotFoundError as e:
+            return PatchResult(op_id=self.op_id, status="failed", message=str(e))
+
+        result = inject_dylib(target_path, self.install_name, arch=self.arch, load_command=self.load_command)
+
+        if result.status == InjectionStatus.INJECTED:
+            return PatchResult(
+                op_id=self.op_id,
+                status="applied",
+                message=result.message,
+                files_touched=[target_path],
+                macho_modified=True,
+                category="modified",
+            )
+        if result.status == InjectionStatus.INJECTION_SKIPPED:
+            return PatchResult(op_id=self.op_id, status="skipped", message=result.message)
+        # INJECTION_UNSUPPORTED and INJECTION_FAILED both mean the patch did not apply.
+        return PatchResult(op_id=self.op_id, status="failed", message=f"{result.status.value}: {result.message}")

ipa_forge/patch/engine.py

@@ -0,0 +1,48 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Dry-run gate + ordered apply for a resolved set of patch operations.
+
+Enforces pipeline stages 5-8: every operation must report dry_run_ok before
+anything mutates, then mutations run resource/plist ops -> binary ops ->
+dylib injection last (LIEF load-command rewrites can shift byte offsets
+binary patches depend on, so injection must never run before binary
+patching). Resource and plist edits share a rank: neither touches Mach-O
+layout, so their relative order carries no correctness constraint.
+"""
+
+from __future__ import annotations
+
+from ipa_forge.patch.base import PatchContext, PatchOperation, PatchResult
+from ipa_forge.patch.binary import BinaryReplaceOp
+from ipa_forge.patch.dylib import DylibInjectOp
+from ipa_forge.patch.plist import PlistEditOp
+from ipa_forge.patch.resource import ResourceAddOp, ResourceRemoveOp, ResourceReplaceOp
+
+
+class PatchValidationError(Exception):
+    def __init__(self, results: list[PatchResult]):
+        self.results = results
+        failures = "; ".join(f"{r.op_id}: {r.message}" for r in results if r.status == "failed")
+        super().__init__(f"patch dry-run validation failed: {failures}")
+
+
+def dry_run_all(ops: list[PatchOperation], ctx: PatchContext) -> list[PatchResult]:
+    return [op.dry_run(ctx) for op in ops]
+
+
+def _apply_order_rank(op: PatchOperation) -> int:
+    if isinstance(op, (ResourceReplaceOp, ResourceAddOp, ResourceRemoveOp, PlistEditOp)):
+        return 0
+    if isinstance(op, BinaryReplaceOp):
+        return 1
+    if isinstance(op, DylibInjectOp):
+        return 2
+    return 3
+
+
+def apply_all(ops: list[PatchOperation], ctx: PatchContext) -> list[PatchResult]:
+    dry_results = dry_run_all(ops, ctx)
+    if any(r.status != "dry_run_ok" for r in dry_results):
+        raise PatchValidationError(dry_results)
+
+    ordered = sorted(ops, key=_apply_order_rank)
+    return [op.apply(ctx) for op in ordered]

ipa_forge/patch/loader.py

@@ -0,0 +1,88 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Loads patch-definition YAML/JSON files and builds concrete PatchOperation instances."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+from pydantic import ValidationError
+
+from ipa_forge.patch.base import PatchOperation
+from ipa_forge.patch.binary import BinaryReplaceOp
+from ipa_forge.patch.dylib import DylibInjectOp
+from ipa_forge.patch.plist import PlistEditOp
+from ipa_forge.patch.resource import ResourceAddOp, ResourceRemoveOp, ResourceReplaceOp
+from ipa_forge.patch.schema import (
+    BinaryReplaceSpec,
+    DylibInjectSpec,
+    PatchDefinition,
+    PlistEditSpec,
+    ResourceAddSpec,
+    ResourceRemoveSpec,
+    ResourceReplaceSpec,
+)
+
+
+class PatchLoadError(Exception):
+    """Raised when the patch-definition file cannot be read, parsed as YAML, or validated."""
+
+
+def _validation_error_details(error: ValidationError) -> str:
+    """Compact single-line summary of a pydantic ValidationError."""
+    return "; ".join(f"{'.'.join(map(str, err['loc'])) or '<root>'}: {err['msg']}" for err in error.errors())
+
+
+def load_patch_definition(path: Path) -> PatchDefinition:
+    try:
+        with open(path) as f:
+            raw = yaml.safe_load(f)
+    except OSError as e:
+        raise PatchLoadError(f"cannot read patch definition '{path}': {e}") from e
+    except yaml.YAMLError as e:
+        raise PatchLoadError(f"patch definition '{path}' is not valid YAML: {e}") from e
+    try:
+        return PatchDefinition.model_validate(raw)
+    except ValidationError as e:
+        # Surface schema violations as a single-line actionable error rather
+        # than letting pydantic's multi-line ValidationError escape as a
+        # traceback (F2).
+        raise PatchLoadError(f"patch definition '{path}' is invalid: {_validation_error_details(e)}") from e
+
+
+def build_operations(definition: PatchDefinition) -> list[PatchOperation]:
+    ops: list[PatchOperation] = []
+    for spec in definition.patches:
+        if isinstance(spec, BinaryReplaceSpec):
+            ops.append(
+                BinaryReplaceOp(
+                    op_id=spec.id,
+                    executable=spec.executable,
+                    pattern=spec.pattern,
+                    replacement=spec.replacement,
+                    expected_matches=spec.expected_matches,
+                    arch=spec.arch,
+                )
+            )
+        elif isinstance(spec, ResourceReplaceSpec):
+            ops.append(ResourceReplaceOp(op_id=spec.id, path=spec.path, source=spec.source))
+        elif isinstance(spec, ResourceAddSpec):
+            ops.append(ResourceAddOp(op_id=spec.id, path=spec.path, source=spec.source))
+        elif isinstance(spec, ResourceRemoveSpec):
+            ops.append(ResourceRemoveOp(op_id=spec.id, path=spec.path))
+        elif isinstance(spec, DylibInjectSpec):
+            ops.append(
+                DylibInjectOp(
+                    op_id=spec.id,
+                    executable=spec.executable,
+                    install_name=spec.install_name,
+                    arch=spec.arch,
+                    load_command=spec.load_command,
+                )
+            )
+        elif isinstance(spec, PlistEditSpec):
+            ops.append(PlistEditOp(op_id=spec.id, action=spec.action, key=spec.key, value=spec.value, path=spec.path))
+        else:
+            # Unreachable via the pydantic discriminated union in patch/schema.py
+            raise TypeError(f"unknown patch spec type: {spec!r}")
+    return ops

ipa_forge/patch/paths.py

@@ -0,0 +1,19 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Bundle-relative path resolution shared by patch operations that touch
+files inside the app bundle (resource_replace/add/remove, plist_edit)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+class BundlePathError(Exception):
+    """Raised when a bundle-relative path would escape the app bundle root."""
+
+
+def resolve_bundle_path(bundle_root: Path, relative: str) -> Path:
+    bundle_root = bundle_root.resolve()
+    candidate = (bundle_root / relative).resolve()
+    if candidate != bundle_root and bundle_root not in candidate.parents:
+        raise BundlePathError(f"destination '{relative}' escapes the app bundle root")
+    return candidate

ipa_forge/patch/plist.py

@@ -0,0 +1,61 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Info.plist key set/remove operation, following the same single-file,
+single-responsibility pattern as the resource operations."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Literal
+
+from ipa_forge.bundle.plist import read_plist, write_plist
+from ipa_forge.patch.base import PatchContext, PatchResult
+from ipa_forge.patch.paths import BundlePathError, resolve_bundle_path
+
+
+@dataclass
+class PlistEditOp:
+    op_id: str
+    action: Literal["set", "remove"]
+    key: str
+    value: Any = None
+    path: str = "Info.plist"
+
+    def _resolve(self, ctx: PatchContext) -> Path:
+        return resolve_bundle_path(ctx.bundle.root, self.path)
+
+    def dry_run(self, ctx: PatchContext) -> PatchResult:
+        try:
+            target = self._resolve(ctx)
+        except BundlePathError as e:
+            return PatchResult(op_id=self.op_id, status="failed", message=str(e))
+        if not target.is_file():
+            return PatchResult(op_id=self.op_id, status="failed", message=f"plist '{target}' does not exist")
+        try:
+            plist = read_plist(target)
+        except (OSError, ValueError) as e:  # plistlib can only raise these on malformed input
+            return PatchResult(op_id=self.op_id, status="failed", message=f"failed to parse '{target}': {e}")
+        if self.action == "remove" and self.key not in plist:
+            return PatchResult(op_id=self.op_id, status="failed", message=f"key '{self.key}' not present in {target}")
+        return PatchResult(op_id=self.op_id, status="dry_run_ok")
+
+    def apply(self, ctx: PatchContext) -> PatchResult:
+        dry = self.dry_run(ctx)
+        if dry.status != "dry_run_ok":
+            return dry
+
+        target = self._resolve(ctx)
+        plist = read_plist(target)
+        if self.action == "set":
+            plist[self.key] = self.value
+        else:
+            del plist[self.key]
+        write_plist(target, plist)
+
+        return PatchResult(
+            op_id=self.op_id,
+            status="applied",
+            message=f"{self.action} '{self.key}' in {target}",
+            files_touched=[target],
+            category="modified",
+        )

ipa_forge/patch/resolver.py

@@ -0,0 +1,37 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Selects which patch definitions apply to a given bundle, by bundle_id + version."""
+
+from __future__ import annotations
+
+from ipa_forge.bundle.models import AppBundle
+from ipa_forge.patch.schema import PatchDefinition, VersionExact
+from ipa_forge.patch.version import parse_version
+
+
+def target_matches(bundle: AppBundle, definition: PatchDefinition) -> bool:
+    if bundle.bundle_id != definition.target.bundle_id:
+        return False
+
+    version_spec = definition.target.version
+    if isinstance(version_spec, VersionExact):
+        return bundle.version == version_spec.exact
+
+    v = parse_version(bundle.version)
+    if version_spec.min is not None and v < parse_version(version_spec.min):
+        return False
+    return version_spec.max is None or v < parse_version(version_spec.max)
+
+
+def resolve_definitions(
+    bundle: AppBundle, definitions: list[PatchDefinition], *, ignore_version: bool = False
+) -> list[PatchDefinition]:
+    """Select definitions whose bundle id matches; version must match unless
+    ``ignore_version`` (used by the GUI's non-blocking mismatch path — the
+    hooks gate still guards what actually attaches)."""
+    result = []
+    for d in definitions:
+        if bundle.bundle_id != d.target.bundle_id:
+            continue
+        if ignore_version or target_matches(bundle, d):
+            result.append(d)
+    return result

ipa_forge/patch/resource.py

@@ -0,0 +1,135 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Resource file replace/add/remove operations, sandboxed to the app bundle root.
+
+Trusted-input model: `source:` paths resolve relative to the patch definition
+file and are intentionally *not* sandboxed -- the definition, the IPA, and the
+signing credentials are all supplied by the same trusted user, so a definition
+may reference an absolute path or sibling directory (F9). Revisit if the GUI
+ever serves untrusted/multi-user uploads.
+"""
+
+from __future__ import annotations
+
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+
+from ipa_forge.patch.base import PatchContext, PatchResult
+from ipa_forge.patch.paths import BundlePathError, resolve_bundle_path
+
+
+@dataclass
+class _SourceCopyOp:
+    """Shared fields + resolution for ops that copy a patch-source-relative
+    file/dir into the bundle. `path` is sandboxed to the bundle root; `source`
+    resolves against the patch set dir (trusted-input model, see F9)."""
+
+    op_id: str
+    path: str
+    source: str
+
+    def _resolve(self, ctx: PatchContext) -> tuple[Path, Path]:
+        dest = resolve_bundle_path(ctx.bundle.root, self.path)
+        src = (ctx.patch_source_dir / self.source).resolve()
+        return dest, src
+
+
+@dataclass
+class ResourceReplaceOp(_SourceCopyOp):
+    def dry_run(self, ctx: PatchContext) -> PatchResult:
+        try:
+            dest, src = self._resolve(ctx)
+        except BundlePathError as e:
+            return PatchResult(op_id=self.op_id, status="failed", message=str(e))
+        if not src.is_file():
+            return PatchResult(op_id=self.op_id, status="failed", message=f"source '{src}' does not exist")
+        if not dest.is_file():
+            return PatchResult(
+                op_id=self.op_id,
+                status="failed",
+                message=f"destination '{dest}' does not exist (use resource_add to create new files)",
+            )
+        return PatchResult(op_id=self.op_id, status="dry_run_ok")
+
+    def apply(self, ctx: PatchContext) -> PatchResult:
+        dry = self.dry_run(ctx)
+        if dry.status != "dry_run_ok":
+            return dry
+        dest, src = self._resolve(ctx)
+        try:
+            dest.write_bytes(src.read_bytes())
+        except OSError as e:
+            return PatchResult(op_id=self.op_id, status="failed", message=f"failed to replace '{dest}': {e}")
+        return PatchResult(
+            op_id=self.op_id, status="applied", message=f"replaced {dest}", files_touched=[dest], category="modified"
+        )
+
+
+@dataclass
+class ResourceAddOp(_SourceCopyOp):
+    def dry_run(self, ctx: PatchContext) -> PatchResult:
+        try:
+            dest, src = self._resolve(ctx)
+        except BundlePathError as e:
+            return PatchResult(op_id=self.op_id, status="failed", message=str(e))
+        if not src.exists():
+            return PatchResult(op_id=self.op_id, status="failed", message=f"source '{src}' does not exist")
+        if dest.exists():
+            return PatchResult(
+                op_id=self.op_id,
+                status="failed",
+                message=f"destination '{dest}' already exists (use resource_replace to overwrite)",
+            )
+        return PatchResult(op_id=self.op_id, status="dry_run_ok")
+
+    def apply(self, ctx: PatchContext) -> PatchResult:
+        dry = self.dry_run(ctx)
+        if dry.status != "dry_run_ok":
+            return dry
+        dest, src = self._resolve(ctx)
+        try:
+            if src.is_dir():
+                # Whole-directory staging (e.g. a .framework): copy recursively.
+                shutil.copytree(src, dest, symlinks=True)
+            else:
+                dest.parent.mkdir(parents=True, exist_ok=True)
+                dest.write_bytes(src.read_bytes())
+        except OSError as e:
+            return PatchResult(op_id=self.op_id, status="failed", message=f"failed to add '{dest}': {e}")
+        return PatchResult(
+            op_id=self.op_id, status="applied", message=f"added {dest}", files_touched=[dest], category="added"
+        )
+
+
+@dataclass
+class ResourceRemoveOp:
+    op_id: str
+    path: str
+
+    def _resolve(self, ctx: PatchContext) -> Path:
+        return resolve_bundle_path(ctx.bundle.root, self.path)
+
+    def dry_run(self, ctx: PatchContext) -> PatchResult:
+        try:
+            dest = self._resolve(ctx)
+        except BundlePathError as e:
+            return PatchResult(op_id=self.op_id, status="failed", message=str(e))
+        if not dest.exists():
+            return PatchResult(op_id=self.op_id, status="failed", message=f"destination '{dest}' does not exist")
+        return PatchResult(op_id=self.op_id, status="dry_run_ok")
+
+    def apply(self, ctx: PatchContext) -> PatchResult:
+        dry = self.dry_run(ctx)
+        if dry.status != "dry_run_ok":
+            return dry
+        dest = self._resolve(ctx)
+        try:
+            if dest.is_dir():
+                shutil.rmtree(dest)
+            else:
+                dest.unlink()
+        except OSError as e:
+            return PatchResult(op_id=self.op_id, status="failed", message=f"failed to remove '{dest}': {e}")
+        return PatchResult(
+            op_id=self.op_id, status="applied", message=f"removed {dest}", files_touched=[dest], category="removed"
+        )