App Source Catalog Tool

On this page you can generate a custom app source catalog for a given .ipa, as well as verify a custom app source for syntax and correctness.



Use sample .ipa: Clip | Delta | Provenance | iGoat | Cloud Cuckoo


The specified IPA URL will be analyzed and processed and the resulting catalog JSON will be generated into the text area below.



Use sample source: AltStore | Flycast | UTM | Fairapps





The catalog JSON will be parsed and validated, and then posted to the verification service. The service with fetch and analyze the binary artifact at the downloadURL to ensure that the catalog's entry is valid.





Web API Usage

You can also use this API directly using the curl command.

To generate a source catalog from a local .ipa file:

curl -fSL -X POST -F file=@MyApp.ipa https://fairtool.herokuapp.com/source/create

To generate the source from a remote .ipa URL, and save it to a sources.json file, you can run:

curl -fSL -O sources.json -X POST -F url=https://github.com/Cloud-Cuckoo/App/releases/latest/download/Cloud-Cuckoo-iOS.ipa https://fairtool.herokuapp.com/source/create

This can be useful as part of a workflow that builds and deploys an app on a service like GitHub.

To validate a local or remote catalog, you can pipe the JSON through to a request to the source/verify/APPID endpoint:

curl -fsSL https://apps.altstore.io/ | curl -fSL --header "Content-Type: application/json" --data @- https://fairtool.herokuapp.com/source/verify/com.rileytestut.Clip.Beta


Local CLI Usage

Building and running the fairtool command locally is recommended for frequent usage and is the only way to create or verify catalogs with multiple apps. In addition, the web service has limitations on throughput and upload size (100mb), which do not apply when running locally.

Homebrew users on macOS and Linux (and Windows via WSL) can run the fairtool command locally with the command:

brew install fair-ground/tool/fairtool
fairtool source create https://cdn.altstore.io/file/altstore/apps/clip/1_0.ipa
fairtool source verify --bundle-id com.rileytestut.Clip.Beta https://apps.altstore.io/

The fairtool command can be used as part of a continuous deploy process (e.g., using GitHub Actions to build releases) to generate and publish a catalog every time an app release is created.

Post-processing

The generated catalog JSON contains various placeholder text for the properties that it cannot infer from analyzing the artifact. Some defaults can be specified from the command line (such as the "--catalog-idenfifier" flag), but not all properties can be overridden. For example, the default description will be represented with a defaut placeholder value: "localizedDescription" : "DESCRIPTION", which won't be very useful for a user wanting to learn about an app.

You can manually post-process the catalog JSON using the jq, which is a general-purpose JSON query and manipulation tool.

For example, to replace the localizedDescription of the first app in a generated catalog, you could run:

fairtool source create MyApp.ipa | jq '.apps[0].localizedDescription="A short and clear description of the app."'

Swift Module

The source creation and verification code is implemented as a Swift Module as part of the fair-ground Fair package. See the documentation for AppCatalogAPI for a high-level interface to creating and validating app catalogs.


App Source Catalog Format

The app source “catalog” is a JSON file that lists the apps available in the catalog. It is fully described at https://appfair.net/#app-source-catalog.


Powered by fairtool 0.5.2.