Class AccountStore

java.lang.Object
lol.trq.alts.store.AccountStore

public final class AccountStore extends Object
One runtime's saved Minecraft accounts, persisted encrypted in one file on local disk. A host reaches it through AltsRuntime#store(); every runtime has its own, so two runtimes in one process never see each other's accounts.

The default key is derived from values that are not secret (the OS user, OS name and home directory), so it deters casual copying and nothing more; a host that needs real protection supplies its own key through a StoreKeyProvider.

This store holds accounts only. Accounts may be shared into a multi-member repository, so a user's own secrets (API keys and the like) live separately in HostSecrets and never travel with the accounts.

One carve-out: an account's OAuth refreshToken is a credential and it does sit on the AltAccount record, because renewal has to work for a shared alt too — otherwise every member except whoever added it watches the alt die when its access token lapses. It is therefore not covered by the rule above, and is governed instead by the repository's sharing policy: a repository withholds refresh tokens unless its manifest opts in, and the strip runs on both write and read (see SharedVault). A purely local account is unaffected — its refresh token never leaves this file.

Every mutator here is atomic with respect to the others and to a save, and a save replaces the file in one step, so neither a concurrent login nor a crash can leave a half-written store. A write that fails is reported on saveError(); nothing here throws at a caller for an I/O failure.

The store holds an exclusive lock on a sidecar <file>.lock in its directory for the life of the runtime that owns it, so a second runtime on the same file, in this process or another, is refused when it builds rather than discovered later as a corrupt file. Once the runtime is closed the mutators still change the list in memory but write nothing: each records "the store is closed" on saveError() instead.

