Shade/packages/shade-server/src/store.ts

/**
 * PrekeyStore — server-side storage interface for prekey bundles.
 *
 * The prekey server stores public keys only (never private keys).
 */
export interface PrekeyStore {
  /** Save or update an identity for an address */
  saveIdentity(
    address: string,
    identitySigningKey: Uint8Array,
    identityDHKey: Uint8Array,
  ): Promise<void>;

  /** Get an identity by address */
  getIdentity(
    address: string,
  ): Promise<{ identitySigningKey: Uint8Array; identityDHKey: Uint8Array } | null>;

  /** Save or update a signed prekey for an address */
  saveSignedPreKey(
    address: string,
    keyId: number,
    publicKey: Uint8Array,
    signature: Uint8Array,
  ): Promise<void>;

  /** Get the current signed prekey for an address */
  getSignedPreKey(
    address: string,
  ): Promise<{ keyId: number; publicKey: Uint8Array; signature: Uint8Array } | null>;

  /** Add one-time prekeys for an address */
  saveOneTimePreKeys(
    address: string,
    keys: Array<{ keyId: number; publicKey: Uint8Array }>,
  ): Promise<void>;

  /** Consume (pop) one one-time prekey for an address. Returns null if none left. */
  consumeOneTimePreKey(
    address: string,
  ): Promise<{ keyId: number; publicKey: Uint8Array } | null>;

  /** Get remaining one-time prekey count for an address */
  getOneTimePreKeyCount(address: string): Promise<number>;

  /** Delete all keys for an address */
  deleteAll(address: string): Promise<void>;

  // ─── Stale cleanup ─────────────────────────────────────

  /**
   * Update the last-activity timestamp for an address to the current time.
   * Called on every read or write that references the address, so stale
   * cleanup only removes addresses nobody has touched in a long time.
   */
  touchIdentity(address: string): Promise<void>;

  /**
   * Purge every identity whose last activity is older than `olderThanMs`
   * milliseconds ago. Cascades deletion to signed prekeys and one-time
   * prekeys for the affected addresses.
   *
   * @returns the number of addresses purged
   */
  purgeStaleIdentities(olderThanMs: number): Promise<number>;
}