ipa-forge 0.1.0__tar.gz

ipa_forge-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,50 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  # Pure static checks: OS-independent, no macOS tooling or patch submodules
+  # needed, so this runs on ubuntu-latest for speed.
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11" # matches pyproject.toml's requires-python floor / [tool.mypy] python_version
+          cache: pip
+      - name: Install
+        run: pip install -e ".[dev]"
+      - name: Ruff check
+        run: ruff check .
+      - name: Ruff format
+        run: ruff format --check .
+      - name: Mypy
+        run: mypy ipa_forge/
+
+  # macOS-only: many unit tests compile real Mach-O binaries via `clang` and
+  # inspect them with `otool`/`lipo` (see tests/conftest.py) -- Apple-only
+  # tools not available on Linux runners, so the suite only runs here.
+  # macOS-marked integration tests that need a real Keychain signing
+  # identity self-skip gracefully (tests/conftest.py::synthetic_profile) --
+  # GitHub's macos-latest runners don't have one, so those run as skips.
+  # Single Python version (matches pyproject.toml's requires-python floor):
+  # macOS runner minutes are the expensive GH-hosted tier, and this repo
+  # doesn't carry per-version-specific code paths worth multiplying CI cost
+  # across the whole 3.11-3.13 support range to catch.
+  test:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+      - name: Install
+        run: pip install -e ".[dev]"
+      - name: Pytest
+        run: pytest tests/

