ipa-dlp 0.3.0__py3-none-any.whl

ipa_dlp-0.3.0.dist-info/METADATA

@@ -0,0 +1,414 @@
+Metadata-Version: 2.4
+Name: ipa-dlp
+Version: 0.3.0
+Summary: Fetch, decrypt, and inspect personalized App Store IPAs.
+Author: Benjamin Liou
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+
+# ipa-dlp
+
+A cross-platform CLI and Python library for fetching, decrypting, and
+extracting App Store IPAs and Mach-O binaries (powered by
+[ipatool](https://github.com/majd/ipatool) and
+[UnfairPlay](https://github.com/DrWhax/unfairplay)). It turns this:
+
+```sh
+ipatool auth login ...
+ipatool download ...
+unfairplay setup ...
+unfairplay decrypt ...
+```
+
+into this:
+
+```sh
+ipa-dlp get spotify@9.1.88
+```
+
+It prompts for your Apple ID in the terminal (including 2FA) by default;
+`--gui` switches to native macOS dialogs. On an Apple Silicon Mac it installs
+pinned copies of both tools, recovers the reusable FairPlay model on first use
+with one admin prompt, downloads the requested app version, decrypts it,
+strips the App Store account data, and verifies the plaintext before reporting
+success. On macOS Intel, Linux, and Windows, search, version history,
+`get --encrypted`, and local extraction work; FairPlay decryption requires an
+Apple Silicon Mac.
+
+## Requirements
+
+- Python 3.9+
+- macOS, Linux, or Windows for search, `get -F`, `get --encrypted`, and local
+  extraction (`ipatool` is downloaded automatically for your platform)
+- An Apple Silicon Mac for FairPlay decryption (`get` without `--encrypted`,
+  `decrypt`, `setup --seed`), plus admin rights for the one-time model recovery
+
+## Platform support
+
+| Capability | macOS arm64 | macOS Intel | Linux | Windows |
+| --- | --- | --- | --- | --- |
+| Search, `get -F`, `get --encrypted` | yes | yes | yes | yes |
+| `extract` / `load_macho` on decrypted inputs | yes | yes | yes | yes |
+| `get` (decrypt), `decrypt`, `setup --seed` | yes | no | no | no |
+
+Linux amd64/arm64 and Windows amd64/arm64 are covered by ipatool's official
+release builds. `--gui` is macOS-only; the other platforms use terminal
+prompts.
+
+## Install
+
+### Homebrew (macOS, recommended)
+
+```sh
+brew tap ipakit/ipa-dlp
+brew install ipa-dlp
+```
+
+If Homebrew complains that the tap is untrusted (some Homebrew 7 builds gate
+third-party taps), run `brew trust ipakit/ipa-dlp` and retry.
+
+Then:
+
+```sh
+ipa-dlp setup
+```
+
+### From source (macOS)
+
+```sh
+git clone https://github.com/ipakit/ipa-dlp.git
+cd ipa-dlp
+./install.sh
+```
+
+This installs the `ipa-dlp` entrypoint and its `ipa_dlp.py` module into
+`~/.local/bin/`, registers that directory in the Python user site-packages
+(`ipa_dlp.pth`) so `import ipa_dlp` works from any script, then runs
+`ipa-dlp setup`. No `sudo` is needed; the first decryption asks for admin
+once.
+
+If `~/.local/bin` is not on your `PATH`:
+
+```sh
+./install.sh --add-path
+```
+
+or call the full path.
+
+### pip / pipx (any OS)
+
+```sh
+pipx install ipa-dlp
+# or
+python3 -m pip install ipa-dlp
+```
+
+On Linux and Windows this is the supported install path; `install.sh` is
+macOS-only. `ipatool` is fetched for your OS/architecture on first use.
+
+## Use
+
+### CLI
+
+```sh
+ipa-dlp setup
+ipa-dlp get spotify
+ipa-dlp get spotify@9.1.88
+ipa-dlp get spotify -v 9.1.88
+ipa-dlp get spotify --version 9.1.88
+ipa-dlp get com.spotify.client --version 9.1.88
+ipa-dlp get 324684580 --version 9.1.88
+ipa-dlp get spotify --version 9.1.88 -o ~/Desktop/Spotify.ipa
+```
+
+To download the raw FairPlay-encrypted IPA without decrypting (supported on
+any OS):
+
+```sh
+ipa-dlp get spotify --encrypted
+```
+
+On macOS Intel, Linux, and Windows, a plain `ipa-dlp get` exits with a clear
+message; `--encrypted` is the supported download path there. `-F` and
+`extract` work normally. The encrypted IPA still contains `SC_Info`
+licenses and account metadata, so treat it like `--keep-account-data`.
+
+The final path is printed on stdout; progress and diagnostics go to stderr.
+The default output is:
+
+```text
+~/Downloads/Spotify-9.1.88.ipa
+```
+
+Account data is stripped by default: `SC_Info` licenses are removed and the
+Apple ID/purchaser fields are scrubbed from `iTunesMetadata.plist`.
+ipa-dlp checks the decryption report and the output archive
+before printing `account data stripped: yes`; if either check fails,
+it deletes the output and exits with an error.
+
+Use `--keep-account-data` if you need the licenses for further analysis, and
+`--full` to keep the extra artifacts:
+
+```sh
+ipa-dlp get spotify --version 9.1.88 --keep-account-data
+ipa-dlp get spotify --version 9.1.88 --full
+```
+
+`--full` also keeps:
+
+```text
+Spotify-9.1.88.encrypted.ipa
+Spotify-9.1.88.report.json
+```
+
+For `ipa-dlp decrypt`, `--full` keeps the report; the encrypted input
+already exists where you put it.
+
+### Extracting the executable
+
+`--extract-binary` also writes the app's arm64 Mach-O executable next to the
+decrypted IPA, ready for a disassembler or symbol dumper:
+
+```sh
+ipa-dlp get spotify --version 9.1.88 --extract-binary
+ipa-dlp decrypt /path/to/App.ipa --extract-binary
+```
+
+```text
+~/Downloads/Spotify-9.1.88.ipa
+~/Downloads/Spotify-9.1.88.bin
+```
+
+The slice is read from the decrypted archive, so it is already FairPlay-free.
+Universal ("fat") executables are reduced to the arm64 slice (falling back to
+x86_64), written with mode `0755`, and the `.bin` path is what gets printed on
+stdout. The IPA is still written; pass `--force` to replace an existing `.bin`.
+
+### Extracting from an existing IPA, .app, or binary
+
+`ipa-dlp extract` works on files you already have and does not need an App
+Store account:
+
+```sh
+ipa-dlp extract ~/Downloads/Spotify-9.1.88.ipa        # -> Spotify-9.1.88.bin
+ipa-dlp extract ~/Applications/MyApp.app -o MyApp.bin
+ipa-dlp extract ./SomeBinary -o SomeBinary.arm64
+```
+
+For an IPA it reads `CFBundleExecutable`, checks the Mach-O encryption command,
+and extracts directly when the payload is already decrypted. If `cryptid` is
+non-zero, the command requires `SC_Info`, decrypts through UnfairPlay into a
+temporary directory on an Apple Silicon Mac (the usual model/admin rules
+apply), and extracts from that copy. A `.app` or raw Mach-O that is still encrypted cannot be decrypted
+in place; it is extracted with a warning. `-o` templates and `--exec` work as
+described below.
+
+`extract` accepts `--json` like the other commands.
+
+### Output templates and hooks
+
+`-o` on `get`, `decrypt`, and `extract`, plus `--exec` on all three, accept
+tokens expanded from the app's `Info.plist`:
+
+| Token | Value |
+| --- | --- |
+| `%(name)s` | app display name |
+| `%(bundle_id)s` | bundle identifier |
+| `%(version)s` | `CFBundleShortVersionString` |
+| `%(build)s` | `CFBundleVersion` |
+| `%(external_id)s` | Apple external version ID, when known |
+
+```sh
+ipa-dlp get spotify --version 9.1.88 \
+  -o '~/Research/spotify/%(version)s-%(build)s.ipa'
+
+ipa-dlp get spotify --version 9.1.88 --extract-binary \
+  --exec 'cp "{}" ~/Research/spotify/current.bin'
+```
+
+`--exec` runs after the artifacts are written. `{}` is replaced with the final
+artifact path — the `.bin` when `--extract-binary` is set, otherwise the
+`.ipa` — and the command runs through the shell. Expansion uses Python
+`%`-formatting, so write `%%` for a literal `%`. A failing hook exits non-zero
+after the artifacts are kept.
+
+For `extract`, tokens are read from an IPA or `.app`; a raw Mach-O only has
+`%(name)s` (its filename stem). `%(external_id)s` is empty for `decrypt` and
+`extract` because the input's version ID is not resolved.
+
+### JSON output
+
+`--json` prints a JSON object on stdout and keeps all progress and
+diagnostics on stderr, so a pipeline can parse it without stripping noise:
+
+```sh
+ipa-dlp --json get spotify --version 9.1.88 > result.json
+ipa-dlp --json get spotify --list-versions --limit 5
+ipa-dlp --json status
+```
+
+Results carry `ok`, `command`, the resolved app, `external_id`, the
+`artifact` path, `ipa`/`binary`/`encrypted_ipa` paths where relevant,
+`encrypted`, `verified`, and `account_data_stripped`. `--list-versions` returns a `versions` array. A
+failure still prints one object, `{"ok": false, "error": "..."}`, and
+exits non-zero. With `--exec`, the hook's stdout is redirected to stderr so
+the object stays alone on stdout.
+
+### Library API
+
+```python
+from ipa_dlp import download, decrypt, extract_binary, load_macho
+
+ipa = download("spotify", version="9.1.88")    # -> Path (decrypted IPA)
+raw = download("spotify", encrypted=True)       # -> Path (encrypted IPA)
+ipa = decrypt("/path/to/App.ipa", output="App.ipa")
+bin_path = extract_binary(ipa)                   # -> Path (<base>.bin)
+data = load_macho("spotify", version="9.1.88")  # -> bytes (arm64 slice)
+```
+
+Each function returns its result instead of printing it. Pass `exec_hook=` or
+`reveal=True` only when the side effects are wanted.
+
+Other commands:
+
+```sh
+ipa-dlp status
+ipa-dlp decrypt /path/to/App.ipa   # Apple Silicon Mac
+ipa-dlp extract /path/to/App.ipa
+ipa-dlp setup --update          # reinstall pinned ipatool (and UnfairPlay on Mac)
+ipa-dlp setup --reauth          # force a new Apple ID login
+ipa-dlp setup --seed spotify    # Apple Silicon Mac: create the model now
+ipa-dlp setup --seed spotify --version 9.1.88
+```
+
+### Version selection
+
+`--version` matches the IPA's `CFBundleShortVersionString`. ipa-dlp
+maps it to Apple's external version identifier by asking the App Store for
+metadata, newest versions first, and caches the mapping in
+`~/Library/Caches/ipa-dlp/versions/`. If the App Store will not serve a version to
+your account, you get an error; `--external-version-id` lets you bypass the
+lookup once you know the ID.
+
+The version can be given as `--version 9.1.88` (or `-v`), as a second
+positional (`ipa-dlp get spotify 9.1.88`), or appended to the query
+(`ipa-dlp get spotify@9.1.88`). The `@` form also works with `load_macho`.
+
+### Version history
+
+`--list-versions` (`-F`) prints the App Store's version history for an app,
+newest first, without downloading anything:
+
+```sh
+ipa-dlp get spotify --list-versions        # newest 15
+ipa-dlp get spotify -F --limit 100         # newest 100
+```
+
+The table goes to stdout:
+
+```text
+EXTERNAL_ID  VERSION  RELEASE_DATE
+871294812    9.1.88   2026-03-14
+870912300    9.1.86   2026-03-07
+```
+
+Metadata for versions that were not resolved before is fetched in parallel and
+stored in the same version cache used by `--version`, so later runs are
+instant. Pipe an `EXTERNAL_ID` into `--external-version-id` to download a
+version that is no longer listed.
+
+### Licenses and paid apps
+
+Free apps are licensed automatically when needed. For a paid app, buy it in the
+App Store first; downloading an owned paid app works without extra flags.
+`--purchase` asks Apple to obtain a missing license, which can charge your
+account, so ipa-dlp asks for confirmation before using it on a paid app.
+
+```sh
+ipa-dlp get some-paid-app --purchase
+```
+
+## On first run
+
+1. Pinned `ipatool 2.7.0` (and `UnfairPlay 0.2.0` on Apple Silicon Macs)
+   releases are downloaded and SHA-256 verified into
+   `~/.local/share/ipa-dlp/bin/`.
+2. You are prompted for your Apple ID and password in the terminal. On macOS
+   and Linux the password is fed to `ipatool` over a PTY, not as a
+   command-line argument; on Windows ipatool's `--password` flag is used for
+   that login (visible in the process list while it runs). ipa-dlp does not
+   store the password. If Apple asks for a 2FA
+   code, you are prompted for it. Pass `--gui` (macOS) to use native dialogs.
+3. `setup` checks the App Store session and reports the signed-in account.
+4. On an Apple Silicon Mac, the first `get` downloads the IPA, unpacks its app
+   bundle, and `UnfairPlay` recovers the enrollment model. You are asked for
+   your login password once (in the terminal by default, or in a macOS dialog
+   with `--gui`). The model is saved under
+   `~/Library/Application Support/unfairplay/models` and reused for later IPAs
+   from the same enrollment/account.
+5. The IPA is decrypted, account data is stripped, and the output is checked
+   against its pre-encryption page hashes before success is reported.
+
+On macOS Intel, Linux, and Windows, steps 4-5 do not apply; use
+`ipa-dlp get --encrypted` to keep the raw IPA. Later `get` calls on a Mac do
+not need the admin password.
+
+## Important limitations
+
+- **Decryption requires an Apple Silicon Mac.** UnfairPlay depends on
+  macOS's FairPlay services, so `get` without `--encrypted`, `decrypt`, and
+  `setup --seed` are unavailable on Intel Macs, Linux, and Windows. Those
+  platforms can still search, list versions, download with `--encrypted`,
+  and extract already-decrypted binaries.
+- **`--encrypted` output is still personalized.** It keeps `SC_Info`
+  licenses and account metadata, so treat it like `--keep-account-data`.
+- **UnfairPlay is build-sensitive.** It may fail closed after a macOS update if
+  Apple changes the FairPlay state or `fairplayd`. ipa-dlp reports the error.
+- **The model is tied to the Mac's enrollment and Apple ID.** If you sign in to
+  a different account, use `ipa-dlp setup --reauth`; a different enrollment
+  needs its own model.
+- **Only "store-owned" apps are supported.** If the account cannot obtain the app/version, the download fails.
+- **No App Store password is stored.** `ipatool` stores its own session token in
+  the system credential store (the macOS Keychain on Mac). Revoke it with
+  `ipatool auth revoke` if needed.
+
+## Privacy and legal use
+
+Use this only with apps and accounts you lawfully control, and follow Apple's
+terms. Decrypting an app does not grant redistribution rights. Do not share
+personalized or decrypted IPAs. The default output is stripped, but
+`--keep-account-data` and `--encrypted` output still contain your account
+licenses and metadata.
+
+The model file is private. Keep it on encrypted storage and never share it.
+
+## Development / testing
+
+Environment overrides:
+
+```sh
+IPADLP_IPATOOL=/path/to/ipatool
+IPADLP_UNFAIRPLAY=/path/to/unfairplay
+IPADLP_BIN_DIR=/tmp/ipa-dlp-bin
+IPADLP_CACHE_DIR=/tmp/ipa-dlp-cache
+IPADLP_DATA_DIR=/tmp/ipa-dlp-data
+UNFAIRPLAY_MODEL_DIR=/tmp/unfairplay-models
+```
+
+Terminal prompts are the default, which works over SSH and in scripts. Pass
+`--gui` (macOS only) to use native dialogs instead.
+
+Useful checks:
+
+```sh
+python3 -m py_compile ipa_dlp.py ipa-dlp
+ipa-dlp status
+ipa-dlp --json status
+ipa-dlp get spotify --version 9.1.88 --dry-run
+python3 -m build          # wheel + sdist (needs flit_core)
+```
+
+See [RELEASING.md](RELEASING.md) for the automated tag → PyPI → Homebrew
+pipeline and the one-time repository secrets.
+

ipa_dlp-0.3.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+ipa_dlp.py,sha256=lVw6BWIqXHDLW3mbOe9VMo621Yfqf3KxuqSSRdtVk0Q,133048
+ipa_dlp-0.3.0.dist-info/entry_points.txt,sha256=VAPH_fMh-ePQ2oNt2Lm1FdQVI1IkeA6pErt3Q6puUYA,40
+ipa_dlp-0.3.0.dist-info/licenses/LICENSE,sha256=HSWVgCD2xJ6_tP1cjGKoFQSKdKGyRifZ69nduZVXVtc,1070
+ipa_dlp-0.3.0.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
+ipa_dlp-0.3.0.dist-info/METADATA,sha256=X_9RMkZgITJFIGE3kzS9belXh-7Xz4Fmo2DhKnUrYI0,14421
+ipa_dlp-0.3.0.dist-info/RECORD,,

ipa_dlp-0.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: flit 3.12.0
+Root-Is-Purelib: true
+Tag: py3-none-any

ipa_dlp-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+ipa-dlp=ipa_dlp:main
+

ipa_dlp-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Benjamin Liou
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.