@idealyst/storage 1.2.106 → 1.2.108

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@idealyst/storage",
-  "version": "1.2.106",
+  "version": "1.2.108",
   "description": "Cross-platform storage abstraction for React and React Native",
   "documentation": "https://github.com/IdealystIO/idealyst-framework/tree/main/packages/storage#readme",
   "readme": "README.md",
@@ -40,6 +40,7 @@
   "peerDependencies": {
     "react": ">=16.8.0",
     "react-native": ">=0.60.0",
+    "react-native-keychain": ">=9.0.0",
     "react-native-mmkv": ">=4.0.0",
     "react-native-nitro-modules": ">=0.20.0"
   },
@@ -47,6 +48,9 @@
     "react-native": {
       "optional": true
     },
+    "react-native-keychain": {
+      "optional": true
+    },
     "react-native-mmkv": {
       "optional": true
     },
@@ -56,6 +60,7 @@
   },
   "devDependencies": {
     "@types/react": "^19.1.0",
+    "react-native-keychain": "^9.2.0",
     "react-native-mmkv": "^4.1.1",
     "react-native-nitro-modules": "^0.32.1",
     "typescript": "^5.0.0"
@@ -70,6 +75,9 @@
     "storage",
     "cross-platform",
     "localStorage",
-    "MMKV"
+    "MMKV",
+    "secure-storage",
+    "keychain",
+    "encryption"
   ]
 }

package/src/createSecureStorage.native.ts

@@ -0,0 +1,11 @@
+import BaseStorage from './storage';
+import NativeSecureStorage from './secure-storage.native';
+import type { SecureStorageOptions } from './types';
+
+/**
+ * Creates a secure storage instance using encrypted MMKV backed by the OS Keychain.
+ * The MMKV encryption key is stored in the iOS Keychain / Android Keystore.
+ */
+export function createSecureStorage(options?: SecureStorageOptions): BaseStorage {
+  return new BaseStorage(new NativeSecureStorage(options));
+}

package/src/createSecureStorage.ts

@@ -0,0 +1,14 @@
+import BaseStorage from './storage';
+import type { SecureStorageOptions } from './types';
+
+/**
+ * Creates a secure storage instance with encrypted data at rest.
+ *
+ * Platform stub — replaced by `.web.ts` and `.native.ts` at build time.
+ */
+export function createSecureStorage(_options?: SecureStorageOptions): BaseStorage {
+  throw new Error(
+    'createSecureStorage is not available on this platform. ' +
+    'Import from a platform-specific entry point.'
+  );
+}

package/src/createSecureStorage.web.ts

@@ -0,0 +1,12 @@
+import BaseStorage from './storage';
+import WebSecureStorage from './secure-storage.web';
+import type { SecureStorageOptions } from './types';
+
+/**
+ * Creates a secure storage instance using AES-GCM encryption via the Web Crypto API.
+ * Encryption keys are stored as non-extractable CryptoKeys in IndexedDB.
+ * Encrypted values are persisted in localStorage.
+ */
+export function createSecureStorage(options?: SecureStorageOptions): BaseStorage {
+  return new BaseStorage(new WebSecureStorage(options));
+}

package/src/index.native.ts

@@ -6,4 +6,6 @@ const storage = new BaseStorage(new NativeStorage());
 export default storage;
 // Export instance as both `storage` and `Storage` for convenience
 export { storage, storage as Storage, BaseStorage, NativeStorage };
+export { createSecureStorage } from './createSecureStorage.native';
+export { default as NativeSecureStorage } from './secure-storage.native';
 export * from './types';

package/src/index.ts

@@ -5,5 +5,6 @@ import BaseStorage from './storage';
 const storage = null as unknown as BaseStorage;
 
 export { BaseStorage, storage, storage as Storage };
+export { createSecureStorage } from './createSecureStorage';
 export default BaseStorage;
 export * from './types';

package/src/index.web.ts