ipa_forge-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+*.egg-info/
+build/
+dist/
+.DS_Store
+*.ipa.tmp/
+.pi/
+# staged tweak artifacts are built locally; keep the patch definitions only
+patches/*/build*/
+patches/*/dev/build*/
+patches/*/dylib/build/
+patches/*/dev/build-test/
+patches/*/assets/*.dylib
+.coverage

ipa_forge-0.1.0/.gitmodules

@@ -0,0 +1,9 @@
+[submodule "patches/youtube"]
+	path = patches/youtube
+	url = https://github.com/nandan-varma/ipa-forge-patches-youtube.git
+[submodule "patches/spotify"]
+	path = patches/spotify
+	url = https://github.com/nandan-varma/ipa-forge-patches-spotify.git
+[submodule "patches/instagram"]
+	path = patches/instagram
+	url = https://github.com/nandan-varma/ipa-forge-patches-instagram.git

ipa_forge-0.1.0/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to this project are documented here. Format loosely
+follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [0.1.0] - 2026-08-25
+
+Initial public release.
+
+### Added
+
+- Core patch engine: 17-stage pipeline (extract → dry-run gate → resource
+  patches → binary patches → dylib injection → codesign → repackage →
+  re-validate) driven entirely by external YAML patch definitions.
+- Patch operation types: `binary_replace`, `resource_replace`,
+  `resource_add`, `resource_remove`, `plist_edit`, `dylib_inject`.
+- Hook verification (`forge hooks verify|extract|audit|find|manifest|diff`):
+  cross-checks a dylib's declared runtime hook targets against the actual
+  Mach-O class/method tables before signing, and `hooks audit` catches
+  hooks a dylib calls but the YAML never declared.
+- General-purpose IPA reverse engineering (`forge analysis
+  classdump|strings|symbols|security|diff`), plus a read-only `/analysis`
+  viewer in the local GUI.
+- Per-extension provisioning-profile signing (repeatable `--profile`,
+  `ProfilePool`).
+- Local FastAPI GUI (`forge gui`) for novice-friendly patch application and
+  zip-based asset uploads.
+- GPLv3-or-later license.
+
+### Known limitations
+
+- macOS-only for signing and Mach-O/ObjC analysis (`hooks/`, `analysis/`,
+  `signing/`); `bundle/`, `patch/`, and dry-run work cross-platform.
+- FairPlay/App Store DRM decryption is explicitly out of scope — every
+  command assumes an already-decrypted `.ipa`.
+- Instruction-level disassembly, struct field expansion in the type-encoding
+  decoder, entitlements diffing, and Swift-native class support are tracked
+  in `ROADMAP.md`.

ipa_forge-0.1.0/CLAUDE.md

@@ -0,0 +1,200 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+A generic, data-driven iOS IPA patcher: extract a user-supplied `.ipa`, apply
+version-aware patches from external YAML (binary byte patches, resource
+replace/add/remove, dylib injection), and re-sign the result into a
+standard-structure `.ipa` that AltStore Classic can install/refresh.
+
+**Read [`STATE.md`](STATE.md) first, every session, before anything else in
+this file or in `docs/`.** It is the single source of truth for *current*
+status (which apps/features are shipped vs. beta/untested, where delivered
+IPAs live right now, decisions already made that shouldn't be re-litigated).
+This file (`CLAUDE.md`) covers what doesn't change session to session:
+architecture, hard constraints, and where to find the doc that answers a
+given question. If something here ever conflicts with `STATE.md`, `STATE.md`
+wins — it's updated far more often.
+
+## Documentation map
+
+Route by task, don't read everything:
+
+| Task | Read |
+| --- | --- |
+| **Starting a session** | [`STATE.md`](STATE.md) — current status, in-flight work, decisions not to undo |
+| Finding the right doc for anything else | [`docs/README.md`](docs/README.md) — the full doc index, table-of-contents style |
+| Port a **new app** end-to-end | [`docs/adding-an-app.md`](docs/adding-an-app.md) |
+| Add a **feature** to an existing hook dylib | [`docs/adding-a-feature.md`](docs/adding-a-feature.md) |
+| The **YAML patch-definition** contract | [`docs/patch-reference.md`](docs/patch-reference.md) |
+| The **CLI/GUI** reference | [`docs/usage.md`](docs/usage.md) |
+| **Reverse-engineer** any IPA (`forge analysis`: class-dump, strings, symbols, security, diff) | [`docs/reverse-engineering.md`](docs/reverse-engineering.md) |
+| An **error message** | [`docs/troubleshooting.md`](docs/troubleshooting.md) — message → cause → fix |
+| Testing on a **real device** via AltStore | [`docs/altstore_device_testing.md`](docs/altstore_device_testing.md) |
+| **Engine internals** before touching `pipeline.py`/`signing/` | [`docs/architecture.md`](docs/architecture.md) — component map, the 17-stage pipeline, two real bugs found empirically |
+| **Extending** the engine (new operation type, new provider) | [`docs/extensibility.md`](docs/extensibility.md) |
+| **Deferred work** (RE roadmap: disassembly, Swift support, etc.) | [`ROADMAP.md`](ROADMAP.md) — file/anchor pointers to resume |
+| A specific app's **runbook** (build/apply/verify commands, gotchas) | `patches/<app>/PLAYBOOK.md` |
+
+The patch sets (`patches/youtube/`, `patches/spotify/`, `patches/instagram/`)
+are private git submodules — `git clone --recursive` to get them, and
+**commit inside each submodule directory separately** before committing the
+updated submodule pointer in this repo; a plain top-level `git add -A` will
+silently skip submodule content changes.
+
+## Commands
+
+```bash
+# Setup (macOS with Xcode CLT; Python 3.11+)
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e .
+
+# Run all tests (includes real codesign signing against your local Keychain identity)
+pytest tests/
+
+# Run only tests that don't need macOS signing tools (e.g. to check Linux-safe code paths)
+pytest tests/ -m "not macos"
+
+# Run a single test
+pytest tests/unit/test_binary_patch.py::test_binary_replace_apply_mutates_file -v
+
+# CLI (installed as `forge` via pyproject.toml's [project.scripts])
+forge inspect path/to/App.ipa
+forge validate path/to/App.ipa
+forge patch --ipa <ipa> --patches <patches.yaml> --identity <id> --profile <profile> --output <out.ipa> [--dry-run] [--verbose]
+forge export-source --ipa <patched.ipa> --download-url <url> --output source.json
+forge gui   # launches the local FastAPI GUI on 127.0.0.1:8765 (+ /analysis RE viewer)
+
+# Hook verification (forge hooks --help): verify | extract | audit | find | manifest | diff
+forge hooks verify --ipa <ipa> --patches <patches.yaml>
+# Cross-check tweak source against the declared hooks: block -- catches a hook
+# the source calls but the YAML forgot to declare (invisible to --dry-run
+# otherwise; this is how real gaps were found in two of the three patch sets)
+forge hooks audit --ipa <ipa> --dir dylib/ --patches <patches.yaml>
+
+# General-purpose IPA reverse engineering (forge analysis --help), see docs/reverse-engineering.md
+forge analysis classdump --ipa <ipa> [--class NAME | --search REGEX]
+forge analysis diff --old <old.ipa> --new <new.ipa>
+
+# Regenerate the synthetic test fixture (only needed if changing its shape)
+scripts/rebuild_fixture.sh
+```
+
+Lint and typecheck (config lives in `pyproject.toml`): `ruff check .`,
+`ruff format --check .`, `mypy ipa_forge/`.
+
+## Architecture
+
+**Hard constraint, never violate it**: Apple's code signature format
+(CodeDirectory, CMS, SuperBlob, DER entitlements) is never reimplemented.
+`ipa_forge/signing/backend.py` is the *only* module allowed to invoke
+`codesign`/`security`; everything else shells out through it.
+
+**Dependency direction is one-way and enforced by convention, not tooling**:
+`patch/` and `signing/` both depend on `bundle/` but never on each other.
+`machO/` (arch selection, dylib injection, and the shared ObjC/Mach-O
+analysis engine in `machO/objc.py`) also depends on `bundle/`. `hooks/` and
+`analysis/` are siblings that both depend on `machO/objc.py`'s
+`MachOAnalysis` and never import each other. `pipeline.py` orchestrates
+`patch/`, `signing/`, `hooks/`, `validators/`, and `manifest.py`.
+
+**Hook verification (`ipa_forge/hooks/`)**: the `hooks:` block in a patch
+definition declares the dylib's runtime hook targets; `pipeline.py` verifies
+them against the app's main binary (class table + method lists + selrefs,
+chained-fixup aware — parsed by `machO/objc.py`, shared with `analysis/`)
+during the dry-run gate and fails when a `required` hook can't attach. This
+is the safety net for version drift — a renamed/removed class silently
+kills a hook otherwise, **but only for hooks actually declared in the
+`hooks:` block** — a hook the dylib source calls but the block never
+mentions is invisible to the dry-run gate by construction. `forge hooks
+audit --patches <yaml>` closes that specific gap by cross-checking the
+source scan against the declaration (`ipa_forge/hooks/scan.py` +
+`ipa_forge/cli/hooks.py::hooks_audit`); it isn't run automatically by
+`--dry-run`; run it as a standard part of the verify loop, not just when a
+hook seems broken. The CLI surface is `forge hooks
+verify|extract|audit|find|manifest|diff`. `cli/` and `gui/` call into
+`pipeline.py` for patching — neither touches `patch/` or `signing/`
+directly; `cli/` additionally uses `altstore/` (export-source) and
+`validators/` (inspect/validate) directly, and structural IPA validation
+(stage 1) is run by the pipeline, not by `bundle/`.
+
+**General-purpose reverse engineering (`ipa_forge/analysis/`)**:
+class-dump, strings, symbols, security posture, and version diffing for
+*any* IPA — not tied to a patch definition. Built on the same
+`machO/objc.py` engine `hooks/` uses; CLI surface is `forge analysis
+classdump|strings|symbols|security|diff`, plus a read-only `/analysis`
+page in the GUI. FairPlay decryption and instruction-level disassembly are
+deliberately out of scope — see `ipa_forge/analysis/__init__.py`'s
+docstring and `ROADMAP.md`.
+
+**The core engine is app-agnostic**: it understands patch operation *types*
+(`binary_replace`, `resource_replace`, `dylib_inject`, ...) via the
+`PatchOperation` protocol (`patch/base.py`), never a specific bundle id or
+byte pattern — those only ever come from user-supplied YAML parsed by
+`patch/schema.py` (pydantic) and `patch/loader.py`.
+
+### The pipeline (`ipa_forge/pipeline.py`)
+
+A fixed 17-stage sequence: extract → bottom-up inventory → parse Info.plist
+→ resolve applicable patch definitions → **dry-run gate** (every op must
+pass before anything mutates) → apply resources → apply binary patches →
+apply dylib injection (deliberately last — LIEF rewrites can shift binary
+offsets) → re-validate → **emit manifest** (pre-signing, for debugging) →
+load/validate provisioning profile → reconcile entitlements → embed profile
+→ recursive bottom-up codesign → verify → repackage → final re-validation
+(re-extract from scratch). The ordering encodes real dependencies; see
+`docs/architecture.md` for why each ordering constraint exists.
+
+### Two non-obvious things found empirically (both documented + tested)
+
+1. **`codesign` must target bundle *directories*, not raw executable
+   files**, for anything that is itself a bundle (main app, `.framework`,
+   `.appex`, watch app) — otherwise the `_CodeSignature/CodeResources` seal
+   covering `Info.plist` never gets created and a later
+   `codesign --verify --strict` fails. See
+   `signing/pipeline.py::sign_target_path`.
+2. **LIEF's `Binary.write()` on a single arch slice of a fat/universal
+   Mach-O silently discards every other architecture.** Injection code must
+   always write back through the parent `FatBinary` object
+   (`fat.write(path)`), never the extracted slice directly. See
+   `machO/injector.py`. `patch/binary.py`'s raw byte-offset read/write is
+   unaffected since it never goes through LIEF's write path.
+
+### Signing abstraction
+
+`signing/provider.py::SigningProvider` is an ABC with `LocalIdentityProvider`
+(signs via a Keychain identity — the only implementation that exists today)
+and `AltStoreCredentialProvider` (deliberate `NotImplementedError` stub for
+future AltServer-account-based signing — see `docs/extensibility.md` before
+implementing it).
+
+### Linux support boundary
+
+`ipa_forge/signing/` needs `codesign`/`security` (macOS only). Less obvious:
+`ipa_forge/machO/objc.py` (the shared ObjC/Mach-O analysis engine —
+`analyze_macho`/`analyze_bundle`) shells out to `otool`/`lipo`, which are
+also macOS-only, unlike the rest of `machO/` (`arch.py`, `injector.py` are
+LIEF-backed and Linux-safe). This means **`hooks/` and `analysis/` are not
+Linux-safe either** — both are built on `machO/objc.py`. Everything else
+(`bundle/`, `patch/`, `machO/arch.py`, `machO/injector.py`, dry-run) works
+without macOS. The boundary is which modules a code path imports, not a
+runtime OS check — no hooks/analysis tests are `@pytest.mark.macos`-gated
+today even though they need Xcode CLT, which is only a gap if someone
+actually runs them on a bare Linux CI runner.
+
+### Test fixture
+
+`fixtures/synthetic_app.ipa` is a real, from-scratch arm64 iOS Mach-O app —
+main executable + linked framework + an
+*unlinked* standalone dylib (the dylib-injection target) + a resource file —
+built via `scripts/rebuild_fixture.sh` directly against the iOS SDK rather
+than a hand-authored Xcode project. It's checked in as a binary artifact;
+tests consume it as-is. `tests/conftest.py` also has fixtures for compiling
+throwaway Mach-O binaries on the fly (`compiled_macho_binary`,
+`fat_macho_binary`) and for generating a self-signed test
+`.mobileprovision` (`synthetic_profile`) using whatever real Apple
+Development identity is in the local Keychain — tests requiring real
+signing are marked `@pytest.mark.macos` and skip gracefully if no suitable
+local identity/profile exists.