alts

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

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

[Unreleased]

Added

Fixed

[1.0.0] - 2026-11-14

Migrating from 0.12

1.0.0 freezes the API, and it does so in one release: every form it replaces is removed outright, with no deprecated bridge and no transitional release in which both work. This section is the whole route from 0.12.0, name by name; the sections after it give the detail of each change.

The runtime owns its state. Nothing is process-wide any more: each AltsRuntime builds its own stores, transport and executor.

0.12 1.0
AltStore.accounts(), AltStore.addAccount(a), and every other AltStore call the same call on alts.store() (an AccountStore)
every SecretStore call the same call on alts.secrets() (a HostSecrets)
AltStore.bind, configure, keyProvider, writeDelay, and the same on SecretStore none: the builder sets the directory, file names, key bindings and key provider, and a runtime always coalesces writes (100 ms)
AltStore.DEFAULT_WRITE_DELAY none
HttpUtil (and bind), IoExecutor none: set proxyProvider and executor on the builder
AltsToasts.success, failure, info, removed alts.toasts().toast(level, title, description, durationMs) (see Removed for each mapping)
AccountServices.of(...) alts.accountServices(account) or alts.accountServices(token, uuid)
ProfileLookupService.create(...) alts.profileLookup(); another base with Builder#accountEndpoints
new SkinAvatarCache<>(...) alts.skinCache()
new UrlTemplateAvatarSource(t) passed to avatarSource Builder#avatarUrlTemplate(t)
new MojangAvatarSource(...) nothing: it is the default
new AsyncCache<>(loader, ...) new AsyncCache<>(executor, loader, ...)
new NtpTimeSource(...) new NtpTimeSource(executor, ...)
a runtime left open for the process close it (try (AltsRuntime<H> alts = ...) or alts.close()); a shutdown hook still flushes if you do not

One error model. Every failure is an AltsFailure, thrown as an AltsException where it is not part of a result. The Error kinds table below maps every former constant to its kind.

0.12 1.0
AltLoginCallback.LoginResult auth.LoginResult(account, failure)
AltLoginCallback, AltLoginCallback.FailureReason none; result.reason() becomes result.failure().map(AltsFailure::kind)
LoginResult.retryAfter(), xstsError() failure().flatMap(AltsFailure::retryAfter), failure().flatMap(AltsFailure::xstsError)
LoginResult.failure(String), failure(String, FailureReason, ...), rateLimited() LoginResult.failure(AltsFailure), LoginResult.failure(Kind, String)
AccountStatus.reason(), rateLimited(), retryAfter() AccountStatus.failure(); state() is unchanged
catch (AccountException e) and e.status(), tokenRefused(), rateLimited(), notFound(), retryAfter() catch (AltsException e) and e.kind(), e.failure().retryAfter()
SkinValidationException and its Reason SkinService.validate(bytes) returning a SkinProblem (same constants); an upload throws AltsException of kind INVALID_INPUT
CryptoException, VaultException AltsException of kind CRYPTO, INVALID_INPUT or PROTOCOL
CookieFile.read’s IOException AltsException of kind INVALID_INPUT
PlayerCertificate.privateKey(), publicKey() throwing GeneralSecurityException the same calls, throwing AltsException: INVALID_INPUT for an absent or non-Base64 PEM, CRYPTO for one that decodes to no RSA key; drop the catch (GeneralSecurityException e)
NameChangeResult and ProfileCreationResult outcomes NOT_ENTITLED, UNAUTHORIZED, RATE_LIMITED FAILED, with the kind on failure()
ClaimResult.StopReason.RATE_LIMITED, UNKNOWN; ClaimResult.rateLimited() TERMINAL_FAILURE, with the kind on failure()
new ClaimResult(claimed, attempts, finalResult), new ClaimResult(claimed, attempts, finalResult, stopReason) new ClaimResult(claimed, attempts, finalResult, stopReason, failure)
BulkEntryResult.reason() BulkEntryResult.failure()
BulkEntryResult.failure(index, label, FailureReason, message, attempts) BulkEntryResult.failure(index, label, AltsFailure, attempts)
store loadError(), saveError(), loadWarning() strings Optional<AltsFailure> of kind STORAGE

Value types that may grow are classes. Six records of 0.12 are final classes (and the new AltsFailure is one too), so a later field is an addition and not a break. Accessors, equals/hashCode over the same fields, the redacted toString where there was one, and every withX method are unchanged; the public canonical constructors are gone, and so are deconstruction patterns over them.

0.12 1.0
new AltAccount(uuid, username, accessToken, type, lastUsed, lastUsedBy, bans, sourceClient, sourceUser, refreshToken, expiresAt) AltAccount.builder(uuid, username, accessToken, type).lastUsed(..).lastUsedBy(..).bans(..).sourceClient(..).sourceUser(..).refreshToken(..).expiresAt(..).build() (each setter optional), or account.toBuilder() to change several fields; the store file format is unchanged
new MicrosoftAuthConfig(...) (thirteen or eleven arguments) MicrosoftAuthConfig.of(clientId) or legacyMsa(clientId), then withScope, withRedirectPath, withEndpoints, withDeviceCodeEndpoints, and the new withRedirectUri and withRpsTicketPrefix
new NetworkScope(purpose, uuid, username), new NetworkScope(purpose, uuid, username, routeTag) NetworkScope.of(purpose) or NetworkScope.forAccount(purpose, uuid, username), then withRouteTag(tag)
new BulkOptions(concurrency, minSpacing, maxRetries, retryBaseDelay, stopOnRateLimit) BulkOptions.of(concurrency, minSpacing, maxRetries, retryBaseDelay, stopOnRateLimit), or BulkOptions.defaults() and the withX methods; a route tag with withRouteTag(tag)
new ClaimOptions(leadTime, window, attemptSpacing, concurrency, timeSource) ClaimOptions.of(leadTime, window, attemptSpacing, concurrency, timeSource), or ClaimOptions.defaults() and withTimeSource
new BulkEntryResult(...) BulkEntryResult.success(index, account, message, attempts), success(index, account, entitlements, message, attempts) or failure(index, label, failure, attempts)

The shared vault: 0.4 to AVP 0.5. 1.0 writes AVP 0.5 only, which is not wire compatible with 0.4 and specifies no upgrade. A repository moves in five steps:

  1. Get the repository’s manifest and envelope JSON: export them while the host still runs 0.12, or fetch them from the 0.4 server with your own HTTP client, authenticating with VaultIdentity.signChallenge.
  2. Read them with LegacyVaultReader.read(manifestJson, envelopeJson, identity), which returns the accounts and writes nothing. Review them: 0.4 signed nothing, and the import has no rollback floor.
  3. The owner creates a new repository: OwnerIdentity.generate() (keep its entropy in HostSecrets, or have the owner write the phrase down), alts.vault().connectFirstContact(host) and then SharedVault.create(host, owner), and puts the accounts they choose.
  4. Each member joins again: the joiner calls SharedVault.prepareJoin with the repo locator the owner sent and returns the invite token, the owner calls invite, and the joiner calls join.
  5. Persist each copy’s VaultSnapshot (toJson(), encrypted, for example in HostSecrets) and resume with SharedVault.resume on the next run.
