alts

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

Security Policy

Supported versions

The latest released version on the main branch receives security updates.

Reporting a vulnerability

Please report security vulnerabilities privately via GitHub Security Advisories rather than opening a public issue.

We aim to acknowledge reports within 72 hours and to ship a fix or mitigation as quickly as the severity warrants.

Do not disclose the issue publicly until a fix has been released.

Scope notes

This library handles Minecraft account credentials. The on-disk stores are encrypted with AES-256-GCM under a PBKDF2-derived key. What that encryption is worth depends on where the key comes from: the default key is derived from machine properties and is obfuscation against casual copying, while a key the host supplies through StoreKeyProvider gives real protection for a copied file. The threat model below states both. The library sends credentials only to the identity and Minecraft services a sign-in or an account operation addresses, over the route the host configured. API keys for optional integrations are supplied by the host through a seam and are never held or persisted by the library.

Threat model

This section states what each layer does and does not protect against, so that nobody trusts it for more than it gives.

The local stores (AccountStore, HostSecrets)

Each AltsRuntime owns one AccountStore and one HostSecrets, each an encrypted file in the directory the host named, with its own key binding, its own key and its own lock. Nothing about them is process-wide: two runtimes in one process, on two directories, never see each other’s accounts, secrets or keys.

The default key. With no StoreKeyProvider, the PBKDF2 password is derived from machine properties: the OS user name, the OS name, the home directory, and a constant that is public in this source. None of those is secret. The default key keeps credentials out of plaintext on disk and defeats casual copying: a file lifted from a backup or a synced folder does not open as it is on another machine. It is obfuscation, not protection, against anyone who knows or can guess those values, because they can derive the same key anywhere. It does not protect against an attacker who can already run code as the same user on the same machine.

A host-supplied key. A host that needs the stores to resist a copied file installs a StoreKeyProvider that returns real key material, for example an entry in the operating system’s credential store or a key derived from a passphrase the user types. With a provider installed:

Migration. Files written before the provider was installed are sealed under the machine-derived key. They load under a provider only when the host sets migrateFromMachineKey(true). That launch loads the old store, rewrites it under the host’s key, and reseals or removes the rolling backup and every unreadable copy, so that no file left in the directory opens under the old key. The opt-in is meant for the one launch that adopts the provider. While it is on, the machine-derived key is still accepted, so anyone able to write the store directory can plant a store sealed under it, or put back a copy from before the migration, and have it load. Turn it off afterwards.

What a host key does not cover. The strength of the stores is the strength of the key material and of wherever the host keeps it. The key and the decrypted accounts are held in process memory while the library runs. An attacker running code as the same user can usually reach whatever the provider reaches. A user who wants more should use full-disk or per-user encryption underneath.

Integrity of the files.

The transport and proxies

Every HTTP request the library makes goes through one transport, which the runtime builds for itself and hands to every service; two runtimes share no transport, tunnel or thread. It applies these rules:

Limits a host relying on a proxy for privacy should know:

Tokens in logs and messages

The limit: the original exception stays reachable as the cause of a failure, for a host that wants to log it deliberately. A host that logs full cause chains takes on whatever the JDK put in them. The library also cannot redact what a host reads from an accessor (account.accessToken()) and logs itself.

Interactive sign-in

The device-code flow and the cookie chain were tested against loopback and scripted servers, not against the live services.

The shared vault (AVP 0.5)

The vault implements the Alt Vault Protocol 0.5, whose specification is still labelled draft, as a client; the protocol’s own threat model (THREATMODEL.md in that repository) is the reference, and this section states what this client adds or chooses. Payloads are encrypted on the client and the data key is wrapped to each member’s X25519 key, so a host stores and relays only ciphertext, wrapped keys, public keys, counters, ids and signatures. Every host is untrusted for confidentiality and integrity, the member’s own home host included, and trusted only for availability.

What it resists.

Design choice: a forged state fails the operation. A host that serves a state failing a check of the specification’s manifest rules, or a chain that does not contain the pin and does not win the tie rule (a rollback), fails the whole operation with PROTOCOL, and the pull that met it adopts nothing of what the host served: the chain, the pin, the heads and the accounts stay as that pull found them. This deviates from the reference client, which keeps the valid prefix of what a host served and goes on from there. Failing closed means a lying host cannot choose the point, within the chain it served, to which a device advances; the cost is availability, since one bad state stops that host’s syncs until it stops serving it. A head the client cannot read is left alone and counted, not fatal.

A relayed challenge on first contact. Discovery is unauthenticated (SPEC 11.7). A client that reaches a host by its locator alone, with no key from a token, a manifest or a snapshot, takes whatever key the answer names. An impostor at that address can name host A’s key, fetch a challenge nonce from A for the member, and relay it; the client signs A’s transcript, and the impostor redeems it at A for a bearer token in the member’s name. The domain separation keeps that signature from serving anything but A’s sign-in, the token cache never hands A’s token to another address, and the client never sends the impostor a cached token, a secret or a plaintext; but the impostor holds a token for A, with which it can pull ciphertext as the member there until it expires. This is inherent to SPEC 3.3 and 11.7 without an authenticated channel or a known key. The library narrows it by reaching a locator over HTTPS by default and by passing the known key on every connection that has one: use connect(HostRef), connect(locator, key), connect(RepoLocator) or connect(VaultSnapshot) once the key is known, and connectFirstContact only for a true first contact, comparing the key it reports out of band.

Secrets the host stores. VaultSnapshot holds the retained data keys of every epoch the member could read, and the owner’s entropy() is the owner key. Both are secrets: persist them encrypted, in HostSecrets for example, which is what the examples do, and never in plain configuration. A member’s VaultIdentity is stored as its passphrase-wrapped WrappedIdentity. A lost owner phrase cannot be recovered by the library.

What it still does not cover.

Refresh-token sharing is effectively irreversible. Removing a member re-keys future commits, but a refresh token already on a member’s disk can only be revoked at the identity provider.

The 0.4 importer. LegacyVaultReader reads one 0.4 repository with a member’s identity, for carrying its accounts into a new 0.5 repository. It is read-only: it never writes and never talks to a host. It proves nothing 0.4 did not: nothing in a 0.4 repository is signed, so a 0.4 host that lied could have substituted keys or served an older payload before the import, and the import has no rollback floor, being one read with no earlier state to compare. Review the accounts before writing them into the new repository.

Jar sealing and the module

The implementation lives under lol.trq.alts.internal. On the module path that package is closed: the module does not export it, and code outside the library cannot read it. On the class path a module descriptor restricts nothing, so public classes under internal stay callable there; they are outside the API and outside every guarantee here, and the internal bridges the runtime uses to build its stores and services can be called by class-path code too. What the class path cannot do is join the library’s packages: the jar is sealed, so a class from another jar cannot be loaded into one of them to reach package-private members, and the bridges accept only the library’s own implementation, loaded by the library’s own class loader, so no code can substitute one and see a key provider or a store the library did not open.

Scope of reports

These are described in more detail in docs/GETTING_STARTED.md and docs/ARCHITECTURE.md. Reports that a guarantee above does not hold, or that a stated gap is wider than described, are in scope; reports that the stated gaps exist are not, since they are stated here.

Out of scope. How a consuming application acquires the accounts it feeds this library, and whether that use complies with any service’s terms, is that application’s responsibility; see DISCLAIMER.md.