@@ -6,4 +6,6 @@ const storage = new BaseStorage(new WebStorage());
 export default storage;
 // Export instance as both `storage` and `Storage` for convenience
 export { storage, storage as Storage, BaseStorage, WebStorage };
+export { createSecureStorage } from './createSecureStorage.web';
+export { default as WebSecureStorage } from './secure-storage.web';
 export * from './types';

package/src/secure-storage.native.ts

@@ -0,0 +1,136 @@
+import { createMMKV } from 'react-native-mmkv';
+import * as Keychain from 'react-native-keychain';
+import { IStorage, SecureStorageOptions } from './types';
+
+const KEY_USERNAME = '__mmkv_encryption_key__';
+
+class NativeSecureStorage implements IStorage {
+  private prefix: string;
+  private mmkv: ReturnType<typeof createMMKV> | null = null;
+  private initPromise: Promise<void> | null = null;
+
+  constructor(options: SecureStorageOptions = {}) {
+    this.prefix = options.prefix ?? 'secure';
+  }
+
+  private async ensureInitialized(): Promise<ReturnType<typeof createMMKV>> {
+    if (this.mmkv) return this.mmkv;
+    if (!this.initPromise) {
+      this.initPromise = this._init();
+    }
+    await this.initPromise;
+    return this.mmkv!;
+  }
+
+  private async _init(): Promise<void> {
+    const service = `${this.prefix}_keychain`;
+
+    let encryptionKey: string;
+    const credentials = await Keychain.getGenericPassword({ service });
+
+    if (credentials && credentials.password) {
+      encryptionKey = credentials.password;
+    } else {
+      // Generate a random 16-byte key (MMKV max encryptionKey length is 16 bytes)
+      const randomBytes = new Uint8Array(16);
+      globalThis.crypto.getRandomValues(randomBytes);
+      encryptionKey = String.fromCharCode(...randomBytes);
+
+      await Keychain.setGenericPassword(KEY_USERNAME, encryptionKey, {
+        service,
+        accessible: Keychain.ACCESSIBLE.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
+      });
+    }
+
+    this.mmkv = createMMKV({
+      id: `${this.prefix}_secure_mmkv`,
+      encryptionKey,
+    });
+  }
+
+  async getItem(key: string): Promise<string | null> {
+    try {
+      const storage = await this.ensureInitialized();
+      return storage.getString(key) || null;
+    } catch (error) {
+      console.error('Error getting item from secure storage:', error);
+      return null;
+    }
+  }
+
+  async setItem(key: string, value: string): Promise<void> {
+    try {
+      const storage = await this.ensureInitialized();
+      storage.set(key, value);
+    } catch (error) {
+      console.error('Error setting item in secure storage:', error);
+      throw error;
+    }
+  }
+
+  async removeItem(key: string): Promise<void> {
+    try {
+      const storage = await this.ensureInitialized();
+      storage.remove(key);
+    } catch (error) {
+      console.error('Error removing item from secure storage:', error);
+      throw error;
+    }
+  }
+
+  async clear(): Promise<void> {
+    try {
+      const storage = await this.ensureInitialized();
+      storage.clearAll();
+    } catch (error) {
+      console.error('Error clearing secure storage:', error);
+      throw error;
+    }
+  }
+
+  async getAllKeys(): Promise<string[]> {
+    try {
+      const storage = await this.ensureInitialized();
+      return storage.getAllKeys();
+    } catch (error) {
+      console.error('Error getting all keys from secure storage:', error);
+      return [];
+    }
+  }
+
+  async multiGet(keys: string[]): Promise<Array<[string, string | null]>> {
+    try {
+      const storage = await this.ensureInitialized();
+      return keys.map(key => [key, storage.getString(key) || null]);
+    } catch (error) {
+      console.error('Error in multiGet from secure storage:', error);
+      return keys.map(key => [key, null]);
+    }
+  }
+
+  async multiSet(keyValuePairs: Array<[string, string]>): Promise<void> {
+    try {
+      const storage = await this.ensureInitialized();
+      keyValuePairs.forEach(([key, value]) => {
+        storage.set(key, value);
+      });
+    } catch (error) {
+      console.error('Error in multiSet to secure storage:', error);
+      throw error;
+    }
+  }
+
+  async multiRemove(keys: string[]): Promise<void> {
+    try {
+      const storage = await this.ensureInitialized();
+      keys.forEach(key => {
+        storage.remove(key);
+      });
+    } catch (error) {
+      console.error('Error in multiRemove from secure storage:', error);
+      throw error;
+    }
+  }
+}
+
+export default NativeSecureStorage;