0.12 1.0
SharedVault’s 0.4 constructors and createRepo, openRepo, addMember, encryptPayload, decryptPayload, rotateKey, removeMember SharedVault.create, open, prepareJoin, join, resume, then accounts, update, put, removeAccount, invite, removeMember, sync and the rest
KeyBindingVerifier, IssuerSignedKeyBindingVerifier none: the owner-signed chain and invite tokens replace key binding
RepoPin, RepoContext the pin lives in VaultSnapshot
MemberPublicKey (a prospective member’s two public keys, passed to addMember, rotateKey, removeMember) none: a joiner’s keys reach the owner inside the InviteToken it returns from SharedVault.prepareJoin, and the roster lists members as VaultMembers (roster(), removeMember(member))
VaultTransport and the vault.transport DTOs none: alts.vault() speaks AVP 0.5 over the runtime’s transport
vault.federation.RepoAddress, InviteRequest, RepoLocator vault.RepoLocator, vault.InviteToken
VaultTransportResolver, Builder#vaultTransportResolver, AltsRuntime.vaultTransportResolver() alts.vault(), and Builder#vaultHostAddress to map a host locator to a URL
crypto.VaultIdentity, crypto.WrappedIdentity, crypto.RecoveryCode the same types in lol.trq.alts.vault (change the import; a stored identity still opens)
VaultIdentity.keyAgreementPrivateKey(), RecoveryCode.deriveKey none: the library unwraps inside itself
crypto.KeyWrapScheme, X25519HkdfAesGcmKeyWrap, RepoDataKey, WrappedKey, Hkdf none

Moved or removed packages. The crypto package is gone: its primitives are internal, and the identity types are in vault (above). The format package and AltManagerFormatting are removed (the code to copy is under Removed). The implementation (HttpUtil’s successor HttpTransport, FailureText, MicrosoftAuthUtil, CookieAuthUtil, AccountNetworkUtil, TokenExpiry, MinecraftProfile, the *Impl classes, EncryptionUtil, MicrosoftCallbackServer, …) is under lol.trq.alts.internal, outside the API; the table under Removed says what a host uses instead of each.

The build and the module.

Behaviour a host should know about.

Error kinds

Every former reason, outcome and exception case, and the kind it becomes. kept means the constant is still there and carries no failure of its own (FAILED and TERMINAL_FAILURE carry the failure that says the kind); none means success, so failure() is empty.

