Files
DroidDeck/tools/xbox
Kurt HimebauchandTimmyCraft a5d8abeab4 feat(xbox): install legacy EAppx titles through Windows Update (on main) (#2825)
* feat(xbox): install legacy EAppx titles through Windows Update

A legacy Store title does not ship as MSIXVC. It ships as an encrypted
EAppx bundle, which streaming rejects, so the store could list the game
and never install it.

Accept EAPPX and EAPPXBUNDLE beside MSIXVC, carry the format through the
catalogue, the install record and the cached library, and dispatch
legacy-install for those formats.

Two backend patches do the work:

- droiddeck-legacy-packages.patch lets the plan, license and extract
  verbs handle a legacy package, and expands a bundle in place (nesting
  bounded at three), decrypting each inner EAppx with the same keys.
- droiddeck-legacy-install.patch adds legacy-install: resolve,
  license, download, extract, hoist AppxManifest.xml to the game root.
  Resolution asks the Xbox content service first and Windows Update
  second, because some legacy products return no files from the content
  service at all. The WU endpoint needs no Xbox credential but chains to
  Microsoft's ECC Product Root CA 2018, which Android's CA bundle does
  not carry, so that one public root is pinned for those requests.

The manifest reader accepts AppxManifest.xml as well as
MicrosoftGame.config, since a legacy package carries only the former.

Running it against a real title exposed four things that only show up at
full size:

- A licence names a key by its 16-byte content id, while a bundle header
  names it as a (content id, package id) pair. Reading the 16-byte id
  yields a different pair, so a complete key file reported every key
  missing and no bundle could be opened. Keys are now aligned against
  the header's own ids before the header is judged.
- Windows Update answers with several updates whose PackageContentId
  differs from the bundle's own. Licensing used to take the first and
  fail with content-http 400; every candidate is now tried in order,
  preferring the one the container is named after.
- A container already in .xodus-container is reused rather than fetched
  again, so a failed run does not cost another download of tens of
  gigabytes. The space preflight no longer counts a container twice for
  the same reason.
- A bundle that carries add-on packages unpacks each into its own
  folder, leaving the manifest one level down. Hoisting lifts the
  largest folder that holds a manifest, so the game still lands at the
  root beside its add-ons.

Unpacking now reports bytes written, so the install bubble fills while a
package is decrypted instead of holding a single unchanging word.

* fix(xbox): unpack a legacy package across cores and report the bytes

Unpacking one title ran as a single thread on a saturated core at about
40 MB/s. Files sit at independent offsets, so each worker now opens its own
handle and takes every Nth file, with a 1 MiB read buffer in place of the
8 KiB default that turned one 64 KiB block into eight reads. Measured on the
Forza Horizon 4 bundle, writes went from 40 MB/s to about 200 MB/s.

Two things the first full-size run exposed:

- The container was deleted only after the whole nested tree was unpacked,
  so a title that holds its package as one member held the archive and the
  decrypted copy at once. On this device that runs out of space partway
  through the second stage. The container is now deleted once its members
  are on disk, which frees the archive before they are decrypted.
- A bundle member is written as a single file, so a counter that advances
  when a file finishes stays at zero for the whole of the longest stage.
  The reported figure now also follows the growth of the destination while
  that is the case, and never moves backwards when the container is freed.

Progress is exact during the per-file stage: each file's declared length is
added as it lands, instead of walking the whole destination every tick.

* docs(xbox): record the completed legacy install

The evidence section said a finished legacy install and its decrypted
contents were unverified, because the first run was still unpacking when it
was written. That install has now completed on the same device: the
85,219,173,025-byte container produced 79.3 GB at the game root with
AppxManifest.xml and the package DLLs directly beneath it, and the launcher
lists the title as installed.

It also records what unpacking costs, since that decided the change: one
thread held a core at 100% for about 40 MB/s and four reach about 200 MB/s,
and releasing each container once its members are on disk is what keeps the
peak footprint at one package rather than the archive plus its contents.

The launch is not part of this evidence, and the entry says so.

* fix(xbox): place the 64-bit framework beside a legacy title

A Windows Update framework category lists one package per architecture under
identifier-only names. The first package was unpacked, which on this device was
the x86 build, so a 64-bit title got 32-bit DLLs and every load failed with
STATUS_INVALID_IMAGE_FORMAT. Candidates are unpacked now and only the one whose
manifest declares ProcessorArchitecture="x64" is kept.

The framework folder was also never created, so a finished download failed at the
move with "no such file or directory".

unzip.rs belongs to this patch: legacy-install calls it and the recipe left it out,
so a rebuild from the pinned source could not compile.

* feat(xbox): report a UWP entry point at launch

An unpacked package can name a COM class as its entry point instead of
Windows.FullTrustApplication. That class is a UWP application, which expects the
app model to activate a view; Wine has no host for it, so the launch died inside
the loader with no explanation. The launch now reads the entry point and reports
uwp-entry-point, and full-trust packages are unaffected.

Forza Horizon 4 is such a package: its manifest names Forza.App. Its frameworks
are installed and the loader is clean before that point.

* fix(xbox): report why a launch was refused

A failed prepare replaced the backend message with a fixed sign-in hint, so a title
that was not installed or a runtime that refused all read as a bad account. The
reason is kept, with paths and URLs dropped, and written to the store log.

* fix(adb): dismiss the keyboard on Search and Go

Search and Go were terminal IME actions but were not handled, so focus stayed in
the field and the keyboard covered the results it had just fetched.

* fix(xbox): keep a cache row without a legacy format plain

Decoding added a format key with an empty value to every cached title, so a
library restored from storage no longer matched the one that was saved.

* test(ui): match the manifest message a legacy package reports

The message covers both a MicrosoftGame.config and an AppxManifest, so the
assertion follows the text the content dialog now prints.

* fix(xbox): refuse to start a title that needs the Windows app model

A legacy package that names an entry point other than
Windows.FullTrustApplication is a UWP application. Wine has no app-model
host, so starting its executable crashes inside the loader and the launch
looks like nothing happened. Read the entry point from the manifest the
installer already parses and stop the Play action with a message instead.

Forza Horizon 4 names Forza.App, so it installs and reports as installed
but cannot be started here yet.

* fix(xbox): dispatch on the container format of the chosen package

The catalogue records the format of the first installable desktop package, and
the picker only replaced the content id. An offer that lists MSIXVC and a legacy
container would then hand the legacy id to streaming, or the streamed id to
legacy-install, and the install failed after resolution had succeeded.

The choice now carries its own format and the catalogue value only fills a gap.

* fix(xbox): keep an extraction reason that the sanitizer rewrote

The extraction sanitizer replaces anything outside letters, digits, space, dot,
underscore and dash with a question mark, so a reason such as "(os error 28)"
arrived as "?os error 28?" and the allowlist dropped the line. The failure then
showed only the stage code, with no cause.

Add that replacement character to the class the allowlist accepts.

* fix(xbox): print the reason a launch was refused

The account channel sends a reason with a refusal, and the guest replaced it
with a fixed sign-in message, so a title that was never installed still read as
a bad account. The guest now shows the reason it was given, and a token holding
a path is dropped whole instead of having its slashes removed and its directory
names kept.

* build(xbox): leave RUST_TEST_THREADS unset when the host has no value

The recipe always passed the variable, empty when the host had none, and the
pinned test harness rejects an empty count. On an ARM64 host that runs cargo
test, so the default local build failed before compiling.

* fix(xbox): rebuild the backend patches from the tree that ran

The two patches in this branch were not the ones the verified install ran, and
one of them did not compile. `unzip.rs` inflates deflated entries but the
dependency that provides the inflater was never added, so `prepare.py` produced
a tree that failed at `flate2::read::DeflateDecoder`. Anything else missing fell
into the same gap: the install stage reported no bytes, so the bar held one
value for the whole unpack, and a container a stopped run had finished was
downloaded again.

Rebuilt from the patched source, and fixed the defects a review of the patch
found:

- Unpacking reports bytes again: the workers count each file's declared length,
  and for the single-file bundle member the folder's growth stands in, which is
  what the device run showed.
- A finished container is reused, so a retry after a failure past the download
  does not spend hours fetching it again. The space preflight counts it as
  reclaimable, since the retry truncates it first.
- An install over a folder that already has a manifest replaces the old files
  instead of leaving the new package nested and reporting success. A first
  install still refuses to merge into an existing target.
- The manifest search looks at the depth a nested bundle writes, not only one
  level down.
- `withdraw_libraries` removes only the DLLs `copy_libraries` recorded copying,
  so a framework replacement cannot delete a library the title owns.
- ZIP64 sizes and offsets stay `u64`; truncating them to `u32` read the wrong
  local header past 4 GiB.
- The extraction checks the blockmap length against the footer's before writing,
  which the crate only does when asked.
- The container being unpacked is never treated as a nested member, so
  `extract-eappx title.eappx .` no longer re-enters and deletes its own input.
- `flate2` is declared and the lock is updated.

`prepare.py` reproduces this from a pristine checkout and `cargo test` passes on
it.

* fix(xbox): apply the legacy install patch over the Nexus 0.2.15 backend

* fix(xbox): install only the newest x64 build of a legacy title and size the space check at its real peak

* fix(xbox): install a store package that is a plain archive instead of an XVD

* fix(xbox): refuse a package entry that ends before its recorded size

* fix(xbox): credit only complete staged containers toward the free space a legacy install needs

* fix(xbox): bound each package entry to its data and check ZIP64 decoded sizes

* fix(xbox): refuse duplicate package names and clear an unfinished download before measuring space

* fix(xbox): bound package entries by the next header and stage a plain package until it validates

* fix(xbox): hold the install folder lock through a legacy install

* fix(xbox): fall back to an older build when Microsoft refuses the newest one a license

* fix(xbox): keep the registered device across sign-out

* feat(xbox): explain device-limit and license refusals, with a link to manage devices

* fix(xbox): locate each build only once licensed, roll back a failed package swap, report the final license answer

* fix(xbox): skip trial and preorder packages, read runtime behavior, keep licensing timeouts

* fix(xbox): keep a failed package swap recoverable, size bundles up front, report key-write and framework errors cleanly

* fix(xbox): drop a pending manifest check on any newer launch, keep committed backups out of restores, match the app-model order

* fix(xbox): cancel pending launch checks on a new intent, remember entries a rollback could not remove

* fix(xbox): clear the removal list before a restore moves old files back

---------

Co-authored-by: TimmyCraft <46533729+TimmyTurner51@users.noreply.github.com>
2026-11-18 14:14:26 -05:00
..

Xbox backend for DroidDeck

DroidDeck uses the Nexus backend protocol with a native Linux AArch64 CLI and service. It does not install the Nexus desktop launcher or x86 Linux Wine. backend.lock.json pins the Nexus backend (domsvoboda/nexus-backend, a fork of Xodus that carries Nexus's changes as commits), its Xodus base, Rust and the Cargo.lock checksum. runtime.lock.json pins the Nexus Windows runtime release (domsvoboda/nexus-runtime) and each extracted PE DLL. prepare.py verifies the source revision and Cargo.lock before applying the local transport, launch and library patches.

droiddeck-cloud-token.patch adds xodus-cli cloud-token: the stored account's Xbox Cloud Gaming sign-in (XSTS for http://gssv.xboxlive.com/, then the streaming service's /v2/login/user) and the login proof token a session's /connect step takes. It prints one JSON object and never opens a login or provisions a device. Ported from Bannerlator.

droiddeck-library-subscriptions.patch queries fresh subscription membership alongside product entitlements using the same Store session, account and market. Android can validate a Game Pass child's parent plan when that plan is absent from the product response. A failed membership query fails the refresh and preserves the previous library. Empty membership results add no plan evidence; valid plans already present in the product response retain their existing checks.

Build on AArch64 Ubuntu 24.04 with Rust from the lock, a C/C++ compiler, OpenSSL development headers, pkg-config, protoc, CMake, Git, Python 3 and xz:

bash tools/xbox/build.sh

On macOS, bash tools/xbox/build-local.sh uses an AArch64 Ubuntu container. tools/build_local.sh includes this step and caches it by recipe inputs. CI builds the same recipe on ubuntu-24.04-arm and transfers the result to the APK job. Cache hits still download that build's Xbox artifact before APK assembly. The build runs account-free CLI, credential and streaming tests. It retains the patched backend source archive and the checksum-verified runtime source archive in the build cache and publishes both in CI's xbox-corresponding-source artifact; distribute corresponding sources with published binaries.

droiddeck-credential-fallback.patch names the reason when the backend cannot reach the app's credential socket (NEXUS_CREDENTIAL_ERROR_V1 socket-refused, -denied, ...) and then uses a keyed loopback port the app also listens on; some devices refuse the abstract socket from inside PRoot. The key is passed in the backend's environment only.

droiddeck-licensing-device-ticket.patch sends a delegation-compact device ticket to content licensing in the licensing wire form (t= or a bare compact JWE), as user tickets already are; a plain compact device ticket is sent unchanged. Store license tokens already do this in nexus-backend 0.2.15 (@domsvoboda's commit 27c335e); the content licensing path does not yet (xodus-gaming/xodus#238).

droiddeck-dlc-mount.patch: the C++ XGameRuntime mounts downloadable content only inside a host-owned workspace named by XODUS_MOUNT_ROOT. DroidDeck starts Wine itself, so the droiddeck:prepare session creates that workspace in its launch directory, reports it as mountRoot, and removes it when the session ends; droiddeck-xbox passes it to the game.

droiddeck-credential-diagnostics.patch names the step behind a credential-io failure: the session lock (lock-dir-owner, lock-file-mode, lock-flock-<reason>, ...), a socket or loopback exchange that broke after connecting (socket-exchange-<reason>), a malformed host reply, or a missing socket name, port or key. Errno values without a name are spelled with letters, a = 0 ... j = 9.

droiddeck-credentials.patch replaces Linux Secret Service with a bounded, Android abstract socket restricted to the backend process started by the host. The Android host encrypts every persistent write using its existing Keystore cipher, verifies backend read-backs, and rejects writes when Keystore is unavailable. No token values enter process arguments, external storage, application logs or a plaintext credential file. Account-generation invalidation prevents a signed-out child's later writes from restoring credentials. Each backend gets its own socket. The host checks the peer UID, the PRoot tracer owned by its live child, and an executable mapping of the backend file with a matching inode and SHA-256 against the APK asset. PRoot's loader can occupy /proc/<pid>/exe, so authentication checks the mapped backend image instead. A socket name alone grants no credential operations, including to another copy of Xodus started by the guest.

Licensed launch-view preparation runs in an Android-owned Xodus child, which never starts Wine or a game. Steam and DroidDeck launch paths can request preparation for an installed Xbox title during a live session with an Xbox account. The reply contains a random launch lease, a materialized executable path, a game-service socket and the existing PlayFab game token; it contains no account credential endpoint. Leases bind product, account and session, expire without heartbeats, and release idempotently. Cancellation, session stop and account changes revoke leases; closing the child's stdin lets it remove its private view. Suspension preserves live leases. The Proton initialization and game processes do not inherit the raw credential channel or command-file environment variables. The authenticated GDK bridge remains available to the game. Like the other stores, games share DroidDeck's Linux environment and Android UID. The process checks close the direct credential-socket route; they do not isolate writable runtime files, prevent same-UID process tampering, or provide a sandbox against malicious games.

Microsoft sign-in uses Nexus's private stdio protocol in an isolated Android WebView process. Its page bridge is restricted to the allowed Microsoft/Xbox HTTPS origins and the main frame; it has no credential-store or launcher API. Cookies and page storage are cleared for each attempt. This protocol requires an embedded host for CloudExperienceHost messages; opening its URL in an ordinary Android browser does not complete it. Passkey behavior needs device testing.

droiddeck-launch-view.patch materializes all licensed encrypted images, including DLLs, in a private temporary directory. Original package files remain encrypted, and the temporary view is removed after the Wine child exits. Wine receives normal files with no Xodus FD-map requirement. This costs temporary storage proportional to the encrypted images. The app keeps the account service alive for the session; an authenticated loopback bridge carries GDK requests. Wine's builtin PE marker makes WINEDLLOVERRIDES=n reject the Nexus modules. The extractor verifies their original hashes, then changes only that 16-byte DOS stub marker to DroidDeck native; code, imports and exports stay unchanged. This lets ARM64EC Wine load the AMD64 modules through its normal native DLL path. Only each Xbox game's prefix receives these Windows modules. Existing Steam games and other store prefixes retain their selected runtimes.

droiddeck-legacy-packages.patch lets the plan, license and extract verbs handle a legacy package. A bundle is expanded in place, nesting is bounded at three, and each inner EAppx container is decrypted with the same content keys; inner files without an EAppx header are left as extracted. streaming still serves MSIXVC only.

droiddeck-legacy-install.patch adds xodus-cli legacy-install: resolve, license, download, extract, hoist. Resolution asks the Xbox content service first and Windows Update (fe3cr.delivery.mp.microsoft.com, SOAP) second, because some legacy products return no files from the content service. The WU endpoint needs no Xbox credential but chains to Microsoft's ECC Product Root CA 2018, which Android's CA bundle does not carry, so that one public root is pinned in wu-root.pem for these requests. Only .eappx/.eappxbundle files from a WU result are kept; the .appx framework packages and .cab metadata beside them are dropped. Licensing runs before the first byte and must return content keys. Free space is checked against the download plus two copies of the largest container, and each container is deleted once unpacked. The download has no control channel: cancelling kills it and the next attempt starts that container from zero.

Cloud saves and in-game identity use the reused XGameRuntime/service interfaces; those are game-dependent. Entitlements distinguish purchases from Game Pass access, and the backend performs a fresh license check for downloads and launch. The store lists PC packages it can install: streamed MSIXVC, and the legacy EAppx bundles older desktop titles still ship as. It does not emulate Xbox consoles or host UWP titles in a packaged-app host. Update / verify refreshes an installed package through the normal licensed streaming path. Manage content resolves manifest-related licensed PC DLC into separate content roots and checks its parent identity after download. These flows still require game/account validation; runtime API presence does not establish that they work on Thor.

Upstream contribution restrictions are respected: these are launcher, storage, build and file-lifecycle adapters in DroidDeck, not submitted reverse-engineering contributions to Xodus.

Sources and licenses: