feat: implement core-storage package with unified promise-based interface and encrypted-at-rest support

packages/core-storage/src/storage.interface.ts

@@ -0,0 +1,38 @@
+/**
+ * Generic storage interface contract.
+ *
+ * All storage implementations (localStorage, IndexedDB) must
+ * conform to this interface. Methods use generics to enforce
+ * type-safe serialization/deserialization at the consumer level.
+ *
+ * @example
+ * ```ts
+ * const user = await storage.getItem<UserProfile>(StorageKey.USER_PROFILE);
+ * ```
+ */
+export interface IStorageService {
+  /**
+   * Persist a value under the given key.
+   * The value is JSON-serialized before storage.
+   * If encryption is enabled, the serialized payload is encrypted at rest.
+   */
+  setItem<T>(key: string, value: T): Promise<void>;
+
+  /**
+   * Retrieve and deserialize a value by key.
+   * Returns `null` if the key does not exist or decryption/parsing fails.
+   */
+  getItem<T>(key: string): Promise<T | null>;
+
+  /** Remove a single key from storage. */
+  removeItem(key: string): Promise<void>;
+
+  /** Remove all keys managed by this storage instance. */
+  clear(): Promise<void>;
+
+  /** Check if a key exists in storage. */
+  hasItem(key: string): Promise<boolean>;
+
+  /** Get all keys currently in storage. */
+  keys(): Promise<string[]>;
+}