Relevant source files

The following files were used as context for generating this wiki page: - [pkg/appstore/appstore.go](https://github.com/majd/ipatool/blob/main/pkg/appstore/appstore.go) - [pkg/appstore/app.go](https://github.com/majd/ipatool/blob/main/pkg/appstore/app.go) - [pkg/appstore/appstore_download.go](https://github.com/majd/ipatool/blob/main/pkg/appstore/appstore_download.go) - [pkg/appstore/appstore_purchase.go](https://github.com/majd/ipatool/blob/main/pkg/appstore/appstore_purchase.go) - [pkg/appstore/appstore_list_versions.go](https://github.com/majd/ipatool/blob/main/pkg/appstore/appstore_list_versions.go) - [pkg/appstore/appstore_get_version_metadata.go](https://github.com/majd/ipatool/blob/main/pkg/appstore/appstore_get_version_metadata.go) - [pkg/appstore/appstore_replicate_sinf.go](https://github.com/majd/ipatool/blob/main/pkg/appstore/appstore_replicate_sinf.go) - [pkg/http/client.go](https://github.com/majd/ipatool/blob/main/pkg/http/client.go)

# App Store Client Design The App Store Client is the core engine of the `ipatool` project, designed to facilitate interaction with Apple's private iTunes and App Store APIs. Its primary purpose is to abstract the complexities of Apple's proprietary protocols, allowing users to search for applications, manage licenses (purchases), and download encrypted IPA packages directly from Apple's servers. The system is built around a central `AppStore` interface that orchestrates various sub-services, including authentication, machine authorization (GUID generation), and package patching. By leveraging a specialized HTTP client capable of handling Apple's specific XML Plist formats and document envelopes, the client ensures reliable communication with the Store's backend services across different regions and storefronts. Sources: [pkg/appstore/appstore.go:9-33](), [README.md:1-15]() ## Core Architecture and Components The architecture follows a modular approach where the main `appstore` struct acts as a controller, delegating specific network tasks to multiple instances of a generic HTTP client. Each client instance is configured to handle a specific response type, such as `loginResult` or `downloadResult`. ### Component Responsibilities | Component | Responsibility | Relevant Files | | :--- | :--- | :--- | | **AppStore Interface** | Defines the high-level API for commands (Login, Search, Download, etc.). | `pkg/appstore/appstore.go` | | **HTTP Client** | Handles low-level network communication, XML/JSON unmarshaling, and Cookie management. | `pkg/http/client.go` | | **Machine Service** | Provides hardware-specific identifiers (MAC address) used for GUID generation. | `pkg/appstore/appstore_download.go` | | **Keychain Service** | Manages persistent storage of account credentials and session tokens. | `pkg/appstore/appstore.go` | Sources: [pkg/appstore/appstore.go:35-45](), [pkg/http/client.go:27-32]() ### System Structure Diagram This diagram illustrates the relationship between the `AppStore` controller and its dependencies. ```mermaid classDiagram class AppStore { <> +Login(LoginInput) +Search(SearchInput) +Purchase(PurchaseInput) +Download(DownloadInput) } class appstore { -keychain Keychain -loginClient Client -purchaseClient Client -downloadClient Client -machine Machine -os OperatingSystem } class Client { +Send(Request) +Do(*http.Request) } AppStore <|.. appstore appstore --> Client : uses appstore --> Keychain : persists ``` The `appstore` implementation relies on dependency injection for its internal clients and utilities, facilitating easier testing and modularity. Sources: [pkg/appstore/appstore.go:35-55]() ## App Search and Metadata Retrieval The client provides functionality to discover apps via search terms or direct lookups using Bundle Identifiers. It also handles the retrieval of version history, which is critical for downloading specific older versions of an application. ### Data Model: App Entity The `App` struct serves as the primary data transfer object for application information. ```go type App struct { ID int64 `json:"trackId,omitempty"` BundleID string `json:"bundleId,omitempty"` Name string `json:"trackName,omitempty"` Version string `json:"version,omitempty"` Price float64 `json:"price,omitempty"` } ``` Sources: [pkg/appstore/app.go:7-13]() ### Versioning Logic When retrieving versions, the client communicates with the download endpoint to extract `softwareVersionExternalIdentifiers` from the item metadata. This allows the tool to map human-readable version strings to the internal IDs required by Apple's download servers. Sources: [pkg/appstore/appstore_list_versions.go:53-65](), [pkg/appstore/appstore_get_version_metadata.go:56-61]() ## Download and Patching Pipeline The download process is a multi-stage pipeline that involves machine authorization, binary retrieval, and package post-processing to ensure the resulting IPA is valid for the user's account. ### Download Workflow 1. **GUID Generation**: The client retrieves the machine's MAC address and formats it as a GUID. 2. **Download Request**: A POST request is sent to the private App Store API containing the app ID and machine GUID. 3. **Binary Stream**: The client initiates a `GET` request to the URL provided in the response, supporting range headers for resumed downloads. 4. **Patching**: Once downloaded, the client injects `iTunesMetadata.plist` (containing account info) and replicates SINF files into the package. ```mermaid flowchart TD A[Start Download] --> B[Get MAC Address] B --> C[Generate GUID] C --> D[Request Download URL] D --> E{License Found?} E -- No --> F[Return ErrLicenseRequired] E -- Yes --> G[Stream Binary to .tmp] G --> H[Apply Patches] H --> I[Write iTunesMetadata.plist] I --> J[Replicate SINF Files] J --> K[Rename to .ipa] ``` Sources: [pkg/appstore/appstore_download.go:28-86](), [pkg/appstore/appstore_replicate_sinf.go:31-72]() ## Purchase and Licensing IPATool only supports "purchasing" free apps to obtain a valid license for the user's Apple ID. The client implements a retry mechanism specifically for Apple Arcade or region-specific variations. ### Purchase Retries If a standard purchase fails with a `FailureTypeTemporarilyUnavailable` error, the client attempts the purchase again using the `PricingParameterAppleArcade` ("GAME") parameter to ensure maximum compatibility. Sources: [pkg/appstore/appstore_purchase.go:35-45]() ### API Request Parameters | Parameter | Type | Description | | :--- | :--- | :--- | | `salableAdamId` | int64 | The unique ID of the application (Track ID). | | `guid` | string | Hardware-bound identifier for the current machine. | | `pricingParameters` | string | Determines the store type (e.g., "STDQ" for App Store, "GAME" for Arcade). | | `X-Token` | string | The Password Token (DSID-based) used for authentication. | Sources: [pkg/appstore/appstore_purchase.go:102-126]() ## HTTP Protocol Handling Apple's APIs use a non-standard XML Plist format often wrapped in custom document envelopes. The `http.Client` includes a normalization layer to handle these cases. ### XML Normalization The client uses regular expressions to strip away ``, ``, and `` tags to isolate the core `` content before unmarshaling. This ensures compatibility with various legacy and modern response formats from Apple's servers. ```go func normalizeXMLPlistBody(body []byte) []byte { normalized := bytes.TrimSpace(body) // ... extraction logic ... if bytes.Contains(normalized, []byte("")) { return []byte("" + string(normalized) + "") } return normalized } ``` Sources: [pkg/http/client.go:148-185]() ## Conclusion The App Store Client Design effectively bridges the gap between standard CLI operations and Apple's complex, proprietary ecosystem. By encapsulating machine authorization, specialized HTTP parsing, and automated package patching, it provides a seamless interface for managing iOS applications outside of the standard App Store interface.