goopdl 1.0.0__tar.gz

goopdl-1.0.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2021 Rehmat Alam
+Copyright (c) 2025 Mikel Villota
+
+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.

goopdl-1.0.0/PKG-INFO

@@ -0,0 +1,381 @@
+Metadata-Version: 2.4
+Name: goopdl
+Version: 1.0.0
+Summary: Download APKs from Google Play Store with anonymous authentication
+Author-email: Mikel Villota <mikelvillotatic@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Villoh/goopdl
+Project-URL: Repository, https://github.com/Villoh/goopdl
+Project-URL: Issues, https://github.com/Villoh/goopdl/issues
+Keywords: google-play,apk,downloader,android
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.9.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: httpx>=0.27.0
+Dynamic: license-file
+
+# goopdl
+
+Download APKs from Google Play Store using anonymous authentication. Downloads base APKs, split APKs (App Bundles), OBB expansion files, and Play Asset Delivery packs — all by default.
+
+> **Hard fork.** Independent project, hard-forked from [appknox/gplaydl](https://github.com/appknox/gplaydl), itself a fork of [rehmatworks/gplaydl](https://github.com/rehmatworks/gplaydl). MIT licensed, upstream copyright preserved.
+
+## Install
+
+```bash
+pip install goopdl
+```
+
+## Features
+
+- Anonymous authentication via Aurora Store's token dispenser (no Google account needed)
+- Optional Google account AAS token retrieval without credential or token files
+- Multiple device profiles with automatic rotation for reliable token acquisition
+- Downloads base APK, split APKs, OBB files, and asset packs in one go
+- Streaming gzip decompression for Play Asset Delivery packs
+- Beautiful terminal UI with real-time download progress bars
+- Architecture support: ARM64 (modern phones) and ARMv7 (older phones)
+- Custom token dispenser URL support
+- Search and browse app details from the command line
+- Find the latest available version by sampling multiple fresh GSF IDs
+
+## Deployment / Integration
+
+For servers, Docker images, or any environment that uses `pip` directly:
+
+```bash
+pip install git+https://github.com/Villoh/goopdl.git
+```
+
+In a **Dockerfile**:
+
+```dockerfile
+RUN pip3 install git+https://github.com/Villoh/goopdl.git
+```
+
+To pin to a specific release tag or commit (recommended for production):
+
+```dockerfile
+RUN pip3 install git+https://github.com/Villoh/goopdl.git@v2.0.0
+# or by commit SHA:
+RUN pip3 install git+https://github.com/Villoh/goopdl.git@46d0b1f
+```
+
+In a **`requirements.txt`**:
+
+```
+git+https://github.com/Villoh/goopdl.git
+```
+
+---
+
+## Installation
+
+**Requirements:** Python 3.9+, [uv](https://github.com/astral-sh/uv)
+
+Or install from source:
+
+```bash
+git clone https://github.com/Villoh/goopdl.git
+cd goopdl
+uv sync
+uv pip install .
+```
+
+## Quick Start
+
+```bash
+# 1. Get an auth token (automatic, anonymous)
+uv run goopdl auth
+
+# 2. Download an app (base APK only)
+uv run goopdl download com.whatsapp
+```
+
+All commands below use `uv run goopdl ...`. If you activate the virtual environment (`source .venv/bin/activate`) you can drop the `uv run` prefix.
+
+## Commands
+
+### `auth` — Acquire an authentication token
+
+```bash
+goopdl auth                                   # Default (arm64)
+goopdl auth --arch armv7                      # Token for older ARM devices
+goopdl auth -d https://my-server/api          # Use a custom dispenser
+goopdl auth --clear                           # Remove all cached tokens
+goopdl auth --country IN                      # Register device with India MCC/MNC
+goopdl auth --proxy socks5://host:1080        # Route dispenser call through proxy
+goopdl auth --profile "Galaxy S25 Ultra"      # Use a specific device profile
+```
+
+| Flag | Short | Default | Description |
+| ------ | ------- | --------- | ------------- |
+| `--arch` | | `arm64` | Architecture: `arm64` or `armv7` |
+| `--dispenser` | `-d` | Aurora Store | Custom token dispenser URL |
+| `--clear` | | `false` | Remove all cached tokens |
+| `--country` | `-c` | — | 2-letter country code; registers device with that region's MCC/MNC |
+| `--proxy` | `-p` | — | Proxy URL for dispenser calls (e.g. `socks5://host:port`) |
+| `--profile` | | — | Device profile key or name substring (e.g. `Pv` or `Samsung`). Run `goopdl profiles` to list all |
+
+Tokens are cached at `~/.config/goopdl/auth-{arch}.json` and reused automatically by other commands.
+
+#### Direct Google account authentication
+
+Set both environment variables to bypass Aurora's dispenser and authenticate directly with Google:
+
+```bash
+export GOOPDL_ACCOUNT_EMAIL="account@example.com"
+export GOOPDL_AAS_TOKEN="your-aas-token"
+goopdl download com.whatsapp
+```
+
+No CLI flags, config files, or secret files are used. The AAS token is a persistent sensitive credential; changing the Google account password invalidates it. Temporary Google Play bearer tokens are kept in memory and never cached. If only one variable is configured, goopdl fails without falling back to anonymous authentication.
+
+---
+
+### `aastoken` — Print a Google account AAS token
+
+#### Password or app-password mode
+
+```bash
+# Interactive: asks for email and hides password input
+goopdl aastoken
+
+# Arguments: convenient, but password remains in shell history
+goopdl aastoken user@example.com password
+```
+
+Google commonly rejects both account passwords and 16-character app passwords with `BadAuthentication`. Keep 2-Step Verification enabled and use OAuth mode instead.
+
+#### OAuth mode (recommended)
+
+```bash
+goopdl aastoken --oauth
+```
+
+Get the required one-time `oauth_token`:
+
+1. Open [Google EmbeddedSetup](https://accounts.google.com/EmbeddedSetup).
+2. Sign in and select **I agree**.
+3. The page may remain frozen/loading forever. This is expected; the cookie is normally already available.
+4. Open browser developer tools (`F12`).
+5. In Chrome or Edge, open **Application → Cookies → `https://accounts.google.com`**.
+6. Copy the value of the `oauth_token` cookie. It starts with `oauth2_4/`.
+7. Run `goopdl aastoken --oauth`, enter the same email, then paste the token. Both inputs are handled interactively and the token is hidden.
+
+The `oauth_token` is short-lived and single-use. The resulting AAS token is printed to the console. Credentials and tokens are used in memory only; no `credentials.txt` or `token.txt` files are created.
+
+---
+
+### `latest` — Find the latest available version
+
+Probes multiple fresh GSF IDs (Google Services Framework IDs) from the token dispenser. Because Google stages rollouts by device cohort (tied to the GSF ID), sampling many IDs and taking the maximum version gives the most accurate latest version available.
+
+```bash
+goopdl latest com.instagram.android
+goopdl latest com.instagram.android --stable 5
+goopdl latest com.instagram.android --profile "Galaxy S25 Ultra"
+goopdl latest com.instagram.android --country IN
+goopdl latest com.instagram.android --proxy socks5://host:1080
+goopdl latest com.instagram.android -s 4 -c US -p socks5://host:1080
+```
+
+| Flag | Short | Default | Description |
+| ------ | ------- | --------- | ------------- |
+| `--stable` | `-s` | `3` | Stop early when the highest version code is unchanged for this many consecutive probes |
+| `--profile` | | top-ranked | Device profile for all probes (e.g. `Galaxy S25 Ultra`). Defaults to the highest SDK + Vending version profile |
+| `--country` | `-c` | — | 2-letter country code sent with FDFE requests |
+| `--dispenser` | `-d` | Aurora Store | Custom token dispenser URL |
+| `--proxy` | `-p` | — | Proxy URL for dispenser + FDFE calls (e.g. `socks5://host:port`) |
+| `--arch` | | `arm64` | Architecture for token acquisition |
+
+**How the pool works:** The tool maintains a regional pool of 5 GSF ID / token pairs on disk (`~/.config/goopdl/token-pool-{arch}-{country}.json`). Before every `latest` or `download` call, it checks how many valid (unexpired) tokens exist in that region's pool and fetches only the deficit from Aurora's dispenser — so if the pool is already full, zero dispenser calls are made. Tokens are valid for 50 minutes. If a token dies mid-request (HTTP 401), it is automatically replaced in the pool.
+
+**How convergence works:** After each probe, if the best version code seen so far hasn't increased for `--stable` consecutive probes, the command stops early.
+
+**Output:** A table with each probe's GSF ID prefix, version string, and version code. The highest version code is highlighted and printed as the final result with its version code.
+
+---
+
+### `download` — Download APKs
+
+By default, `download` fetches the base APK, all split APKs, and any additional files (OBB expansion files, Play Asset Delivery packs).
+
+```bash
+goopdl download com.whatsapp                          # Everything (base + splits + extras)
+goopdl download com.whatsapp -o ./apks                # Custom output directory
+goopdl download com.whatsapp -a armv7                 # ARMv7 build
+goopdl download com.whatsapp -v 231205015             # Specific version code
+goopdl download com.instagram.android -v 434.0.0.44.74  # Specific version string
+goopdl download com.whatsapp --no-splits              # Skip split APKs
+goopdl download com.whatsapp --no-extras              # Skip OBB / asset packs
+goopdl download com.whatsapp -d https://...           # Use custom dispenser
+goopdl download com.whatsapp --country IN             # Country header for regional variant
+goopdl download com.whatsapp --proxy socks5://host:1080  # Route through proxy
+goopdl download com.whatsapp --profile "Galaxy S25 Ultra"  # Specific device profile
+```
+
+| Flag | Short | Default | Description |
+| ------ | ------- | --------- | ------------- |
+| `--output` | `-o` | `.` (current dir) | Output directory |
+| `--arch` | `-a` | `arm64` | Architecture: `arm64` or `armv7` |
+| `--version` | `-v` | latest | Version code (e.g. `384009971`) **or** version string (e.g. `434.0.0.44.74`). When a version string is given, the tool probes fresh GSF IDs until it finds a cohort that sees that version |
+| `--dispenser` | `-d` | Aurora Store | Custom token dispenser URL |
+| `--no-splits` | | `false` | Skip downloading split APKs |
+| `--no-extras` | | `false` | Skip downloading OBB files and asset packs |
+| `--country` | `-c` | — | 2-letter country code (e.g. `IN`, `US`). Combine with `--proxy` for true regional APK variants |
+| `--proxy` | `-p` | — | Proxy URL for FDFE calls (e.g. `socks5://host:port` or `http://host:port`) |
+| `--profile` | | — | Device profile key or name substring (e.g. `D2` or `Samsung`). Run `goopdl profiles` to list all |
+
+**Output files:**
+
+| Type | Naming | Example |
+| ------ | -------- | --------- |
+| Base APK | `{package}-{vc}.apk` | `com.whatsapp-231205015.apk` |
+| Split APK | `{package}-{vc}-{split}.apk` | `com.whatsapp-231205015-config.arm64_v8a.apk` |
+| OBB (main/patch) | `{type}.{vc}.{package}.obb` | `main.20925.com.tencent.ig.obb` |
+| Asset pack | `{package}-{vc}-asset.apk` | `com.tencent.ig-20925-asset.apk` |
+
+Split APKs can be installed to a device with:
+
+```bash
+adb install-multiple *.apk
+```
+
+---
+
+### `info` — Show app details
+
+```bash
+goopdl info com.whatsapp
+goopdl info com.whatsapp --country IN
+goopdl info com.whatsapp --proxy socks5://host:1080
+goopdl info com.whatsapp --profile "Galaxy S25 Ultra"
+```
+
+| Flag | Short | Default | Description |
+| ------ | ------- | --------- | ------------- |
+| `--arch` | | `arm64` | Architecture for token |
+| `--dispenser` | `-d` | Aurora Store | Custom token dispenser URL |
+| `--country` | `-c` | — | 2-letter country code; sets `gl=` and locale headers |
+| `--proxy` | `-p` | — | Proxy URL for FDFE calls |
+| `--profile` | | — | Device profile key or name substring |
+
+Displays app name, version, developer, rating, download count, and Play Store URL.
+
+---
+
+### `search` — Search for apps
+
+```bash
+goopdl search "whatsapp"
+goopdl search "file manager" --limit 5
+goopdl search "whatsapp" --country IN
+```
+
+| Flag | Short | Default | Description |
+| ------ | ------- | --------- | ------------- |
+| `--limit` | `-l` | `10` | Max results |
+| `--arch` | | `arm64` | Architecture for token |
+| `--dispenser` | `-d` | Aurora Store | Custom token dispenser URL |
+| `--country` | `-c` | — | 2-letter country code for regional results |
+| `--proxy` | `-p` | — | Proxy URL for FDFE calls |
+| `--profile` | | — | Device profile key or name substring |
+
+---
+
+### `list-splits` — List available split APKs
+
+```bash
+goopdl list-splits com.whatsapp
+```
+
+| Flag | Short | Default | Description |
+|------|-------|---------|-------------|
+| `--arch` | | `arm64` | Architecture for token |
+| `--dispenser` | `-d` | Aurora Store | Custom token dispenser URL |
+
+Shows all split APK names (config splits, language splits, etc.) without downloading.
+
+---
+
+### `profiles` — List device profiles
+
+```bash
+goopdl profiles           # All profiles
+goopdl profiles --arch arm64   # ARM64 only
+goopdl profiles --arch armv7   # ARMv7 only
+```
+
+Use the **Key** column value with `--profile` in any command.
+
+## Running without installing globally
+
+After `uv sync`, you can also invoke via the module directly:
+
+```bash
+uv run python -m goopdl auth
+uv run python -m goopdl download com.whatsapp
+```
+
+## How It Works
+
+1. **Authentication** — Gets an anonymous token from Aurora Store's dispenser, rotating through device profiles for reliability
+2. **Details** — Fetches app metadata (version, size, splits) via Google Play's protobuf API
+3. **Purchase** — "Purchases" the free app to get download authorization
+4. **Delivery** — Gets download URLs for the base APK, split APKs, OBB files, and asset packs
+5. **Download** — Streams all files in parallel from Google Play CDN with progress tracking
+
+## Finding the Latest Version
+
+Google stages app rollouts by device cohort, which is determined by the GSF ID (Google Services Framework ID) — a device registration number assigned during token acquisition. Different GSF IDs may see different active versions (e.g. 434 vs 435 for the same app).
+
+The `latest` command exploits this by sampling multiple fresh GSF IDs and reporting the highest version code seen:
+
+```bash
+goopdl latest com.instagram.android --probes 10 --stable 3
+```
+
+- Each probe fetches a fresh token → fresh GSF ID → queries Play Store for that cohort's version
+- Probing stops early once the max version has been stable for `--stable` consecutive probes
+- The device profile (`--profile`) affects which SDK level is presented; higher SDK profiles tend to receive new versions first
+
+## Token Dispenser
+
+The tool uses [Aurora Store's](https://auroraoss.com/) public token dispenser by default (`https://auroraoss.com/api/auth`). This service provides anonymous Google Play authentication tokens — no personal Google account required.
+
+You can point to a custom/self-hosted dispenser with the `--dispenser` / `-d` flag on any command:
+
+```bash
+goopdl auth -d https://my-dispenser.example.com/api/auth
+goopdl download com.whatsapp -d https://my-dispenser.example.com/api/auth
+```
+
+## Device Profiles
+
+The tool includes multiple device profiles, used to authenticate with Google Play's token dispenser. Profiles are rotated automatically during token acquisition to maximise compatibility.
+
+Run `goopdl profiles` to see all available profiles and their keys. Use `--profile` with any command to pin a specific device.
+
+Profiles are stored as `.properties` files in the `goopdl/profiles/` directory.
+
+## Architecture Support
+
+| Flag | ABI | Devices |
+|------|-----|---------|
+| `arm64` (default) | arm64-v8a | Modern phones (2017+) |
+| `armv7` | armeabi-v7a | Older 32-bit phones |
+
+### Verified integrity manifest
+
+`download --integrity-manifest PATH` fails unless every requested base/split APK has
+Google delivery size and digest metadata. SHA-256 is preferred; SHA-1 is used only
+when SHA-256 is absent. Files are verified before atomic publication, then manifest
+is written atomically with relative filename, size, algorithm, and Base64url digest.
+Manifest never contains download URLs, cookies, headers, or auth tokens.