Add apk downloader project based on aurora's core

Docker all in one

README.md

@@ -53,6 +53,104 @@ Please only download the latest stable releases from one of these sources:
 
 You can also get latest debug builds signed with AOSP test keys for testing latest changes from our [GitLab Package Registry](https://gitlab.com/AuroraOSS/AuroraStore/-/packages/24103616).
 
+## Headless APK Downloader
+
+This repository includes a JVM CLI module for downloading the latest available APK files for a Google Play package name. Build the compiled distribution once:
+
+```bash
+./gradlew :apk-downloader:installDist
+```
+
+Then run the generated launcher directly, without Gradle:
+
+```bash
+./apk-downloader/build/install/apk-downloader/bin/apk-downloader org.mozilla.firefox
+```
+
+By default, files are saved under `./downloads/<packageName>/<versionCode>/`. To choose a different output directory:
+
+```bash
+./apk-downloader/build/install/apk-downloader/bin/apk-downloader org.mozilla.firefox --out ./downloads
+```
+
+When Google Play returns multiple APK files, the downloader keeps the verified raw files and also writes a split APK archive next to them:
+
+```text
+downloads/<packageName>/<versionCode>/
+  base.apk
+  config_*.apk
+  <packageName>_<versionCode>.apks
+```
+
+This `.apks` file is a zip archive of the downloaded base/split APKs for split-aware installers. It is not a true universal APK. Bundletool can create a universal APK from an Android App Bundle (`.aab`) with `build-apks --mode=universal`, but Google Play download delivery provides APK files here, not the original `.aab`, so bundletool cannot merge these split APKs back into one universal APK.
+
+To create a portable archive:
+
+```bash
+./gradlew :apk-downloader:distZip
+```
+
+The archive is written to `apk-downloader/build/distributions/apk-downloader.zip`. Unzip it anywhere with Java 17+ installed and run `bin/apk-downloader`.
+
+For development, you can still run through Gradle:
+
+```bash
+./gradlew :apk-downloader:run --args="org.mozilla.firefox"
+```
+
+You can also build a Docker image for the downloader:
+
+```bash
+docker build -f apk-downloader/Dockerfile -t aurora-apk-downloader .
+docker run --rm \
+  -v "$PWD/downloads:/downloads" \
+  -v "$HOME/.config/aurora-apk-downloader:/root/.config/aurora-apk-downloader" \
+  aurora-apk-downloader \
+  com.nestle.tr.nescafe.nescafe3in1loyaltyapp --country TR --out /downloads
+```
+
+If your Proton VPN runs in a separate VPN container, run the downloader with that container's network namespace, for example `--network container:<vpn-container-name>`.
+
+The image also includes an exec-friendly wrapper that takes the country first, then the package name. Start a reusable container and run downloads with `docker exec`:
+
+```bash
+docker run -d --name aurora-apk-downloader \
+  -v "$PWD/downloads:/downloads" \
+  -v "$HOME/.config/aurora-apk-downloader:/root/.config/aurora-apk-downloader" \
+  --entrypoint sleep \
+  aurora-apk-downloader infinity
+
+docker exec aurora-apk-downloader \
+  download-apk TR com.nestle.tr.nescafe.nescafe3in1loyaltyapp
+```
+
+To run Proton VPN inside Docker instead of on the host, use the bundled Compose file. Copy the example environment file, fill in your Proton WireGuard values, then start the reusable downloader stack:
+
+```bash
+cp apk-downloader/proton.env.example apk-downloader/proton.env
+# edit apk-downloader/proton.env
+docker compose \
+  --env-file apk-downloader/proton.env \
+  -f apk-downloader/docker-compose.proton.yml \
+  up -d --build
+
+docker compose \
+  --env-file apk-downloader/proton.env \
+  -f apk-downloader/docker-compose.proton.yml \
+  exec downloader download-apk TR com.nestle.tr.nescafe.nescafe3in1loyaltyapp
+```
+
+If `APK_COUNTRY` and `APK_PACKAGE` are set in the env file, you can use those defaults instead:
+
+```bash
+docker compose \
+  --env-file apk-downloader/proton.env \
+  -f apk-downloader/docker-compose.proton.yml \
+  exec downloader sh -lc 'download-apk "$APK_COUNTRY" "$APK_PACKAGE"'
+```
+
+For Proton WireGuard, set `WIREGUARD_PRIVATE_KEY` and `WIREGUARD_ADDRESSES` from a Proton VPN WireGuard config. For OpenVPN, set `VPN_TYPE=openvpn` and use Proton's OpenVPN/IKEv2 username and password in `OPENVPN_USER` and `OPENVPN_PASSWORD`.
+
 ## Certificate Fingerprints
 
 - SHA1: 94:42:75:D7:59:8B:C0:3E:48:85:06:06:42:25:A7:19:90:A2:22:02