Former Kind Notes
FailureReason.NONE none  
FailureReason.UNKNOWN UNKNOWN  
FailureReason.REAUTH_REQUIRED REAUTH_REQUIRED The credential is spent and was discarded.
FailureReason.INVALID_TOKEN UNAUTHORIZED Empty, malformed or refused; a refresh token may still renew. Where nothing was sent because the input is no credential at all (an offline name that is not a name, a bulk line of no known form), INVALID_INPUT. A 403 from the Minecraft services Xbox login, which refuses the host’s client registration, is NOT_CONFIGURED.
FailureReason.NETWORK NETWORK  
FailureReason.NOT_CONFIGURED NOT_CONFIGURED A missing DeviceCodePrompt argument is INVALID_INPUT.
FailureReason.NOT_ENTITLED NOT_ENTITLED  
FailureReason.RATE_LIMITED RATE_LIMITED The wait is failure().retryAfter().
FailureReason.XBOX_DENIED XBOX_DENIED The reason is failure().xstsError().
FailureReason.DECLINED DECLINED  
FailureReason.TIMED_OUT TIMED_OUT  
AccountException.tokenRefused() UNAUTHORIZED Status 401 or 403.
AccountException.notFound() NOT_FOUND Status 404 on any call but the profile read.
AccountException.notFound() from ProfileService.fetch NOT_ENTITLED No Minecraft profile, as sign-in and check say; fetchIfPresent() is still empty.
AccountException.rateLimited() RATE_LIMITED Status 429, with its wait.
AccountException status 5xx or 408 NETWORK  
AccountException status 400 or 422 INVALID_INPUT  
AccountException status 409 CONFLICT  
AccountException another status UNKNOWN  
AccountException status 0, unreachable NETWORK CANCELLED once the runtime is closed.
AccountException status 0, unreadable answer PROTOCOL  
XstsAuthException XBOX_DENIED  
RefreshRejectedException.permanent() REAUTH_REQUIRED A stated invalid_grant only.
RefreshRejectedException.rateLimited() RATE_LIMITED  
RefreshRejectedException, an outage NETWORK Status 5xx or 408, or unreachable.
RefreshRejectedException, another refusal UNAUTHORIZED Was NETWORK; the stored token is kept.
RefreshRejectedException, invalid_client or unauthorized_client NOT_CONFIGURED The host’s client registration was refused; the token is kept.
SkinValidationException.Reason.UNREADABLE INVALID_INPUT SkinProblem.UNREADABLE
SkinValidationException.Reason.EMPTY INVALID_INPUT SkinProblem.EMPTY
SkinValidationException.Reason.TOO_LARGE INVALID_INPUT SkinProblem.TOO_LARGE
SkinValidationException.Reason.NOT_PNG INVALID_INPUT SkinProblem.NOT_PNG
SkinValidationException.Reason.WRONG_DIMENSIONS INVALID_INPUT SkinProblem.WRONG_DIMENSIONS
NameChangeResult.Outcome.CHANGED kept  
NameChangeResult.Outcome.INVALID_NAME kept  
NameChangeResult.Outcome.UNAVAILABLE kept  
NameChangeResult.Outcome.NOT_ENTITLED NOT_ENTITLED Now FAILED.
NameChangeResult.Outcome.UNAUTHORIZED UNAUTHORIZED Now FAILED.
NameChangeResult.Outcome.RATE_LIMITED RATE_LIMITED Now FAILED, with its wait.
NameChangeResult.Outcome.FAILED kept Its failure carries the kind.
ProfileCreationResult.Outcome.CREATED kept  
ProfileCreationResult.Outcome.INVALID_NAME kept  
ProfileCreationResult.Outcome.DUPLICATE kept  
ProfileCreationResult.Outcome.NOT_ALLOWED kept  
ProfileCreationResult.Outcome.NOT_ENTITLED NOT_ENTITLED Now FAILED.
ProfileCreationResult.Outcome.UNAUTHORIZED UNAUTHORIZED Now FAILED.
ProfileCreationResult.Outcome.RATE_LIMITED RATE_LIMITED Now FAILED, with its wait.
ProfileCreationResult.Outcome.FAILED kept Its failure carries the kind.
ClaimResult.StopReason.CLAIMED kept  
ClaimResult.StopReason.WINDOW_ELAPSED kept  
ClaimResult.StopReason.RATE_LIMITED RATE_LIMITED Now TERMINAL_FAILURE, with its wait.
ClaimResult.StopReason.TERMINAL_FAILURE kept Its failure carries the kind.
ClaimResult.StopReason.CANCELLED kept  
ClaimResult.StopReason.UNKNOWN UNKNOWN Now TERMINAL_FAILURE.
Store loadError(), saveError(), loadWarning() strings STORAGE  
CookieFile.read’s IOException INVALID_INPUT A sign-in from the file still reports UNAUTHORIZED.
CryptoException, a wrong passphrase or recovery code CRYPTO From VaultIdentity.unlock and unlockWithRecovery; also a tampered sealing, or stored public keys that do not match the private material.
CryptoException, a malformed stored identity INVALID_INPUT A missing or non-Base64 field, a key or sealing of the wrong length, an iteration count out of range, a missing passphrase, no recovery sealing. WrappedIdentity’s constructor reports a missing field the same way, where it threw NullPointerException.
CryptoException, another failed key operation CRYPTO Key generation, sealing, signing. A 0.4 data key that does not unwrap or a payload that does not authenticate, now from LegacyVaultReader.
VaultException PROTOCOL Only the 0.4 vault threw it; LegacyVaultReader makes the same checks and reports them as PROTOCOL.

An AuthFlowException becomes the kind of the FailureReason it carried, as in the rows above.

Added

Changed

Removed

Fixed

[0.12.0] - 2026-11-12

Device-code login, a wider account surface, a host-supplied store key, and a hardening pass over the transport, the stores, the sign-in routes and the shared vault. Several defaults changed on the way, so read the upgrade notes first.

