Shade/packages/shade-core/src/storage.ts

import type { IdentityKeyPair, SignedPreKey, OneTimePreKey, SessionState } from './types.js';

/** A retired identity kept in history during the rotation grace period */
export interface RetiredIdentity {
  keyPair: IdentityKeyPair;
  retiredAt: number;
}

/**
 * StorageProvider — abstract interface for persisting cryptographic state.
 *
 * Implementations per platform:
 *  - In-memory (testing)
 *  - IndexedDB (browser)
 *  - SQLite/PostgreSQL (server)
 *  - EncryptedSharedPreferences (Android)
 */
export interface StorageProvider {
  // ─── Identity ──────────────────────────────────────────────

  /** Get our local identity keypair, or null if not yet generated */
  getIdentityKeyPair(): Promise<IdentityKeyPair | null>;

  /** Persist our local identity keypair */
  saveIdentityKeyPair(keyPair: IdentityKeyPair): Promise<void>;

  /** Get our local registration ID (unique per installation) */
  getLocalRegistrationId(): Promise<number>;

  /** Save our local registration ID */
  saveLocalRegistrationId(id: number): Promise<void>;

  // ─── Signed Pre-Keys ──────────────────────────────────────

  /** Get a signed prekey by ID */
  getSignedPreKey(keyId: number): Promise<SignedPreKey | null>;

  /** Persist a signed prekey */
  saveSignedPreKey(key: SignedPreKey): Promise<void>;

  /** Remove a signed prekey (after rotation grace period) */
  removeSignedPreKey(keyId: number): Promise<void>;

  // ─── One-Time Pre-Keys ────────────────────────────────────

  /** Get a one-time prekey by ID */
  getOneTimePreKey(keyId: number): Promise<OneTimePreKey | null>;

  /** Persist a one-time prekey */
  saveOneTimePreKey(key: OneTimePreKey): Promise<void>;

  /** Remove a consumed one-time prekey */
  removeOneTimePreKey(keyId: number): Promise<void>;

  /** Count remaining one-time prekeys */
  getOneTimePreKeyCount(): Promise<number>;

  // ─── Sessions ─────────────────────────────────────────────

  /** Get session state for a peer address (e.g. "device:abc123") */
  getSession(address: string): Promise<SessionState | null>;

  /** Persist session state for a peer */
  saveSession(address: string, state: SessionState): Promise<void>;

  /** Remove session for a peer */
  removeSession(address: string): Promise<void>;

  /** Check if we trust a remote identity key (for TOFU or pinned keys) */
  isTrustedIdentity(address: string, identityKey: Uint8Array): Promise<boolean>;

  /** Save a trusted remote identity key */
  saveTrustedIdentity(address: string, identityKey: Uint8Array): Promise<void>;

  // ─── Identity History (rotation with grace period) ──────

  /** Add an identity to the retired history */
  addRetiredIdentity(identity: RetiredIdentity): Promise<void>;

  /** Get all retired identities (for grace-period decryption) */
  getRetiredIdentities(): Promise<RetiredIdentity[]>;

  /** Remove retired identities older than the given timestamp */
  pruneRetiredIdentities(olderThan: number): Promise<void>;
}