Files
DroidDeck/tools/xbox/README.md
T
Kurt Himebauch 6ed281f78d feat(xbox): install MSIXVC2 back-compat titles from their content boxes (#2851)
* feat(xbox): install MSIXVC2 packages from their encrypted content boxes

* feat(xbox): run a package's custom install actions once per prefix

* fix(xbox): launch the program a launcher menu names instead of the menu

* fix(xbox): check free space before an MSIXVC2 install starts

* fix(xbox): keep a forwarded launch path relative when the install folder is reached through a link

* fix(xbox): rebuild the MSIXVC2 patch on the final legacy install

* fix(xbox): keep a backup whose release fails, and test an interrupted restore

* fix(xbox): verify resumed msixvc2 files, contain writes, decode install action arguments

* fix(xbox): keep one completion record per msixvc2 file, never follow a linked install state

* fix(xbox): drop a torn msixvc2 completion record before appending to it

* fix(xbox): repair a torn msixvc2 record from its tail instead of rereading it
2026-11-18 16:59:45 -05:00

162 lines
11 KiB
Markdown

# 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:
```sh
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](https://github.com/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.
`droiddeck-msixvc2.patch` installs MSIXVC2 packages, the format Xbox 360 backward-compatible
titles ship in. The package Windows Update serves is only an index (`XboxPackage.cbor`, chunk and
file tables); the files are encrypted, Brotli-compressed segments inside `.box` blobs on the Xbox
content hosts. `streaming` unpacks the index, licenses its content id, derives the package key from
the content key (SP800-108 HMAC-SHA256, label `MSIXVC2:PackageData:AES_256_CBC`), unwraps each
segment key with AES-256-CBC, fetches adjacent segments in one ranged request, and checks the
SHA-384 of every stored segment, decompressed segment and finished file before it is renamed into
place. Files already complete are skipped on a retry.
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:
- Nexus backend: https://github.com/domsvoboda/nexus-backend, a fork of Xodus
https://github.com/xodus-gaming/xodus (GPL-3.0, `LICENSE.xodus`).
- Nexus launcher and runtime compatibility files: https://github.com/domsvoboda/nexus-launcher
(formerly xodus-nexus; MIT, `LICENSE.nexus`, `LICENSE.runtime-compat`).
- XGameRuntime/Wine modules: the exact source archive is identified in
`runtime.lock.json` (LGPL-2.1, `LICENSE.LGPL-2.1`).
- `libnghttp2.dll`: nghttp2, MIT; its license is retained in the runtime source
archive and is packaged as `LICENSE.nghttp2`.