Class AccountStore
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 Summary
Modifier and TypeMethodDescriptionaccounts()Returns the list of all accounts currently held in memory.voidaddAccount(AltAccount account) Adds an account to storage, then saves.voidclearRefreshToken(String uuid) Discards the refresh token and expiry for the account withuuidand persists.Returns the currently active account, if any.booleanGives up on a store file the lastload()could not read, so the store can be written again.voidflush()Writes any state still waiting on the write delay and returns once it is on disk.voidload()Loads and decrypts accounts from disk into memory, replacing what memory held in one step: a reader ofaccounts()on another thread sees the old list or the new one, never an empty one in between.Returns why the lastload()could not read an existing store file, if it could not.Returns a note about entries the last successfulload()had to leave out.voidmarkBanned(String uuid, String serverId, BanInfo ban) Records a locally-observed ban for the account withuuidonserverIdand persists it.voidremoveAccount(AltAccount account) Removes the stored account with the same UUID and saves.voidsave()Encrypts the current accounts and writes them to disk before returning, whatever write delay the store was opened with.Returns why the most recent write did not reach the disk, if it did not.voidupdateCredentials(AltAccount account) Replaces the stored entry foraccount's UUID with the given record and persists.voiduseAccount(AltAccount account) Marksaccountas the active account, stamping it as used now.
-
Method Details
-
markBanned
Records a locally-observed ban for the account withuuidonserverIdand 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 accountserverId- 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
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
Returns why the lastload()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()andflush()is refused and reported onsaveError(), 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 aStoreKeyProvideranswers 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
- a later
-
loadWarning
Returns a note about entries the last successfulload()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. UnlikeloadError()this does not mean the store failed to load — every valid account is inaccounts().- Returns:
- the note, as a failure of kind
AltsFailure.Kind.STORAGE, or empty when the last load skipped nothing - Since:
- 1.0.0
-
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(), orflush(), and a success clears this. LikeloadError(), 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 aload()succeeds or the host callsdiscardUnreadable()(seeloadError()); 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
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
Marksaccountas 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)andupdateCredentials(AltAccount)only.- Parameters:
account- the account to make current, or null to clear- Since:
- 1.0.0
-
updateCredentials
Replaces the stored entry foraccount'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.DIRECTlogin 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 onLoginResult.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
Discards the refresh token and expiry for the account withuuidand 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
Adds an account to storage, then saves. When an entry with the same UUID is already stored the incoming credentials are merged onto it (seeAltAccount.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
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 editedaccounts()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 — seeloadError(). 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 lastload()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 aStoreKeyProvider, 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 ofaccounts()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 onloadError(). Entries that cannot be used are skipped and noted onloadWarning(). Once the runtime is closed nothing is read, andloadError()says so.- Since:
- 1.0.0
-