Class SharedVault

java.lang.Object
lol.trq.alts.vault.SharedVault

public final class SharedVault extends Object
One member device's copy of one AVP 0.5 shared alt repository.

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 Details

    • create

      public 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, listing host as the one host and the owner's device as the one member, and an empty first commit. The repository withholds refresh tokens until setShareRefreshTokens(boolean) turns sharing on.
      Parameters:
      host - the owner's home host
      owner - the owner
      Returns:
      this device's copy; fails with an AltsException only: the host's refusal by its kind (CONFLICT for a repository that exists, UNAUTHORIZED, RATE_LIMITED, NETWORK), PROTOCOL for 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 a LinkSession) reads the repository. The whole chain is pulled and verified from genesis.
      Parameters:
      host - the owner's home host, as the verified state lists it
      owner - the owner
      repoId - the repository
      Returns:
      the copy; fails with PROTOCOL if the chain does not verify, is another repository, or does not list host as 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. Prefer resume(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 it
      member - this device's identity
      repoId - the repository
      Returns:
      the copy; fails with PROTOCOL if the chain does not verify, is another repository, or does not list host as this member's home host, and INVALID_INPUT if 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 host
      member - the joiner's identity
      locator - the owner's repo locator
      Returns:
      the invite token; fails with PROTOCOL if 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 from prepareJoin(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 named
      member - the joiner's identity
      locator - the owner's repo locator
      Returns:
      the copy; fails with PROTOCOL for another owner key, a chain that does not verify, or a host that is not this member's home host in the verified state, and INVALID_INPUT if 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 last snapshot(): 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 owner
      snapshot - the persisted snapshot
      Returns:
      the copy; fails with PROTOCOL for a rollback, and INVALID_INPUT if 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 last snapshot(), as resume(VaultHost, OwnerIdentity, VaultSnapshot) does for the owner.
      Parameters:
      host - the home host the snapshot names (VaultHosts.connect(VaultSnapshot))
      member - this device's identity
      snapshot - the persisted snapshot
      Returns:
      the copy; fails with PROTOCOL for a rollback or a host that is not this member's home host, and INVALID_INPUT if the snapshot belongs to another member, this member left, or it is no longer a member
      Since:
      1.0.0
    • openReport

      public SyncReport openReport()
      What the pull that opened this copy found: every state of the chain for open and join, the states past the pin for resume, nothing for create.
      Returns:
      the report
      Since:
      1.0.0
    • sync

      public CompletableFuture<SyncReport> 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 PROTOCOL as above, INVALID_INPUT after leave(), or the host's refusal by its kind
      Since:
      1.0.0
    • accounts

      public List<AltAccount> 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 a refreshToken or an expiresAt (SPEC 5.1). Nothing here is written to the runtime's AccountStore: 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

      public Optional<AltAccount> account(String uuid)
      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. edit runs 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 no refreshToken or expiresAt, and none is sent.

      edit runs on the runtime's executor, one write at a time; it must not block on this vault.

      Parameters:
      uuid - the player UUID
      edit - the change, for example a -> a.withTokens(access, refresh, expiresAt)
      Returns:
      the account as this copy holds it after the write; fails with NOT_FOUND if this copy holds no such account or holds it deleted, INVALID_INPUT if edit returns null or another UUID or after leave(), PROTOCOL if the vault holds an impossible timestamp from a member, and the host's refusal by its kind
      Since:
      1.0.0
    • put

      public CompletableFuture<Void> put(AltAccount base, AltAccount edited)
      Writes an edit of an account the caller read earlier, as one commit (AVP SPEC 5): only the fields where base and edited differ take a fresh stamp, so a remote edit of any other field, merged into this copy since base was read, survives. A ban server base had and edited drops is cleared. An account this copy does not hold, or holds deleted, is written whole from edited, including clearing every ban server it held before its deletion that edited does not carry. An edit that changes nothing sends no commit. While the repository withholds refresh tokens, refreshToken and expiresAt are not sent.
      Parameters:
      base - the account as read, from account(String) or accounts()
      edited - the account as changed; the same UUID
      Returns:
      completes once the host stored the commit; fails with INVALID_INPUT for a missing or mismatched UUID or after leave(), PROTOCOL if the vault holds an impossible timestamp from a member, and the host's refusal by its kind
      Since:
      1.0.0
    • put

      public CompletableFuture<Void> 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; use update(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 with markBanned(String, String, BanInfo) and a null ban). A put that changes nothing sends no commit. While the repository withholds refresh tokens, its refreshToken and expiresAt are 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) and put(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_INPUT for an account without a UUID or after leave(), PROTOCOL if the vault holds an impossible timestamp from a member, and the host's refusal by its kind
      Since:
      1.0.0
    • removeAccount

      public CompletableFuture<Void> removeAccount(String uuid)
      Deletes an account from the repository: its deletion marker takes a fresh stamp and its fields stay, so a later put(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

      public CompletableFuture<Void> 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.
      Parameters:
      uuid - the player UUID
      serverId - the server id, an opaque host-chosen string
      ban - the ban, or null to clear that server's register
      Returns:
      completes once the host stored the commit; fails as put(AltAccount, AltAccount)
      Since:
      1.0.0
    • mergeHeads

      public CompletableFuture<Boolean> 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

      public List<VaultMember> 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

      public List<HostRef> hosts()
      The hosts of the repository as the latest verified manifest state lists them.
      Returns:
      the hosts, in the state's order
      Since:
      1.0.0
    • pendingLeaves

      public List<VaultMember> 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

      public CompletableFuture<Void> invite(InviteToken token)
      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 PROTOCOL for an acceptance that does not verify, INVALID_INPUT unless 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

      public CompletableFuture<Void> 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. The removed member keeps what it already decrypted. Owner only.
      Parameters:
      member - the member, from roster()
      Returns:
      completes once the host stored the new state; fails with INVALID_INPUT unless 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
    • setShareRefreshTokens

      public CompletableFuture<Void> setShareRefreshTokens(boolean share)
      Sets the refresh-token policy (AVP SPEC 5.1, 8.5) in a new owner-signed state. Sharing is irrevocable for what was shared: turning it off stops future sharing only. Setting the current value publishes nothing. Owner only.
      Parameters:
      share - whether the members share refresh tokens
      Returns:
      completes once the host stored the new state; fails with INVALID_INPUT unless this device is the owner, and the host's refusal by its kind
      Since:
      1.0.0
    • sharesRefreshTokens

      public boolean sharesRefreshTokens()
      Whether the latest verified state shares refresh tokens (AVP SPEC 5.1).
      Returns:
      whether the policy shares
      Since:
      1.0.0
    • processLeaves

      public CompletableFuture<List<VaultMember>> processLeaves()
      Pulls, then removes every member whose pending leave request passes the AVP SPEC 8.4 checks, one removal each (as removeMember(VaultMember)). Owner only.
      Returns:
      the members removed, as the roster listed them after the pull; fails with INVALID_INPUT unless this device is the owner, and the host's refusal by its kind
      Since:
      1.0.0
    • leave

      public CompletableFuture<Void> 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_INPUT for 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

      public String repoId()
      The repository id.
      Returns:
      the id
      Since:
      1.0.0
    • memberId

      public String memberId()
      This device's member id, as lastUsedBy and observedBy name it.
      Returns:
      the member id
      Since:
      1.0.0
    • host

      public VaultHost host()
      The home host this copy syncs through.
      Returns:
      the connection
      Since:
      1.0.0
    • locator

      public RepoLocator 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 kind INVALID_INPUT unless this device is the owner
      Since:
      1.0.0
    • snapshot

      public VaultSnapshot snapshot()
      The state to persist, so resume(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 its VaultSnapshot.toJson() encrypted, for example in HostSecrets, never in plain text.
      Returns:
      the snapshot
      Since:
      1.0.0