Since:
1.0.0
  • Method Details

    • markBanned

      public void markBanned(String uuid, String serverId, BanInfo ban)
      Records a locally-observed ban for the account with uuid on serverId and persists it. Updates the stored list entry and the current account when they match; a no-op if the UUID is unknown. Other servers' ban entries on the account are preserved.
      Parameters:
      uuid - the dashed UUID of the banned account
      serverId - the server the ban was observed on (a host-supplied id; use a fallback such as "unknown" when the server cannot be identified)
      ban - the observed ban record
      Since:
      1.0.0
    • accounts

      public List<AltAccount> accounts()
      Returns the list of all accounts currently held in memory. The list is copy-on-write, so a host may iterate it from its render thread while a login resolving on a background thread mutates it; the iteration sees a snapshot rather than failing.
      Returns:
      the live list of accounts
      Since:
      1.0.0
    • loadError

      public Optional<AltsFailure> loadError()
      Returns why the last load() could not read an existing store file, if it could not.

      A store that fails to decrypt is not an empty store, and the two must not be confused: the default key is derived from machine properties, so a renamed OS user or a moved home directory turns a perfectly good file into an unreadable one. While this is set, a host should tell the user their accounts did not load instead of showing an empty list.

      While this is set nothing is written: every mutation, save() and flush() is refused and reported on saveError(), so the file on disk stays exactly as it was. Accounts added in the meantime live in memory only. Writes resume after one of three things:

      • a later load() succeeds, for example once a locked keychain behind a StoreKeyProvider answers again; what was added in memory is replaced by what it read;
      • the file is gone, so there is nothing left to protect;
      • the host calls discardUnreadable(), the route when the file will never open again: a renamed OS user or a moved home directory under the machine-derived key, or a rotated host key. The next write then starts a new store from what memory holds.

      A file that failed to decrypt, held contents that are not a store, or could not be read is copied aside as <name>.unreadable.<time> when the load fails, one copy per distinct file, newest five kept. A file that failed only because the key was unavailable is intact and is not copied until it is discarded. A successful write after a discard clears this, since the file on disk is then the one just written.

      Its message is the file's name and a fixed phrase. It never carries a filesystem path, so it is safe to show and to log.

      Returns:
      the failure, of kind AltsFailure.Kind.STORAGE, or empty when the last load succeeded or found no file, or the store has been written successfully since
      Since:
      1.0.0
    • loadWarning

      public Optional<AltsFailure> loadWarning()
      Returns a note about entries the last successful load() had to leave out. A stored entry with no UUID cannot be addressed by anything here, and a second entry for a UUID already read is a duplicate; both are skipped so that one bad record does not cost the rest. Unlike loadError() this does not mean the store failed to load — every valid account is in accounts().
      Returns:
      the note, as a failure of kind AltsFailure.Kind.STORAGE, or empty when the last load skipped nothing
      Since:
      1.0.0
    • saveError

      public Optional<AltsFailure> saveError()
      Returns why the most recent write did not reach the disk, if it did not. While this is set the file is whatever the last successful write left — never a partial one — and the accounts in memory are ahead of it; the write is retried by the next mutation, save(), or flush(), and a success clears this. Like loadError(), the message carries no filesystem path.

      Two failures are not retried by writing: while the last load() failed on a file that exists, writes are refused on purpose until a load() succeeds or the host calls discardUnreadable() (see loadError()); and once the runtime is closed nothing is written at all.

      Returns:
      the failure, of kind AltsFailure.Kind.STORAGE, or empty when the last write succeeded
      Since:
      1.0.0
    • currentAccount

      public Optional<AltAccount> currentAccount()
      Returns the currently active account, if any.
      Returns:
      an optional holding the active account, or empty if none is set
      Since:
      1.0.0
    • useAccount

      public void useAccount(AltAccount account)
      Marks account as the active account, stamping it as used now. If the store holds an entry with the same UUID, that entry's last-used time is refreshed and persisted.

      Only the timestamp of the stored entry changes. Its credentials are deliberately left alone: a caller restoring an earlier current account holds a copy read before some renewal rotated its tokens, and writing that copy back would put a spent refresh token on disk. Credentials reach the store through addAccount(AltAccount) and updateCredentials(AltAccount) only.

      Parameters:
      account - the account to make current, or null to clear
      Since:
      1.0.0
    • updateCredentials

      public void updateCredentials(AltAccount account)
      Replaces the stored entry for account's UUID with the given record and persists. Called after a renewal so the rotated refresh token survives a restart; without it the next process start would replay a token the authentication service has already invalidated.

      Silently does nothing when the UUID is not already stored, and that is deliberate, not an oversight. Accounts reach the login service from places this file is not meant to mirror — a shared repository, or a one-off LoginMode.DIRECT login the user explicitly declined to save — and writing them here would persist credentials the user chose to keep out of the store, which is a worse failure than not persisting them. The rotated credential is never lost either way: it is returned on LoginResult.account(), and for an account the store does not hold it is the host's job to put it wherever that account actually lives.

      Parameters:
      account - the account carrying freshly issued credentials
      Since:
      1.0.0
    • clearRefreshToken

      public void clearRefreshToken(String uuid)
      Discards the refresh token and expiry for the account with uuid and persists. Called when the authentication service permanently rejects the token, so a spent credential is not retried or left at rest. A no-op if the UUID is unknown.
      Parameters:
      uuid - the dashed UUID of the account whose refresh token is spent
      Since:
      1.0.0
    • addAccount

      public void addAccount(AltAccount account)
      Adds an account to storage, then saves. When an entry with the same UUID is already stored the incoming credentials are merged onto it (see AltAccount.mergedOnto(AltAccount)) rather than replacing it, so re-authenticating an alt the user already saved refreshes its tokens without discarding the observed bans, provenance, and shared attribution the store had accumulated.

      The merge happens in place and in one step: the entry keeps its position in accounts(), a reader never sees the account missing, and two logins adding the same account at once leave one entry rather than two.

      Parameters:
      account - the account to add or update
      Since:
      1.0.0
    • removeAccount

      public void removeAccount(AltAccount account)
      Removes the stored account with the same UUID and saves. Keyed on the UUID like every other mutator here, so a caller holding a stale copy — one read before a renewal rotated its tokens — still removes the right entry.
      Parameters:
      account - the account to remove
      Since:
      1.0.0
    • save

      public void save()
      Encrypts the current accounts and writes them to disk before returning, whatever write delay the store was opened with. The mutators here persist on their own; this is for a host that edited accounts() directly.

      The file is replaced in one step, so it is always either the previous state or this one. A failure is reported on saveError() rather than thrown.

      Does not write at all while the last load() failed on a file that exists — see loadError(). Persisting there would write an empty store over accounts that are merely unreadable, which is worse than not persisting at all.

      Since:
      1.0.0
    • discardUnreadable

      public boolean discardUnreadable()
      Gives up on a store file the last load() could not read, so the store can be written again. This is the route when the file will never open: under the machine-derived key, after the OS user was renamed or the home directory moved; under a StoreKeyProvider, after the host key was rotated or lost. Only the host can know that, so nothing here does it on its own.

      The file is first copied aside as <name>.unreadable.<time> (a copy of the same bytes that already exists is not made twice), the refusal is lifted, and what memory holds is written as a new store at once. A no-op when writes are not refused.

      Returns:
      true when writes were refused and are allowed again; false when there was nothing to discard, the runtime is closed, or the file could not be copied aside, which saveError() then reports and which leaves the refusal in place
      Since:
      1.0.0
    • flush

      public void flush()
      Writes any state still waiting on the write delay and returns once it is on disk. A no-op when nothing is waiting. Worth calling before a host exits by a route that skips shutdown hooks; a normal exit flushes on its own, and closing the runtime flushes too.
      Since:
      1.0.0
    • load

      public void load()
      Loads and decrypts accounts from disk into memory, replacing what memory held in one step: a reader of accounts() on another thread sees the old list or the new one, never an empty one in between. A file that holds no accounts, an empty one included, leaves the list empty. A file that exists but cannot be read leaves the in-memory list alone and records the reason on loadError(). Entries that cannot be used are skipped and noted on loadWarning(). Once the runtime is closed nothing is read, and loadError() says so.
      Since:
      1.0.0