package/src/secure-storage.web.ts

@@ -0,0 +1,213 @@
+import { IStorage, SecureStorageOptions } from './types';
+
+const DB_NAME = 'idealyst_secure_storage';
+const DB_VERSION = 1;
+const STORE_NAME = 'crypto_keys';
+const IV_LENGTH = 12;
+
+class WebSecureStorage implements IStorage {
+  private prefix: string;
+  private cryptoKey: CryptoKey | null = null;
+  private initPromise: Promise<void> | null = null;
+
+  constructor(options: SecureStorageOptions = {}) {
+    this.prefix = options.prefix ?? 'secure';
+  }
+
+  private async ensureInitialized(): Promise<CryptoKey> {
+    if (this.cryptoKey) return this.cryptoKey;
+    if (!this.initPromise) {
+      this.initPromise = this._init();
+    }
+    await this.initPromise;
+    return this.cryptoKey!;
+  }
+
+  private async _init(): Promise<void> {
+    if (typeof crypto === 'undefined' || !crypto.subtle) {
+      throw new Error(
+        'Secure storage requires the Web Crypto API (crypto.subtle). ' +
+        'Ensure you are running in a secure context (HTTPS).'
+      );
+    }
+
+    const db = await this.openDB();
+    const keyName = `${this.prefix}_aes_key`;
+
+    const existingKey = await this.getKeyFromDB(db, keyName);
+    if (existingKey) {
+      this.cryptoKey = existingKey;
+      db.close();
+      return;
+    }
+
+    this.cryptoKey = await crypto.subtle.generateKey(
+      { name: 'AES-GCM', length: 256 },
+      false,
+      ['encrypt', 'decrypt']
+    );
+
+    await this.putKeyInDB(db, keyName, this.cryptoKey);
+    db.close();
+  }
+
+  private async encrypt(plaintext: string): Promise<string> {
+    const key = await this.ensureInitialized();
+    const iv = crypto.getRandomValues(new Uint8Array(IV_LENGTH));
+    const encoded = new TextEncoder().encode(plaintext);
+
+    const ciphertext = await crypto.subtle.encrypt(
+      { name: 'AES-GCM', iv },
+      key,
+      encoded
+    );
+
+    const combined = new Uint8Array(iv.length + ciphertext.byteLength);
+    combined.set(iv);
+    combined.set(new Uint8Array(ciphertext), iv.length);
+
+    return btoa(String.fromCharCode(...combined));
+  }
+
+  private async decrypt(stored: string): Promise<string> {
+    const key = await this.ensureInitialized();
+    const combined = Uint8Array.from(atob(stored), c => c.charCodeAt(0));
+
+    const iv = combined.slice(0, IV_LENGTH);
+    const ciphertext = combined.slice(IV_LENGTH);
+
+    const decrypted = await crypto.subtle.decrypt(
+      { name: 'AES-GCM', iv },
+      key,
+      ciphertext
+    );
+
+    return new TextDecoder().decode(decrypted);
+  }
+
+  private storageKey(key: string): string {
+    return `__secure_${this.prefix}_${key}`;
+  }
+
+  private storageKeyPrefix(): string {
+    return `__secure_${this.prefix}_`;
+  }
+
+  async getItem(key: string): Promise<string | null> {
+    try {
+      const stored = localStorage.getItem(this.storageKey(key));
+      if (stored === null) return null;
+      return await this.decrypt(stored);
+    } catch (error) {
+      console.error('Error getting item from secure storage:', error);
+      return null;
+    }
+  }
+
+  async setItem(key: string, value: string): Promise<void> {
+    try {
+      const encrypted = await this.encrypt(value);
+      localStorage.setItem(this.storageKey(key), encrypted);
+    } catch (error) {
+      console.error('Error setting item in secure storage:', error);
+      throw error;
+    }
+  }
+
+  async removeItem(key: string): Promise<void> {
+    try {
+      localStorage.removeItem(this.storageKey(key));
+    } catch (error) {
+      console.error('Error removing item from secure storage:', error);
+      throw error;
+    }
+  }
+
+  async clear(): Promise<void> {
+    try {
+      const keys = await this.getAllKeys();
+      keys.forEach(key => localStorage.removeItem(this.storageKey(key)));
+    } catch (error) {
+      console.error('Error clearing secure storage:', error);
+      throw error;
+    }
+  }
+
+  async getAllKeys(): Promise<string[]> {
+    try {
+      const prefix = this.storageKeyPrefix();
+      const keys: string[] = [];
+      for (let i = 0; i < localStorage.length; i++) {
+        const fullKey = localStorage.key(i);
+        if (fullKey?.startsWith(prefix)) {
+          keys.push(fullKey.slice(prefix.length));
+        }
+      }
+      return keys;
+    } catch (error) {
+      console.error('Error getting all keys from secure storage:', error);
+      return [];
+    }
+  }
+
+  async multiGet(keys: string[]): Promise<Array<[string, string | null]>> {
+    return Promise.all(
+      keys.map(async (key) => {
+        const value = await this.getItem(key);
+        return [key, value] as [string, string | null];
+      })
+    );
+  }
+
+  async multiSet(keyValuePairs: Array<[string, string]>): Promise<void> {
+    for (const [key, value] of keyValuePairs) {
+      await this.setItem(key, value);
+    }
+  }
+
+  async multiRemove(keys: string[]): Promise<void> {
+    for (const key of keys) {
+      await this.removeItem(key);
+    }
+  }
+
+  private openDB(): Promise<IDBDatabase> {
+    return new Promise((resolve, reject) => {
+      const request = indexedDB.open(DB_NAME, DB_VERSION);
+
+      request.onupgradeneeded = () => {
+        const db = request.result;
+        if (!db.objectStoreNames.contains(STORE_NAME)) {
+          db.createObjectStore(STORE_NAME);
+        }
+      };
+
+      request.onsuccess = () => resolve(request.result);
+      request.onerror = () => reject(request.error);
+    });
+  }
+
+  private getKeyFromDB(db: IDBDatabase, keyName: string): Promise<CryptoKey | null> {
+    return new Promise((resolve, reject) => {
+      const tx = db.transaction(STORE_NAME, 'readonly');
+      const store = tx.objectStore(STORE_NAME);
+      const request = store.get(keyName);
+
+      request.onsuccess = () => resolve(request.result ?? null);
+      request.onerror = () => reject(request.error);
+    });
+  }
+
+  private putKeyInDB(db: IDBDatabase, keyName: string, key: CryptoKey): Promise<void> {
+    return new Promise((resolve, reject) => {
+      const tx = db.transaction(STORE_NAME, 'readwrite');
+      const store = tx.objectStore(STORE_NAME);
+      const request = store.put(key, keyName);
+
+      request.onsuccess = () => resolve();
+      request.onerror = () => reject(request.error);
+    });
+  }
+}
+
+export default WebSecureStorage;

package/src/types.ts

@@ -1,3 +1,13 @@
+export interface SecureStorageOptions {
+  /**
+   * Namespace prefix for storage keys.
+   * - Native: used as the Keychain service name and MMKV instance ID.
+   * - Web: used as prefix for localStorage keys and IndexedDB key name.
+   * @default 'secure'
+   */
+  prefix?: string;
+}
+
 export interface IStorage {
   getItem: (key: string) => Promise<string | null>;
   setItem: (key: string, value: string) => Promise<void>;