alts

A Minecraft Java Edition account library for sign-in, account management, an encrypted store and a shared vault.

Architecture

lol.trq.alts is an account library for Minecraft: Java Edition, usable from a launcher, a tool, the host application of a bot, or an account manager. It is consumer-agnostic and holds no Minecraft or renderer types; everything platform-specific crosses a seam the host implements.

Layers

            ┌──────────────────────────────────────────────────────────────┐
  host      │  seam implementations (SessionInjector, ProxyProvider, ...)   │
            └───────────────▲──────────────────────────────────────────────┘
                            │ spi/ interfaces
            ┌───────────────┴──────────────────────────────────────────────┐
            │  AltsRuntime: wiring root + Builder, AutoCloseable            │
            │  AltsFailure / AltsException: the one error model             │
            ├───────────────────────────────────────────────────────────────┤
  API       │ spi/      the host seams: session, directory, main thread, toasts,
  (module   │           textures, avatars, stats, proxy, store key, device-code prompt
  exports)  │ auth/     login and account services, LoginResult, AccountStatus, config
            │ account/  services over a token: profile, entitlements, name, skin, cape,
            │           attributes, certificates, blocklist; public profile lookup
            │ bulk/     one operation over many accounts: options, progress, report
            │ store/    AccountStore + HostSecrets, one per runtime
            │ net/      NetworkScope, ProxyRoute: what a ProxyProvider sees
            │ time/     TimeSource, SystemTimeSource, NtpTimeSource
            │ cache/    AsyncCache<K,V>
            │ skin/     SkinAvatarCache<H>
            │ model/    AltAccount, SessionData, GameStats, BanInfo, enums
            │ vault/    VaultHosts, SharedVault, identities, tokens, snapshot,
            │           LegacyVaultReader
            ├───────────────────────────────────────────────────────────────┤
  internal  │ internal.net    HttpTransport (one per runtime), proxy tunnel, FailureText
  (not      │ internal.auth   the Microsoft, cookie and session chains; the login services
  exported) │ internal.account, internal.bulk, internal.skin   service implementations
            │ internal.store  StoreFile (the locked, atomic writer), EncryptionUtil
            │ internal.crypto Ed25519, X25519, PBKDF2, PayloadCipher
            │ internal.avp    AVP 0.5 constructions: canonical encoding, strict Ed25519,
            │                 BIP39, manifest, commit, payload, tokens
            │ internal.vault  the AVP 0.5 client engine; legacy/ the 0.4 importer
            └───────────────────────────────────────────────────────────────┘

Key pieces

Module and internal packages

The jar is the named module lol.trq.alts (src/main/java/module-info.java). It exports the twelve API packages and nothing under lol.trq.alts.internal; it requires transitive com.google.gson, because @SerializedName sits on public records (the build declares Gson as an ordinary api dependency), and requires java.desktop (the system browser, ImageIO) and jdk.httpserver (the loopback redirect). It opens exactly three packages, to Gson only, for the private records Gson builds by reflection: store (the two store files), internal.auth (the device-code response) and internal.store (AltAccountJson, the record an AltAccount is read and written through, with the same components in the same order, so no final field is set by reflection). The exported model package is not opened.

The fences around internal:

Runtime-built public types (the stores, AccountServices, ProfileLookupService, SkinAvatarCache, VaultHosts) have no public factory. Each package holds a package-private bridge (StoreBridge, AccountBridge, SkinBridge, VaultBridge) that installs itself into an internal.*Access class when the package initializes; the Access class accepts only that bridge, loaded by the library’s own class loader, and only once, and the runtime builds through it.

check runs the whole suite twice: on the class path (test) and with the jar as a named module and the tests patched into it (moduleTest), so a missing requires or opens fails there.

Threading

Store persistence

AccountStore (accounts) and HostSecrets (per-user secrets that must never enter a shared repository) are instance types, one of each per runtime, each over its own internal.store.StoreFile with its own file, key binding and lock. Neither has a public factory or close(): the runtime opens them through the store bridge and closes them when it closes.

Transport

Every HTTP request goes through the runtime’s internal.net.HttpTransport, which is what makes the rules enforceable in one place. The runtime builds one and hands it to every service through its constructor; two runtimes have two transports and share no route, tunnel or thread.

Error model

One value describes a failure everywhere: AltsFailure, a final class read through kind(), message(), retryAfter(), xstsError(), retryAt() and retryable(), and built with of(kind, message), of(kind, message, retryAfter), rateLimited(message, retryAfter) and xboxDenied(message, error) (copied with withMessage), with AltsFailure.Kind one enum for the whole library (NETWORK, RATE_LIMITED, UNAUTHORIZED, REAUTH_REQUIRED, NOT_ENTITLED, NOT_FOUND, XBOX_DENIED, DECLINED, TIMED_OUT, CANCELLED, INVALID_INPUT, CONFLICT, NOT_CONFIGURED, STORAGE, CRYPTO, PROTOCOL, UNKNOWN). It ends in UNKNOWN so a host’s default branch covers a constant a later release adds. One unchecked exception carries it, AltsException, with failure() and kind().

Three rules decide where a failure appears:

  1. An outcome the caller is expected to branch on is a result. LoginResult (sign-in), AccountStatus (check and refresh; its State is the account’s state, mapped from the kind by an exhaustive switch: RATE_LIMITED and NETWORK are UNREACHABLE, XBOX_DENIED is NOT_ENTITLED), NameChangeResult and ProfileCreationResult (their outcome constants stay, and every failure folds into FAILED), ClaimResult (a TERMINAL_FAILURE carries the failure), and BulkEntryResult. Each carries Optional<AltsFailure> failure(). These routes never throw at the caller and never complete exceptionally, even on a closed runtime.
  2. Everything else is an AltsException. The account services, the profile lookup, CookieFile.read, the vault and build() throw it, and a library future completes exceptionally only with it (inside a CompletionException), never with a transport exception or a checked one.
  3. The stores throw nothing for I/O; they report on loadError(), loadWarning() and saveError(), each an Optional<AltsFailure> of kind STORAGE.

retryable() is true for NETWORK, and for NETWORK or RATE_LIMITED once a stated wait (retryAt) has passed; a RATE_LIMITED with no stated wait is not retryable, because retrying into an unknown limit is how a short limit becomes a long one.

Messages are for people and are not a contract. A message never repeats a transport exception’s own text (internal.net.FailureText maps a failure to a fixed phrase for its kind, and the original stays reachable as the cause), never carries a token, a cookie, a code or a path, and never repeats what a service or the host’s session injector said. ErrorKindMigrationTableTest pins every 0.12 constant’s kind against the CHANGELOG’s table, and per-service loopback tests drive each failing response to its kind.

Bulk runs

bulk/ runs one operation per entry with a concurrency bound, a minimum spacing between starts, a retry budget and per-entry progress. BulkOptions.defaults() is four at a time, a quarter second apart, two retries growing from two seconds, stopping on a rate limit.

Shared vault

The vault speaks AVP 0.5 (a draft specification) as a client only. The constructions are in internal.avp, the client engine in internal.vault, and the public types in vault/ are thin handles over them.

The constructions are gated byte for byte by the AVP 0.5 vectors vendored under src/test/resources/avp-vectors/, the must-reject bank included; the 0.4 vectors the importer and the identity rest on are kept beside them. SECURITY.md states what the protocol resists and what it does not.

Design rules