Class SharedVault
An instance comes from create(VaultHost, OwnerIdentity), open(VaultHost, OwnerIdentity, String), join(VaultHost, VaultIdentity, RepoLocator) or resume(VaultHost, OwnerIdentity, VaultSnapshot) and syncs through its home
host (VaultHost, from alts.vault()). The client never trusts a host: it verifies every owner-signed
manifest state from genesis and pins the highest, refuses a rollback, checks every member-signed commit, merges the
heads per account and per field, wraps the data key only to invite-token keys, and withholds refreshToken and
expiresAt on read and on write unless the latest verified state shares them. A forged state or a rollback
fails the whole operation with PROTOCOL, and the pull that met it adopts nothing of what the host served,
where the reference client keeps the valid prefix of it. No secret (the owner phrase, its entropy or seed, a private
key, a data key, a plaintext account field) is ever sent to a host.
The accounts are AltAccounts (accounts(), put(AltAccount, AltAccount), removeAccount(String), markBanned(String, String, BanInfo)); the owner manages members and the policy (invite(InviteToken), removeMember(VaultMember),
setShareRefreshTokens(boolean), processLeaves()); a member can leave(). The host persists
snapshot() after each operation and passes it to resume(VaultHost, OwnerIdentity, VaultSnapshot) next time. Nothing the vault reads
is written to the runtime's account store.
Every operation that talks to the host returns a future that fails only with an AltsException.
Operations on one copy run one at a time, in the order they were started; the accessors read the state the
last finished operation left and never wait.
- Since:
- 0.2.0
-
Method Summary
Modifier and TypeMethodDescriptionOne account of this copy, unless it is absent or deleted.accounts()The accounts of this copy that are not deleted, by player UUID, as the last finished operation left them.static CompletableFuture<SharedVault> create(VaultHost host, OwnerIdentity owner) Creates a repository on the owner's home host (AVP SPEC 8.2): a fresh genesis state signed by the owner key, listinghostas the one host and the owner's device as the one member, and an empty first commit.host()The home host this copy syncs through.hosts()The hosts of the repository as the latest verified manifest state lists them.invite(InviteToken token) Invites a member from the invite token the joiner sent (AVP SPEC 8.1, 8.2).booleanisOwner()Whether this device is the owner's.static CompletableFuture<SharedVault> join(VaultHost home, VaultIdentity member, RepoLocator locator) The joiner's last step (AVP SPEC 8.1, 11.2), once the owner invited the token fromprepareJoin(VaultHost, VaultIdentity, RepoLocator): pulls the chain from the joiner's home host, verifies it from genesis, checks that the genesis owner key matches the locator's owner fingerprint, and reads the accounts.leave()Leaves the repository (AVP SPEC 8.4): sends a signed leave request and stops syncing at once; every later operation that talks to the host is refused, and a snapshot taken afterwards does not resume.booleanleft()Whether this member left the repository.locator()The repo locator to give a joiner (AVP SPEC 11.2): this repository at the owner's home host, with the owner fingerprint.markBanned(String uuid, String serverId, BanInfo ban) Records the ban an account was last observed with on one server, as the register for that server id (AVP SPEC 5); other servers' registers stay.memberId()This device's member id, aslastUsedByandobservedByname it.Merges every readable head into this copy and, when there was more than one, pushes the merge commit whose parents are exactly those heads (AVP SPEC 5).static CompletableFuture<SharedVault> open(VaultHost host, OwnerIdentity owner, String repoId) Opens a repository the owner's device is a member of, from its home host, without a snapshot: the way a second owner device (after aLinkSession) reads the repository.static CompletableFuture<SharedVault> open(VaultHost host, VaultIdentity member, String repoId) Opens a repository this member device belongs to, from its home host, without a snapshot.What the pull that opened this copy found: every state of the chain foropenandjoin, the states past the pin forresume, nothing forcreate.The members whose pending leave request passed the AVP SPEC 8.4 checks at the last pull.static CompletableFuture<InviteToken> prepareJoin(VaultHost home, VaultIdentity member, RepoLocator locator) The joiner's first step (AVP SPEC 8.1, 8.2): asks the joiner's home host to carry the repository for this member, checks the acceptance the host signs, and builds the invite token to give the owner.Pulls, then removes every member whose pending leave request passes the AVP SPEC 8.4 checks, one removal each (asremoveMember(VaultMember)).put(AltAccount account) Writes an account into the repository as one commit (AVP SPEC 5), stamping the fields that differ from the copy as it stands when the write runs; a stale object can revert remote edits; useupdate(String, UnaryOperator).put(AltAccount base, AltAccount edited) Writes an edit of an account the caller read earlier, as one commit (AVP SPEC 5): only the fields wherebaseandediteddiffer take a fresh stamp, so a remote edit of any other field, merged into this copy sincebasewas read, survives.removeAccount(String uuid) Deletes an account from the repository: its deletion marker takes a fresh stamp and its fields stay, so a laterput(AltAccount, AltAccount)brings it back (AVP SPEC 5).removeMember(VaultMember member) Removes a member (AVP SPEC 8.3): rotates the data key to a new epoch wrapped to every remaining member, records the removal with its cutoff, and carries the merged accounts forward under the new key.repoId()The repository id.static CompletableFuture<SharedVault> resume(VaultHost host, OwnerIdentity owner, VaultSnapshot snapshot) Opens the owner device's copy again from its lastsnapshot(): pulls the whole chain, verifies it, and refuses it unless it contains the snapshot's pin or wins the tie rule at or below it (SPEC 6.4, 6.5), then takes the retained keys, the clock and the merged accounts back.static CompletableFuture<SharedVault> resume(VaultHost host, VaultIdentity member, VaultSnapshot snapshot) Opens this member device's copy again from its lastsnapshot(), asresume(VaultHost, OwnerIdentity, VaultSnapshot)does for the owner.roster()The members as the latest verified manifest state lists them, the owner's device among them.setShareRefreshTokens(boolean share) Sets the refresh-token policy (AVP SPEC 5.1, 8.5) in a new owner-signed state.booleanWhether the latest verified state shares refresh tokens (AVP SPEC 5.1).snapshot()The state to persist, soresume(VaultHost, OwnerIdentity, VaultSnapshot)can open this copy again: the pin, the retained epoch keys, the clock and the merged accounts, as the last finished operation left them.sync()Syncs with the home host (AVP SPEC 5, 6.4, 7.5): verifies every new manifest state and pins the highest, checks every head, reads and merges the heads it can, and pushes a merge commit when it read more than one.update(String uuid, UnaryOperator<AltAccount> edit) Edits one account in the repository as one commit (AVP SPEC 5): the recommended way to change an account.
-
Method Details
-
create
Creates a repository on the owner's home host (AVP SPEC 8.2): a fresh genesis state signed by the owner key, listinghostas the one host and the owner's device as the one member, and an empty first commit. The repository withholds refresh tokens untilsetShareRefreshTokens(boolean)turns sharing on.- Parameters:
host- the owner's home hostowner- the owner- Returns:
- this device's copy; fails with an
AltsExceptiononly: the host's refusal by its kind (CONFLICTfor a repository that exists,UNAUTHORIZED,RATE_LIMITED,NETWORK),PROTOCOLfor an answer that is not the protocol - Since:
- 1.0.0
-
open
public static CompletableFuture<SharedVault> open(VaultHost host, OwnerIdentity owner, String repoId) Opens a repository the owner's device is a member of, from its home host, without a snapshot: the way a second owner device (after aLinkSession) reads the repository. The whole chain is pulled and verified from genesis.- Parameters:
host- the owner's home host, as the verified state lists itowner- the ownerrepoId- the repository- Returns:
- the copy; fails with
PROTOCOLif the chain does not verify, is another repository, or does not listhostas the owner's home host - Since:
- 1.0.0
-
open
public static CompletableFuture<SharedVault> open(VaultHost host, VaultIdentity member, String repoId) Opens a repository this member device belongs to, from its home host, without a snapshot. The whole chain is pulled and verified from genesis. Preferresume(VaultHost, OwnerIdentity, VaultSnapshot)with the last snapshot: it also refuses a host that rolls the repository back below what this device saw.- Parameters:
host- the member's home host, as the verified state lists itmember- this device's identityrepoId- the repository- Returns:
- the copy; fails with
PROTOCOLif the chain does not verify, is another repository, or does not listhostas this member's home host, andINVALID_INPUTif the identity is not a member - Since:
- 1.0.0
-
prepareJoin
public static CompletableFuture<InviteToken> prepareJoin(VaultHost home, VaultIdentity member, RepoLocator locator) The joiner's first step (AVP SPEC 8.1, 8.2): asks the joiner's home host to carry the repository for this member, checks the acceptance the host signs, and builds the invite token to give the owner. The home host may be the owner's (alts.vault().connect(locator)) or one the joiner picks.- Parameters:
home- the joiner's home hostmember- the joiner's identitylocator- the owner's repo locator- Returns:
- the invite token; fails with
PROTOCOLif the host's acceptance does not verify for this host, repository and member - Since:
- 1.0.0
-
join
public static CompletableFuture<SharedVault> join(VaultHost home, VaultIdentity member, RepoLocator locator) The joiner's last step (AVP SPEC 8.1, 11.2), once the owner invited the token fromprepareJoin(VaultHost, VaultIdentity, RepoLocator): pulls the chain from the joiner's home host, verifies it from genesis, checks that the genesis owner key matches the locator's owner fingerprint, and reads the accounts.- Parameters:
home- the joiner's home host, the one its invite token namedmember- the joiner's identitylocator- the owner's repo locator- Returns:
- the copy; fails with
PROTOCOLfor another owner key, a chain that does not verify, or a host that is not this member's home host in the verified state, andINVALID_INPUTif the owner has not invited this member yet - Since:
- 1.0.0
-
resume
public static CompletableFuture<SharedVault> resume(VaultHost host, OwnerIdentity owner, VaultSnapshot snapshot) Opens the owner device's copy again from its lastsnapshot(): pulls the whole chain, verifies it, and refuses it unless it contains the snapshot's pin or wins the tie rule at or below it (SPEC 6.4, 6.5), then takes the retained keys, the clock and the merged accounts back.- Parameters:
host- the home host the snapshot names (VaultHosts.connect(VaultSnapshot))owner- the ownersnapshot- the persisted snapshot- Returns:
- the copy; fails with
PROTOCOLfor a rollback, andINVALID_INPUTif the snapshot belongs to another member - Since:
- 1.0.0
-
resume
public static CompletableFuture<SharedVault> resume(VaultHost host, VaultIdentity member, VaultSnapshot snapshot) Opens this member device's copy again from its lastsnapshot(), asresume(VaultHost, OwnerIdentity, VaultSnapshot)does for the owner.- Parameters:
host- the home host the snapshot names (VaultHosts.connect(VaultSnapshot))member- this device's identitysnapshot- the persisted snapshot- Returns:
- the copy; fails with
PROTOCOLfor a rollback or a host that is not this member's home host, andINVALID_INPUTif the snapshot belongs to another member, this member left, or it is no longer a member - Since:
- 1.0.0
-
openReport
What the pull that opened this copy found: every state of the chain foropenandjoin, the states past the pin forresume, nothing forcreate.- Returns:
- the report
- Since:
- 1.0.0
-
sync
Syncs with the home host (AVP SPEC 5, 6.4, 7.5): verifies every new manifest state and pins the highest, checks every head, reads and merges the heads it can, and pushes a merge commit when it read more than one. A head this device cannot read is left alone and counted, never a failure.A forged state, a chain without the pin that does not win the tie rule (a rollback), or any state that fails a SPEC 6.1 check fails the whole sync with
PROTOCOL; such a sync adopts no state, reads no head and pushes no commit, so the copy stays as it was. This is stricter than the reference client, which keeps the valid prefix of what a host served.A sync that finds no new state and at most one readable head pushes nothing. One that finds more than one readable head merges them and pushes a merge commit, even when the host served nothing new (heads that diverged earlier, or a merge push that failed).
- Returns:
- the report; fails with
PROTOCOLas above,INVALID_INPUTafterleave(), or the host's refusal by its kind - Since:
- 1.0.0
-
accounts
The accounts of this copy that are not deleted, by player UUID, as the last finished operation left them. While the repository withholds refresh tokens, none carries arefreshTokenor anexpiresAt(SPEC 5.1). Nothing here is written to the runtime'sAccountStore: an account of a shared repository is one the user chose not to save, and a host that wants one saved adds it itself.- Returns:
- the accounts, sorted by UUID
- Since:
- 1.0.0
-
account
One account of this copy, unless it is absent or deleted.- Parameters:
uuid- the player UUID- Returns:
- the account, or empty
- Since:
- 1.0.0
-
update
Edits one account in the repository as one commit (AVP SPEC 5): the recommended way to change an account.editruns inside the write, on the account as this copy holds it at that moment, and only the fields where its result differs from what it was given take a fresh stamp from the vault's clock. A remote edit of any other field, merged into this copy before or while the caller worked, is never reverted. A ban server the result drops is cleared. An edit that changes nothing sends no commit. While the repository withholds refresh tokens, the account it is given carries norefreshTokenorexpiresAt, and none is sent.editruns on the runtime's executor, one write at a time; it must not block on this vault.- Parameters:
uuid- the player UUIDedit- the change, for examplea -> a.withTokens(access, refresh, expiresAt)- Returns:
- the account as this copy holds it after the write; fails with
NOT_FOUNDif this copy holds no such account or holds it deleted,INVALID_INPUTifeditreturns null or another UUID or afterleave(),PROTOCOLif the vault holds an impossible timestamp from a member, and the host's refusal by its kind - Since:
- 1.0.0
-
put
Writes an edit of an account the caller read earlier, as one commit (AVP SPEC 5): only the fields wherebaseandediteddiffer take a fresh stamp, so a remote edit of any other field, merged into this copy sincebasewas read, survives. A ban serverbasehad andediteddrops is cleared. An account this copy does not hold, or holds deleted, is written whole fromedited, including clearing every ban server it held before its deletion thatediteddoes not carry. An edit that changes nothing sends no commit. While the repository withholds refresh tokens,refreshTokenandexpiresAtare not sent.- Parameters:
base- the account as read, fromaccount(String)oraccounts()edited- the account as changed; the same UUID- Returns:
- completes once the host stored the commit; fails with
INVALID_INPUTfor a missing or mismatched UUID or afterleave(),PROTOCOLif the vault holds an impossible timestamp from a member, and the host's refusal by its kind - Since:
- 1.0.0
-
put
Writes an account into the repository as one commit (AVP SPEC 5), stamping the fields that differ from the copy as it stands when the write runs; a stale object can revert remote edits; useupdate(String, UnaryOperator). A new or deleted account is written whole, and a revived one loses every ban server it held before its deletion that it does not carry now. Each ban the account carries is written per server id; on a live account, a server it does not mention is left as it is (clear one withmarkBanned(String, String, BanInfo)and a null ban). A put that changes nothing sends no commit. While the repository withholds refresh tokens, itsrefreshTokenandexpiresAtare not sent."Stale" means read before the copy merged a remote edit of the same account: such an object differs from the copy in exactly the field the other member changed, and putting it stamps that field back.
update(String, UnaryOperator)andput(AltAccount, AltAccount)compare with what the caller started from instead, and are safe for a read-modify-write.- Parameters:
account- the account- Returns:
- completes once the host stored the commit; fails with
INVALID_INPUTfor an account without a UUID or afterleave(),PROTOCOLif the vault holds an impossible timestamp from a member, and the host's refusal by its kind - Since:
- 1.0.0
-
removeAccount
Deletes an account from the repository: its deletion marker takes a fresh stamp and its fields stay, so a laterput(AltAccount, AltAccount)brings it back (AVP SPEC 5).- Parameters:
uuid- the player UUID- Returns:
- completes once the host stored the commit; fails as
put(AltAccount, AltAccount) - Since:
- 1.0.0
-
markBanned
Records the ban an account was last observed with on one server, as the register for that server id (AVP SPEC 5); other servers' registers stay.- Parameters:
uuid- the player UUIDserverId- the server id, an opaque host-chosen stringban- the ban, ornullto clear that server's register- Returns:
- completes once the host stored the commit; fails as
put(AltAccount, AltAccount) - Since:
- 1.0.0
-
mergeHeads
Merges every readable head into this copy and, when there was more than one, pushes the merge commit whose parents are exactly those heads (AVP SPEC 5).sync()already does this.- Returns:
- whether a merge commit was pushed
- Since:
- 1.0.0
-
roster
The members as the latest verified manifest state lists them, the owner's device among them.- Returns:
- the roster, in the state's order
- Since:
- 1.0.0
-
hosts
-
pendingLeaves
The members whose pending leave request passed the AVP SPEC 8.4 checks at the last pull.- Returns:
- the leaving members
- Since:
- 1.0.0
-
invite
Invites a member from the invite token the joiner sent (AVP SPEC 8.1, 8.2). The token's host acceptance must verify under its host key and name this repository, the token's member key and its home host, and must not have expired. The data key is wrapped to exactly the token's key, never to a key a host served, and the joiner's home host joins the repository's hosts when it is not listed yet. Owner only.- Parameters:
token- the joiner's invite token (InviteToken.parse(String)reads pasted text)- Returns:
- completes once the host stored the new state; fails with
PROTOCOLfor an acceptance that does not verify,INVALID_INPUTunless this device is the owner, or for a current or removed member, and the host's refusal by its kind - Since:
- 1.0.0
-
removeMember
Removes a member (AVP SPEC 8.3): rotates the data key to a new epoch wrapped to every remaining member, records the removal with its cutoff, and carries the merged accounts forward under the new key. The removed member keeps what it already decrypted. Owner only.- Parameters:
member- the member, fromroster()- Returns:
- completes once the host stored the new state; fails with
INVALID_INPUTunless this device is the owner, for the owner itself or a key that is not a member, and the host's refusal by its kind - Since:
- 1.0.0
-
processLeaves
Pulls, then removes every member whose pending leave request passes the AVP SPEC 8.4 checks, one removal each (asremoveMember(VaultMember)). Owner only.- Returns:
- the members removed, as the roster listed them after the pull; fails with
INVALID_INPUTunless this device is the owner, and the host's refusal by its kind - Since:
- 1.0.0
-
leave
Leaves the repository (AVP SPEC 8.4): sends a signed leave request and stops syncing at once; every later operation that talks to the host is refused, and a snapshot taken afterwards does not resume. The owner removes the member when it next processes leaves. The owner cannot leave.- Returns:
- completes once the host stored the request; fails with
INVALID_INPUTfor the owner, and the host's refusal by its kind - Since:
- 1.0.0
-
left
public boolean left()Whether this member left the repository.- Returns:
- whether it left
- Since:
- 1.0.0
-
isOwner
public boolean isOwner()Whether this device is the owner's.- Returns:
- whether its key is the owner key
- Since:
- 1.0.0
-
repoId
-
memberId
This device's member id, aslastUsedByandobservedByname it.- Returns:
- the member id
- Since:
- 1.0.0
-
host
-
locator
The repo locator to give a joiner (AVP SPEC 11.2): this repository at the owner's home host, with the owner fingerprint. Owner only.- Returns:
- the locator
- Throws:
AltsException- of kindINVALID_INPUTunless this device is the owner- Since:
- 1.0.0
-
snapshot
The state to persist, soresume(VaultHost, OwnerIdentity, VaultSnapshot)can open this copy again: the pin, the retained epoch keys, the clock and the merged accounts, as the last finished operation left them. Take one after every operation that changes the copy. It holds secrets (the data keys and the accounts' credentials): persist itsVaultSnapshot.toJson()encrypted, for example inHostSecrets, never in plain text.- Returns:
- the snapshot
- Since:
- 1.0.0
-