missuo/unfairplay-bot

This project is a self-hosted service for people who need signed, time-limited download links to App Store builds their own Apple ID has lawfully purchased. It combines a Telegram bot restricted to private chats with a token-protected HTTP API. You send an app_id, bundle_id, or App Store link; the service downloads the current build with ipatool and decrypts it with UnfairPlay, then produces a temporary download URL.

What actually changes

The useful shift is that you stop handling ipatool and UnfairPlay by hand. A confirmation-first Telegram flow shows the app name, version, size, price, and whether that build is already cached before anything is queued. The request only proceeds after the user taps ✅ within 10 minutes. Long-running work is visible: queue position, a download bar with speed and ETA, then decryption, then a download button. One live message per task keeps the chat uncluttered, and users can cancel their own tasks.

How the cache and progress work

Each request asks the App Store for the latest external version ID first, so a new release is not missed when the lookup API lags. The cache key is trackId:externalVersionId; requests by bundle_id and app_id for the same app share it. That means a cache hit only applies to the build currently served, and a version bump forces a fresh download on the next request. Artifacts expire 24 hours after their most recent hit, and issued links remain valid only until that artifact expiry. Progress can be followed over Server-Sent Events or by polling the task endpoint API and deployment details.

Access and privacy conditions

Everyone other than an admin needs to be allowlisted. Admins receive access requests with allow/ignore buttons, and admins can also manage the list with /allow, /revoke, and /users. The bot answers only in private chats, needs no public webhook, and uses long polling. Decryption runs with --strip-account-data, leaving out SC_Info licenses and Apple ID/purchaser fields from iTunesMetadata.plist; the service checks each IPA again and refuses to start if UnfairPlay lacks that flag. The README is explicit that this is for apps your account lawfully acquired and that the decrypted IPAs and links are private.

Requirements to plan for

• Two separate credentials. You need an UnfairPlay model file created by unfairplay setup on an enrolled Mac, plus an ipatool App Store session. The model can be copied to another machine; the session cannot and must be recreated on the server. Both must belong to the same Apple ID.
• Docker Compose or systemd. The Compose path needs Docker and a reverse proxy with TLS. The systemd path avoids Docker but needs Go (per go.mod or newer), gcc, git, and Caddy. The Linux build requires cgo, so building from macOS by cross-compiling is not supported.
• A stable container identity. The Compose file pins the container MAC address because ipatool derives the device GUID from it; changing it after login breaks that session.
• Paid apps. A paid app the account does not own returns 403 license_required.
• Real-world validation is limited. Public CI cannot exercise actual downloads or decryption because they need the private session and model; the operator-side canary check is the documented gate for those project README. The project is Apache-2.0 licensed, and the bundled ipatool and UnfairPlay keep their own licenses license.

HotRepo's take

The only recorded HotRepo observation is a NEW-REPOSITORY board entry from 2026-10-29 showing 101 total stars at #3. That is not a daily growth measure, and there is insufficient comparable history to judge whether the interest is lasting.