Upgrading

Every item here is a break or a change in behaviour that a host has to act on or at least know about.

Added

Changed

Deprecated

Removed

Fixed

Security

Notes

The device-code flow and the reworked cookie sign-in chain were tested against loopback and scripted servers only. Neither has been verified against the live Microsoft services in this release, so treat both as unproven there until a host has exercised them.

What the shared vault does not protect against, and what the default store key is and is not, are stated in SECURITY.md. One limit of the proxy tunnel is stated there too: the JVM still resolves the origin host name through the local resolver.

Of the 1.0.0 design, this release ships device-code login, the bulk entitlement sweep and the removal of the deprecated profile methods. Username and password login was not built, by decision.

[0.11.1] - 2026-10-11

Fixed

[0.11.0] - 2026-08-06

The full post-login account surface — everything an account owner can do to their own account through the public Minecraft services. The bulk of the 1.0.0 design, shipped ahead of the freeze so the freeze itself, and the one sensitive route it holds back, are a decision made deliberately rather than in passing.

Added

Notes

The account services are additive — a host that does not call accountServices(...) is unaffected, and nothing in the existing surface changed shape. The one thing that turned out cleaner than the design record proposed: the full profile is a new PlayerProfile in account/ rather than a widened MinecraftProfile, so the auth chain’s result type is untouched and there is no breaking change to it.

Held back for the 1.0.0 freeze, deliberately: credential (username + password) login, which the design record flags for an explicit decision; the removal of the deprecated AccountNetworkUtil.fetchProfileFromToken; and a bulk entitlement sweep. 1.0.0 is where the surface is frozen and those are settled.

[0.10.0] - 2026-08-06

Identity that stays current — the third milestone of the alt-management surface.

Added

Changed

Fixed

[0.9.0] - 2026-08-05

Bulk operations — the second milestone of the alt-management surface.

Added

Changed

Notes

Concurrency is bounded structurally — that many worker chains pulling from one cursor — rather than by an executor, so the library still creates no threads of its own and everything runs on the common pool.

Spacing is global rather than per proxy route, which the design record called for. Per-route pacing means asking the host’s ProxyProvider which route an entry would take before making the request, and a rotating provider treats every ask as an allocation — so the library would claim two pool slots per entry and hand one back unused. Asking a provider more times than requests are made is a bug a host cannot see.

§C (identity refresh and UUID-keyed avatars) was specced for this release and held back: two of its decisions — flipping the default avatar source off the third-party service, and changing what skinCache().get() is keyed on — were put to the repository owner and are unanswered. A focused release beats one with a guess baked into it. It becomes 0.10.0, and device-code login 0.11.0.

[0.8.0] - 2026-08-05

The first milestone of the alt-management surface: requests can be routed, accounts can be operated on without being logged into, and an account that owns no Minecraft says so.

Added

Fixed

Changed

Notes

Rate-limit backoff was specced as part of this milestone and deferred to 0.9.0, where the bulk operations that drive it land. Shipping a public utility with no caller is worse than shipping it with one; what landed now is the input it needs, HttpResponse.retryAfter.

[0.7.0] - 2026-08-05

A login route, a second Microsoft dialect, and a durability pass over the local stores after a full audit of the library.

Added

Fixed

Security

Changed

[0.6.2] - 2026-07-28

Fixed

[0.6.1] - 2026-07-28

Added

[0.6.0] - 2026-07-28

Refresh tokens become a first-class credential: importable as a login route, redeemable to renew a stored session silently, and shareable into a repository only when that repository opts in.

Added

Fixed

Security

Changed

[0.5.0] - 2026-06-01

Changed

[0.4.0] - 2026-06-01

Changed

[0.3.0] - 2026-06-01

Changed

Added

[0.2.0] - 2026-06-01

Added

Changed

[0.1.0] - 2026-05-29

Added