Fallback providers

Google Play is the preferred source for stock APKs, but it is not always available: anonymous access is rate-limited and frequently blocked from datacenter IP ranges, and old versions get removed. Fallback providers keep a build working in those cases without weakening verification.

Fixed order

google-play → direct → archive → apkmirror → uptodown

The order is fixed in code, not configurable. Which providers are actually attempted depends on which [apps.fallbacks] entries you declared; an empty table means Google Play is the only source. See configuration.md.

When fallback advances, and when it stops

This is the most important rule in the chain.

Outcome	Behavior
Provider unreachable, rate-limited, or authentication unavailable	Advance to the next provider.
Requested version not offered by this provider	Advance to the next provider.
Downloaded file fails any verification	Stop the entire chain.

Verification failures are terminal: size limits, ZIP or manifest parsing, package identity, version, architecture, required splits, signature validity, and pinned signer. A later provider is never allowed to satisfy a request that already failed verification, because that would turn "this file is wrong" into "keep looking until something passes", which is exactly how a malicious mirror wins.

Availability failures exit with code 3 when the chain is exhausted. Integrity failures exit with code 5.

Provider types

direct

An explicit HTTPS APK asset URL. Nothing is resolved; the URL is fetched as given. Use this for a self-hosted or otherwise stable mirror.

archive

An explicit archive.org/download/... APK asset URL. Useful for historical versions that Google Play no longer serves.

apkmirror

Accepts either an explicit asset URL or an APKMirror catalog page. A catalog page is resolved through:

catalog → release → architecture variant → download page → asset

Configured and intermediate URLs must stay on an APKMirror host. The final delivery redirect may additionally use APKMirror's Cloudflare R2 host. Any other host fails closed.

.apkm bundles are extracted to recover the split set, but only after archive safety checks pass.

uptodown

Accepts either an explicit asset URL or an Uptodown catalog page, resolved through:

catalog → version → architecture variant → download page → asset

Uptodown pages and the final delivery host must stay on Uptodown throughout. .xapk bundles are extracted after the same archive safety checks.

Resolution fails closed when a provider offers no unique variant for the requested architecture, rather than picking one arbitrarily.

Untrusted metadata

Mirror-supplied descriptions, filenames, sizes, version labels, and any other remote metadata are treated as untrusted hints. They may steer which asset is downloaded; they never establish what the file is.

Each download goes into a unique temporary directory under enforced file-count and size limits, its SHA-256 is computed, and it then passes the same APK verification used for Google Play deliveries before anything is published. Original downloads are never modified in place. See google-play-integrity.md.

Catalog resolution parses third-party HTML, so it will break when a site redesigns. That is a maintenance cost, not a security hole: a broken parse fails the resolution instead of downloading something unverified.

Provenance

Fallback provenance records, per download:

• provider name
• sanitized source URL, with query string and fragment removed
• downloaded size and SHA-256
• requested identity (package, version, architecture)
• APK metadata independently re-derived from the file

It never records URL credentials, query tokens, or authenticated URLs.