Class HostSecrets

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

public final class HostSecrets extends Object
One runtime's per-user encrypted key/value secrets on local disk, separate from the account store. Holds host secrets (API keys, referral codes, integration tokens) that belong to the individual user and must never travel into a shared account repository. A host reaches it through AltsRuntime#secrets(); every runtime has its own.

Secrets are encrypted with a machine-derived key unless the host supplies its own through a StoreKeyProvider. That default is built from values that are not secret, so it deters casual copying and nothing more. Hosts namespace their own keys (for example "myfeature.api-key"); the library imposes no schema.

This store is deliberately split from AccountStore: accounts may be shared into a multi-member repository, but secrets stay local to one user.

Persistence follows the account store's rules: a write replaces the file in one step, writes are serialized, a failure is reported on saveError() rather than thrown, and a file that exists but could not be read is never written over: nothing is written until a load succeeds or the host calls discardUnreadable(). The store holds an exclusive lock on a sidecar <file>.lock for the life of the runtime that owns it; once the runtime is closed the mutators change memory only and record "the store is closed" on saveError().

Since:
1.0.0
  • Method Summary

    Modifier and Type
    Method
    Description
    void
    Removes a secret and persists.
    boolean
    Gives up on a secret file the last load() could not read, so the secrets can be written again; the route when the file will never open (a renamed OS user or moved home under the machine-derived key, a rotated host key).
    find(String key)
    Returns the stored secret for key, if there is one.
    void
    Writes any state still waiting on the write delay and returns once it is on disk.
    get(String key)
    Returns the stored secret for key, or null if absent.
    boolean
    has(String key)
    Returns whether a non-blank secret is stored for key.
    void
    Loads and decrypts secrets from disk into memory, replacing what memory held in one step: a reader on another thread sees the old secrets or the new ones, never a secret missing in between.
    Returns why the last load() could not read an existing secret file, if it could not.
    void
    put(String key, String value)
    Stores a secret and persists.
    void
    Encrypts the current secrets and writes them to disk before returning, replacing the file in one step.
    Returns why the most recent write did not reach the disk, if it did not.

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Method Details

    • get

      public String get(String key)
      Returns the stored secret for key, or null if absent. Prefer find(String), which says the same without a null.
      Parameters:
      key - the secret key
      Returns:
      the stored value, or null if absent
      Since:
      1.0.0
    • find

      public Optional<String> find(String key)
      Returns the stored secret for key, if there is one.
      Parameters:
      key - the secret key
      Returns:
      the stored value, or empty if absent
      Throws:
      NullPointerException - if key is null
      Since:
      1.0.0
    • put

      public void put(String key, String value)
      Stores a secret and persists. A null or blank value removes the key instead.
      Parameters:
      key - the secret key
      value - the value to store, or null/blank to remove the key
      Since:
      1.0.0
    • has

      public boolean has(String key)
      Returns whether a non-blank secret is stored for key.
      Parameters:
      key - the secret key
      Returns:
      true if a non-blank value is stored
      Since:
      1.0.0
    • clear

      public void clear(String key)
      Removes a secret and persists.
      Parameters:
      key - the secret key to clear
      Since:
      1.0.0
    • loadError

      public Optional<AltsFailure> loadError()
      Returns why the last load() could not read an existing secret file, if it could not. As with the account store, an unreadable file is not an empty one: it is copied aside when the load fails (unless it failed only for want of the key), and nothing is written over it until a later load succeeds or the host calls discardUnreadable() — see AccountStore.loadError(). The message carries no filesystem path.
      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
    • saveError

      public Optional<AltsFailure> saveError()
      Returns why the most recent write did not reach the disk, if it did not. The write is retried by the next mutation, save(), or flush(), and a success clears this; a write refused because the last load failed, or because the store is closed, is not retried. The message carries no filesystem path.
      Returns:
      the failure, of kind AltsFailure.Kind.STORAGE, or empty when the last write succeeded
      Since:
      1.0.0
    • save

      public void save()
      Encrypts the current secrets and writes them to disk before returning, replacing the file in one step. A failure is reported on saveError(). Does not write at all while the last load() failed on a file that exists — see loadError().
      Since:
      1.0.0
    • discardUnreadable

      public boolean discardUnreadable()
      Gives up on a secret file the last load() could not read, so the secrets can be written again; the route when the file will never open (a renamed OS user or moved home under the machine-derived key, a rotated host key). The file is copied aside first, and the next write starts a new file from what memory holds. See AccountStore.discardUnreadable().
      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
      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.
      Since:
      1.0.0
    • load

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