@okint-digital/okint-rn-storage 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Okint Digital
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,217 @@
+# @okint-digital/okint-rn-storage
+
+> One async storage API for React Native. Swappable backends — hardware
+> **Keystore/Keychain** for secrets, **SharedPreferences/UserDefaults** for plain
+> data, or **in-memory** for ephemerals. No third-party runtime dependencies.
+
+Built by **Okint**. Designed to be the simple, dependable storage layer you reach
+for instead of juggling `react-native-keychain` + `react-native-encrypted-storage`
++ `async-storage` + an MMKV wrapper.
+
+## Why
+
+- **One API, many backends.** Choose per data sensitivity at init — same calls everywhere.
+- **Secrets in hardware.** `secure` keeps the encryption key in the Android Keystore /
+  iOS Keychain (hardware-backed where available). Right home for JWTs, refresh & FCM tokens.
+- **Vanilla.** Zero third-party dependencies — JS or native. The native module is
+  ours (Kotlin + Objective-C); all crypto is the platform's own (`javax.crypto` +
+  AndroidKeystore / CommonCrypto + Keychain). Nothing to audit but us.
+- **Typed & async.** Promise-based, fully typed, with JSON / number / boolean helpers.
+
+## Install
+
+```sh
+npm install @okint-digital/okint-rn-storage
+# iOS
+cd ios && pod install
+# Android: autolinked. Rebuild the app.
+```
+
+Requires React Native 0.73+ (AGP 8 `namespace`, Java 17). Works on the legacy
+and the New Architecture (via the interop layer).
+
+## Usage
+
+```ts
+import { createStorage } from '@okint-digital/okint-rn-storage';
+
+// Secrets → hardware-backed Keystore / Keychain
+const auth = createStorage({ backend: 'secure', namespace: 'auth' });
+await auth.setString('refreshToken', token);
+const token = await auth.getString('refreshToken');
+await auth.setItem('fcm', { token: t, platform: 'android' }); // JSON helper
+
+// Plain persistent data → SharedPreferences / UserDefaults
+const prefs = createStorage({ backend: 'async', namespace: 'prefs' });
+await prefs.setBoolean('onboarded', true);
+
+// Ephemeral / tests → in-memory, zero native
+const cache = createStorage({ backend: 'memory' });
+
+// SYNCHRONOUS store (the MMKV-style use case) — load once, then sync everywhere.
+import { createSyncStorage } from '@okint-digital/okint-rn-storage';
+const fast = await createSyncStorage({ backend: 'fast', namespace: 'app' });
+fast.setBoolean('onboarded', true);              // sync write (persists in background)
+const onboarded = fast.getBoolean('onboarded');  // sync read — no await
+await fast.flush();                              // optional: guarantee durability
+```
+
+### API
+
+Every instance implements:
+
+| Method | Notes |
+|---|---|
+| `getString / setString` | raw strings |
+| `getItem<T> / setItem<T>` | JSON (throws `PARSE_ERROR` on malformed read) |
+| `getNumber / setNumber` | numbers |
+| `getBoolean / setBoolean` | booleans |
+| `has(key)` | presence check |
+| `remove(key)` · `clear()` · `keys()` | |
+| `multiGet / multiSet / multiRemove` | batched string ops |
+| `backend` | the backing `BackendKind` |
+
+All methods return Promises and **reject** (never throw synchronously) on
+invalid input. `namespace` partitions stores so they never collide.
+
+### Input validation
+
+- **Namespace** becomes a file/service name → restricted to `[A-Za-z0-9._-]`
+  (1–200 chars); `../`, `/`, spaces, etc. are rejected (`INVALID_NAMESPACE`) to
+  prevent filename injection / cross-store collisions.
+- **Keys** must be non-empty strings without control characters (`INVALID_KEY`).
+- **`setNumber`** rejects `NaN`/`±Infinity` (they don't round-trip). Numbers are
+  IEEE-754 doubles — for integers above 2^53 (e.g. snowflake IDs) use `setString`.
+- **`setItem`** rejects non-JSON-serializable values (`undefined`, functions,
+  symbols, circular refs, BigInt) with `INVALID_VALUE` instead of corrupting.
+- **`getBoolean`** is strict: only canonical `"true"`/`"false"` map; anything
+  else returns `null`.
+
+## Backends
+
+| Kind | Android | iOS | Encrypted | Use for |
+|---|---|---|---|---|
+| `secure` | AES-256-GCM (Keystore key) over SharedPreferences | Keychain (`kSecClassGenericPassword`) | ✅ hardware | JWTs, refresh/FCM tokens, secrets |
+| `async` | SharedPreferences | UserDefaults suite | ❌ | large / non-sensitive data |
+| `memory` | — (pure JS) | — (pure JS) | n/a | ephemeral cache, tests |
+| `fast` (sync) | SharedPreferences snapshot | UserDefaults snapshot | ❌ | **synchronous** state/flags/cache (MMKV-style) — via `createSyncStorage` |
+| `encrypted` | AES-256-GCM keys **and** values (Keystore key) over SQLite | AES-256-CBC + HMAC-SHA256 keys **and** values (key in Keychain) over SQLite | ✅ hardware-rooted key | large encrypted blobs / encrypted DB |
+| `sqlite` | SQLite key/value table | SQLite (`sqlite3`) key/value table | ❌ | larger datasets, SQL-backed key/value |
+
+All five backends are implemented. `encrypted` is a genuinely encrypted
+database: **both keys and values** are sealed with an authenticated cipher whose
+key is rooted in the hardware Keystore/Keychain, and rows are looked up by a
+deterministic HMAC token — so nothing readable touches disk, yet it still scales
+to large blobs and many entries. No SQLCipher dependency.
+
+### Synchronous (`fast`) store
+
+`createStorage` is async (correct for `secure` — never block the UI thread on
+Keystore crypto). For the MMKV-style **synchronous** need — persist/rehydrate,
+feature flags, hot-path UI state — use `createSyncStorage`:
+
+- It loads a snapshot **once**, then every `get`/`set` is **synchronous** in-JS
+  memory (the fastest possible read path — no per-call bridge crossing).
+- Writes apply to memory immediately and persist in the background, **coalesced**
+  per key; call `flush()` (e.g. on app background) for a durability barrier.
+- **Zero-load variant** — `createSyncStorageSync` hydrates the snapshot in a
+  single blocking native bulk-read and returns synchronously, so state is
+  available immediately at startup (e.g. before first render):
+
+  ```ts
+  import { createSyncStorageSync } from '@okint-digital/okint-rn-storage';
+  const fast = createSyncStorageSync({ backend: 'fast', namespace: 'app' });
+  const onboarded = fast.getBoolean('onboarded'); // sync, no await, no load step
+  ```
+
+- **JSI engine** — `createJSIStorage` installs a C++ `jsi::HostObject` and runs
+  every `get`/`set` **directly in C++ with no bridge serialization** — the
+  maximum-performance synchronous path, with no JS-memory snapshot:
+
+  ```ts
+  import { createJSIStorage } from '@okint-digital/okint-rn-storage';
+  const kv = createJSIStorage({ namespace: 'app' });
+  kv.setString('theme', 'dark');        // sync, in C++
+  const theme = kv.getString('theme');  // sync, in C++
+  ```
+
+  It installs lazily on first use and throws a clear error under remote JS
+  debugging (no JSI runtime) — fall back to `createSyncStorageSync` there.
+
+  Use `secure` for tokens — never a sync store.
+
+## Compared to alternatives
+
+| | okint-rn-storage | react-native-keychain | react-native-encrypted-storage | expo-secure-store | react-native-mmkv | async-storage |
+|---|---|---|---|---|---|---|
+| Secure (hardware-backed) | ✅ | ✅ | ✅ | ✅ | ❌ (key in JS) | ❌ |
+| Plain persistent store | ✅ (`async`) | ❌ | ❌ | ❌ | ✅ | ✅ |
+| Synchronous access | ✅ (`fast` snapshot · zero-load · **C++/JSI**) | ❌ | ❌ | ❌ | ✅ (mmap) | ❌ |
+| In-memory / test backend | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| One API, swappable backends | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| New Architecture (RN 0.81) | ✅ (interop) | ✅ (TurboModule) | ❌ unmaintained | ✅ | ✅ (v3 requires it) | ✅ |
+| Android crash-recovery¹ | ✅ | partial | ❌ | n/a | n/a | n/a |
+| Third-party runtime deps | none | none | none | Expo modules | MMKV (C++) | — |
+| Maintained (2026) | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ |
+
+¹ Encrypted Android stores can break after backup/restore, device transfer, or
+Keystore key invalidation — historically a **startup crash** (the gap that sank
+`react-native-encrypted-storage`, which wrapped EncryptedSharedPreferences). okint
+never crashes on this: a value that can't be decrypted with the current Keystore
+key simply reads back as `null`, so the app re-authenticates instead of dying on
+launch.
+
+**When to use what:** secrets/tokens → `secure` (async, hardware-backed). Big or
+non-sensitive data → `async`. Synchronous state/flags/cache → `fast` (via
+`createSyncStorage`) — this is okint's MMKV replacement, so you don't need a
+separate sync library. Tests/ephemeral → `memory`. One package, every store.
+
+## Errors
+
+All failures throw `OkintStorageError` with a stable `code`:
+`NATIVE_MODULE_MISSING` · `BACKEND_NOT_IMPLEMENTED` · `UNKNOWN_BACKEND` ·
+`PARSE_ERROR` · `INVALID_VALUE` · `NATIVE_ERROR`.
+
+```ts
+import { OkintStorageError } from '@okint-digital/okint-rn-storage';
+try { await auth.getItem('x'); }
+catch (e) { if (e instanceof OkintStorageError && e.code === 'PARSE_ERROR') { /* … */ } }
+```
+
+## Security & reliability
+
+- **Android `secure`** encrypts every value with **AES-256-GCM** under a
+  per-namespace, non-exportable **AndroidKeystore** key (hardware-backed where the
+  device offers it); ciphertext is held in plain SharedPreferences. This is the
+  same construction `EncryptedSharedPreferences` used internally — without the
+  now-deprecated `androidx.security:security-crypto`, and with **no third-party
+  dependency** (Tink, DataStore, etc.). A failed decrypt (restored backup,
+  invalidated key) returns `null` rather than crashing on launch.
+- **iOS `secure`** uses the Keychain with
+  `kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly` (not iCloud-synced, not in
+  encrypted backups, available to background tasks after first unlock) + the
+  data-protection keychain. Writes are add-or-update (`SecItemUpdate` →
+  `SecItemAdd`). The module is Objective-C for maximum build compatibility (no
+  Swift / `use_frameworks!` pitfalls).
+- **`encrypted`** authenticates as well as encrypts, and seals **both keys and
+  values**: Android AES-256-GCM (per-namespace Keystore key); iOS AES-256-CBC +
+  HMAC-SHA256 encrypt-then-MAC (96-byte key in the Keychain, constant-time MAC
+  check). Rows are addressed by a deterministic HMAC token, so the database holds
+  no readable key or value, yet scales to large blobs and many entries.
+- Keychain/Keystore are sized for secrets, not megabytes. Store tokens & keys in
+  `secure`; store bulk data in `async`, or encrypted bulk data in `encrypted`.
+- **Secrets are never logged** (avoids the class of bug behind CVE-2024-21668 in
+  another RN storage lib). Error messages carry key names + OS status codes only.
+
+### Threat model (read this)
+
+Hardware-backed Keystore/Keychain protects secrets **at rest on an uncompromised
+device**. It does **not** protect against: rooted/jailbroken devices, runtime
+instrumentation (Frida) or memory dumps of a running app, malware running as the
+same app, or a handed-over unlocked device. For high-value secrets, pair okint
+with root/jailbreak detection and short-lived tokens. okint encrypts on Android
+by **default** (unlike libraries that fall back to plaintext SharedPreferences).
+
+## License
+
+MIT © Okint Digital — see [LICENSE](./LICENSE).

package/android/build.gradle

@@ -0,0 +1,59 @@
+// okint-rn-storage — Android library build.
+// Relies on the host app's React Native Gradle setup for the Android Gradle
+// Plugin + Kotlin plugin classpath (RN 0.73+ convention), so no buildscript
+// block is needed here. Versions fall back to sensible defaults if the root
+// project doesn't expose them.
+
+apply plugin: "com.android.library"
+apply plugin: "org.jetbrains.kotlin.android"
+
+def safeExtGet(prop, fallback) {
+  rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
+}
+
+android {
+  namespace "com.okint.rnstorage"
+  compileSdkVersion safeExtGet("compileSdkVersion", 35)
+
+  defaultConfig {
+    minSdkVersion safeExtGet("minSdkVersion", 24)
+    targetSdkVersion safeExtGet("targetSdkVersion", 35)
+    consumerProguardFiles "proguard-rules.pro"
+    externalNativeBuild {
+      cmake {
+        cppFlags "-O2", "-frtti", "-fexceptions", "-std=c++17"
+      }
+    }
+  }
+
+  // Consume React Native's prefab (JSI) for the C++ fast-path engine.
+  buildFeatures {
+    prefab true
+  }
+
+  externalNativeBuild {
+    cmake {
+      path "src/main/jni/CMakeLists.txt"
+    }
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_17
+    targetCompatibility JavaVersion.VERSION_17
+  }
+
+  kotlinOptions {
+    jvmTarget = "17"
+  }
+}
+
+repositories {
+  mavenCentral()
+  google()
+}
+
+dependencies {
+  // Version supplied by the host app's React Native Gradle Plugin — do NOT pin.
+  // No other dependencies: all crypto is platform javax.crypto + AndroidKeystore.
+  implementation "com.facebook.react:react-android"
+}

package/android/proguard-rules.pro

@@ -0,0 +1,8 @@
+# okint-rn-storage — consumer ProGuard/R8 rules.
+# Keep the module + its JNI entry point so autolinking and the native
+# System.loadLibrary("okint") / nativeInstallJSI binding survive minification.
+
+-keep class com.okint.rnstorage.** { *; }
+-keepclasseswithmembernames class com.okint.rnstorage.** {
+  native <methods>;
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android" />

package/android/src/main/java/com/okint/rnstorage/OkintRnStorageModule.kt

@@ -0,0 +1,354 @@
+package com.okint.rnstorage
+
+import android.content.Context
+import android.content.SharedPreferences
+import android.database.sqlite.SQLiteDatabase
+import android.database.sqlite.SQLiteOpenHelper
+import android.security.keystore.KeyGenParameterSpec
+import android.security.keystore.KeyProperties
+import android.util.Base64
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.Promise
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReactContextBaseJavaModule
+import com.facebook.react.bridge.ReactMethod
+import com.facebook.react.bridge.WritableMap
+import java.security.KeyStore
+import java.util.concurrent.ConcurrentHashMap
+import javax.crypto.Cipher
+import javax.crypto.KeyGenerator
+import javax.crypto.Mac
+import javax.crypto.SecretKey
+import javax.crypto.spec.GCMParameterSpec
+
+/**
+ * okint-rn-storage — Android native module. One module, four stores, ZERO
+ * third-party dependencies (only the Android platform + AndroidKeystore):
+ *
+ *   - "secure"    → AES-256-GCM with a per-namespace, non-exportable
+ *                   AndroidKeystore key (hardware-backed where available);
+ *                   ciphertext lives in plain SharedPreferences. This is the
+ *                   construction EncryptedSharedPreferences used internally,
+ *                   without the deprecated androidx.security dependency. A
+ *                   decrypt failure (restored backup, invalidated key) returns
+ *                   null instead of crashing at launch — crash-recovery built in.
+ *   - "async"     → plain SharedPreferences (fast, unencrypted).
+ *   - "encrypted" → a fully-encrypted SQLite table: both KEYS and VALUES are
+ *                   AES-256-GCM encrypted; lookups use a deterministic HMAC
+ *                   token (Keystore HMAC key). No plaintext in the database — an
+ *                   encrypted DB with no SQLCipher dependency, sized for large
+ *                   blobs / many entries.
+ *   - "sqlite"    → plaintext values in a separate SQLite table.
+ *
+ * Plus a blocking-sync bulk read (`getEntriesSync`) and a C++/JSI fast-path
+ * installer (`installJSI`).
+ *
+ * NOTE: native code is written against the stable Android crypto/Keystore APIs
+ * and verified at app build time (no Gradle/NDK in the authoring environment).
+ */
+class OkintRnStorageModule(private val reactContext: ReactApplicationContext) :
+  ReactContextBaseJavaModule(reactContext) {
+
+  override fun getName(): String = NAME
+
+  // ── Dispatch ────────────────────────────────────────────────────────────────
+
+  @ReactMethod
+  fun setItem(service: String, key: String, value: String, store: String, promise: Promise) {
+    try {
+      when (store) {
+        STORE_SECURE -> securePrefs(service).edit().putString(key, encrypt(service, value)).commit()
+        STORE_ENCRYPTED -> encSet(service, key, value)
+        STORE_SQLITE -> sqliteSet(service, key, value)
+        else -> asyncPrefs(service).edit().putString(key, value).commit()
+      }
+      promise.resolve(null)
+    } catch (e: Exception) {
+      promise.reject("E_OKINT_SET", e.message, e)
+    }
+  }
+
+  @ReactMethod
+  fun getItem(service: String, key: String, store: String, promise: Promise) {
+    try {
+      promise.resolve(readOne(service, key, store))
+    } catch (e: Exception) {
+      promise.reject("E_OKINT_GET", e.message, e)
+    }
+  }
+
+  @ReactMethod
+  fun removeItem(service: String, key: String, store: String, promise: Promise) {
+    try {
+      when (store) {
+        STORE_SECURE -> securePrefs(service).edit().remove(key).commit()
+        STORE_ENCRYPTED -> encExec(service, "DELETE FROM ${encTable(service)} WHERE kt=?", arrayOf(token(service, key)))
+        STORE_SQLITE -> sqliteExec(service, "DELETE FROM ${kvTable(service)} WHERE k=?", arrayOf(key))
+        else -> asyncPrefs(service).edit().remove(key).commit()
+      }
+      promise.resolve(null)
+    } catch (e: Exception) {
+      promise.reject("E_OKINT_REMOVE", e.message, e)
+    }
+  }
+
+  @ReactMethod
+  fun clear(service: String, store: String, promise: Promise) {
+    try {
+      when (store) {
+        STORE_SECURE -> securePrefs(service).edit().clear().commit()
+        STORE_ENCRYPTED -> encExec(service, "DELETE FROM ${encTable(service)}", emptyArray())
+        STORE_SQLITE -> sqliteExec(service, "DELETE FROM ${kvTable(service)}", emptyArray())
+        else -> asyncPrefs(service).edit().clear().commit()
+      }
+      promise.resolve(null)
+    } catch (e: Exception) {
+      promise.reject("E_OKINT_CLEAR", e.message, e)
+    }
+  }
+
+  @ReactMethod
+  fun getAllKeys(service: String, store: String, promise: Promise) {
+    try {
+      val arr = Arguments.createArray()
+      for (k in allKeys(service, store)) arr.pushString(k)
+      promise.resolve(arr)
+    } catch (e: Exception) {
+      promise.reject("E_OKINT_KEYS", e.message, e)
+    }
+  }
+
+  /** Blocking-synchronous bulk read for the zero-load sync store. */
+  @ReactMethod(isBlockingSynchronousMethod = true)
+  fun getEntriesSync(service: String, store: String): WritableMap {
+    val map = Arguments.createMap()
+    try {
+      when (store) {
+        STORE_ASYNC -> for ((k, v) in asyncPrefs(service).all) {
+          if (v is String) map.putString(k, v)
+        }
+        else -> for (k in allKeys(service, store)) {
+          readOne(service, k, store)?.let { map.putString(k, it) }
+        }
+      }
+    } catch (ignored: Exception) {
+    }
+    return map
+  }
+
+  /** Install the C++/JSI fast-path engine. Returns false if the runtime is unreachable. */
+  @ReactMethod(isBlockingSynchronousMethod = true)
+  fun installJSI(): Boolean {
+    return try {
+      val ptr = reactContext.javaScriptContextHolder?.get() ?: return false
+      if (ptr == 0L) return false
+      nativeInstallJSI(ptr, reactContext.filesDir.absolutePath)
+      true
+    } catch (e: Throwable) {
+      false
+    }
+  }
+
+  private external fun nativeInstallJSI(jsiPtr: Long, dir: String)
+
+  // ── Shared read helpers ──────────────────────────────────────────────────────
+
+  private fun readOne(service: String, key: String, store: String): String? = when (store) {
+    STORE_SECURE -> securePrefs(service).getString(key, null)?.let { decryptOrNull(service, it) }
+    STORE_ENCRYPTED -> encGet(service, key)
+    STORE_SQLITE -> sqliteGet(service, key)
+    else -> asyncPrefs(service).getString(key, null)
+  }
+
+  private fun allKeys(service: String, store: String): List<String> = when (store) {
+    STORE_SECURE -> securePrefs(service).all.keys.toList()
+    STORE_ENCRYPTED -> encKeys(service)
+    STORE_SQLITE -> sqliteKeys(service)
+    else -> asyncPrefs(service).all.keys.toList()
+  }
+
+  // ── SharedPreferences (secure ciphertext + async plaintext) ──────────────────
+
+  private val prefsCache = ConcurrentHashMap<String, SharedPreferences>()
+
+  private fun prefs(name: String): SharedPreferences =
+    prefsCache.getOrPut(name) { reactContext.getSharedPreferences(name, Context.MODE_PRIVATE) }
+
+  private fun asyncPrefs(service: String): SharedPreferences = prefs("okint_$service")
+
+  private fun securePrefs(service: String): SharedPreferences = prefs("okint_secure_$service")
+
+  // ── Crypto core (AES-256-GCM + HMAC token, rooted in AndroidKeystore) ────────
+
+  private fun aesKey(service: String): SecretKey {
+    val alias = "okint_enckey_$service"
+    val ks = KeyStore.getInstance(ANDROID_KEYSTORE)
+    ks.load(null)
+    (ks.getKey(alias, null) as? SecretKey)?.let { return it }
+    val kg = KeyGenerator.getInstance(KeyProperties.KEY_ALGORITHM_AES, ANDROID_KEYSTORE)
+    kg.init(
+      KeyGenParameterSpec.Builder(alias, KeyProperties.PURPOSE_ENCRYPT or KeyProperties.PURPOSE_DECRYPT)
+        .setBlockModes(KeyProperties.BLOCK_MODE_GCM)
+        .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_NONE)
+        .setKeySize(256)
+        .build(),
+    )
+    return kg.generateKey()
+  }
+
+  private fun hmacKey(service: String): SecretKey {
+    val alias = "okint_enchmac_$service"
+    val ks = KeyStore.getInstance(ANDROID_KEYSTORE)
+    ks.load(null)
+    (ks.getKey(alias, null) as? SecretKey)?.let { return it }
+    val kg = KeyGenerator.getInstance(KeyProperties.KEY_ALGORITHM_HMAC_SHA256, ANDROID_KEYSTORE)
+    kg.init(KeyGenParameterSpec.Builder(alias, KeyProperties.PURPOSE_SIGN).build())
+    return kg.generateKey()
+  }
+
+  private fun token(service: String, key: String): String {
+    val mac = Mac.getInstance("HmacSHA256")
+    mac.init(hmacKey(service))
+    return Base64.encodeToString(mac.doFinal(key.toByteArray(Charsets.UTF_8)), Base64.NO_WRAP)
+  }
+
+  private fun encrypt(service: String, plaintext: String): String {
+    val cipher = Cipher.getInstance("AES/GCM/NoPadding")
+    cipher.init(Cipher.ENCRYPT_MODE, aesKey(service))
+    val iv = cipher.iv
+    val ct = cipher.doFinal(plaintext.toByteArray(Charsets.UTF_8))
+    val out = ByteArray(1 + iv.size + ct.size)
+    out[0] = iv.size.toByte()
+    System.arraycopy(iv, 0, out, 1, iv.size)
+    System.arraycopy(ct, 0, out, 1 + iv.size, ct.size)
+    return Base64.encodeToString(out, Base64.NO_WRAP)
+  }
+
+  private fun decrypt(service: String, b64: String): String {
+    val data = Base64.decode(b64, Base64.NO_WRAP)
+    val ivLen = data[0].toInt() and 0xFF
+    val iv = data.copyOfRange(1, 1 + ivLen)
+    val ct = data.copyOfRange(1 + ivLen, data.size)
+    val cipher = Cipher.getInstance("AES/GCM/NoPadding")
+    cipher.init(Cipher.DECRYPT_MODE, aesKey(service), GCMParameterSpec(128, iv))
+    return String(cipher.doFinal(ct), Charsets.UTF_8)
+  }
+
+  /** Decrypt that tolerates a lost/rotated key (restored backup) — returns null, never crashes. */
+  private fun decryptOrNull(service: String, b64: String): String? = try {
+    decrypt(service, b64)
+  } catch (e: Exception) {
+    null
+  }
+
+  // ── encrypted store (enc_ table: HMAC token + encrypted key + encrypted value)
+
+  private fun encTable(service: String): String = "enc_" + service.replace(Regex("[^A-Za-z0-9_]"), "_")
+
+  private fun ensureEnc(db: SQLiteDatabase, service: String) {
+    db.execSQL("CREATE TABLE IF NOT EXISTS ${encTable(service)} (kt TEXT PRIMARY KEY, ke TEXT NOT NULL, ve TEXT NOT NULL)")
+  }
+
+  @Synchronized
+  private fun encSet(service: String, key: String, value: String) {
+    val db = dbHelper.writableDatabase
+    ensureEnc(db, service)
+    db.execSQL(
+      "INSERT OR REPLACE INTO ${encTable(service)} (kt, ke, ve) VALUES (?, ?, ?)",
+      arrayOf(token(service, key), encrypt(service, key), encrypt(service, value)),
+    )
+  }
+
+  @Synchronized
+  private fun encGet(service: String, key: String): String? {
+    val db = dbHelper.readableDatabase
+    ensureEnc(db, service)
+    db.rawQuery("SELECT ve FROM ${encTable(service)} WHERE kt = ?", arrayOf(token(service, key))).use { c ->
+      return if (c.moveToFirst()) decryptOrNull(service, c.getString(0)) else null
+    }
+  }
+
+  @Synchronized
+  private fun encExec(service: String, sql: String, args: Array<String>) {
+    val db = dbHelper.writableDatabase
+    ensureEnc(db, service)
+    if (args.isEmpty()) db.execSQL(sql) else db.execSQL(sql, args)
+  }
+
+  @Synchronized
+  private fun encKeys(service: String): List<String> {
+    val db = dbHelper.readableDatabase
+    ensureEnc(db, service)
+    val keys = ArrayList<String>()
+    db.rawQuery("SELECT ke FROM ${encTable(service)}", emptyArray()).use { c ->
+      while (c.moveToNext()) decryptOrNull(service, c.getString(0))?.let { keys.add(it) }
+    }
+    return keys
+  }
+
+  // ── sqlite store (plaintext key/value table) ──────────────────────────────────
+
+  private val dbHelper: SQLiteOpenHelper by lazy {
+    object : SQLiteOpenHelper(reactContext, "okint_sqlite.db", null, 1) {
+      override fun onCreate(db: SQLiteDatabase) {}
+      override fun onUpgrade(db: SQLiteDatabase, oldV: Int, newV: Int) {}
+    }
+  }
+
+  private fun kvTable(service: String): String = "kv_" + service.replace(Regex("[^A-Za-z0-9_]"), "_")
+
+  private fun ensureKv(db: SQLiteDatabase, service: String) {
+    db.execSQL("CREATE TABLE IF NOT EXISTS ${kvTable(service)} (k TEXT PRIMARY KEY, v TEXT NOT NULL)")
+  }
+
+  @Synchronized
+  private fun sqliteSet(service: String, key: String, value: String) {
+    val db = dbHelper.writableDatabase
+    ensureKv(db, service)
+    db.execSQL("INSERT OR REPLACE INTO ${kvTable(service)} (k, v) VALUES (?, ?)", arrayOf(key, value))
+  }
+
+  @Synchronized
+  private fun sqliteGet(service: String, key: String): String? {
+    val db = dbHelper.readableDatabase
+    ensureKv(db, service)
+    db.rawQuery("SELECT v FROM ${kvTable(service)} WHERE k = ?", arrayOf(key)).use { c ->
+      return if (c.moveToFirst()) c.getString(0) else null
+    }
+  }
+
+  @Synchronized
+  private fun sqliteExec(service: String, sql: String, args: Array<String>) {
+    val db = dbHelper.writableDatabase
+    ensureKv(db, service)
+    if (args.isEmpty()) db.execSQL(sql) else db.execSQL(sql, args)
+  }
+
+  @Synchronized
+  private fun sqliteKeys(service: String): List<String> {
+    val db = dbHelper.readableDatabase
+    ensureKv(db, service)
+    val keys = ArrayList<String>()
+    db.rawQuery("SELECT k FROM ${kvTable(service)}", emptyArray()).use { c ->
+      while (c.moveToNext()) keys.add(c.getString(0))
+    }
+    return keys
+  }
+
+  companion object {
+    init {
+      try {
+        System.loadLibrary("okint")
+      } catch (ignored: Throwable) {
+        // JSI engine optional — installJSI() returns false if the lib is absent.
+      }
+    }
+
+    const val NAME = "OkintRnStorage"
+    private const val ANDROID_KEYSTORE = "AndroidKeyStore"
+    private const val STORE_SECURE = "secure"
+    private const val STORE_ASYNC = "async"
+    private const val STORE_ENCRYPTED = "encrypted"
+    private const val STORE_SQLITE = "sqlite"
+  }
+}

package/android/src/main/java/com/okint/rnstorage/OkintRnStoragePackage.kt

@@ -0,0 +1,14 @@
+package com.okint.rnstorage
+
+import com.facebook.react.ReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.uimanager.ViewManager
+
+class OkintRnStoragePackage : ReactPackage {
+  override fun createNativeModules(reactContext: ReactApplicationContext): List<NativeModule> =
+    listOf(OkintRnStorageModule(reactContext))
+
+  override fun createViewManagers(reactContext: ReactApplicationContext): List<ViewManager<*, *>> =
+    emptyList()
+}