@okint-digital/okint-rn-storage 0.6.0 → 0.7.0

package/README.md

@@ -41,6 +41,12 @@ await auth.setString('refreshToken', token);
 const token = await auth.getString('refreshToken');
 await auth.setItem('fcm', { token: t, platform: 'android' }); // JSON helper
 
+// High-value secrets → require Face ID / fingerprint / passcode to access.
+// Opt in per use case; the OS shows the auth prompt on read.
+const wallet = createStorage({ backend: 'secure', namespace: 'wallet', requireAuth: true });
+await wallet.setString('privateKey', pk);
+const pk = await wallet.getString('privateKey'); // ← triggers the biometric prompt
+
 // Plain persistent data → SharedPreferences / UserDefaults
 const prefs = createStorage({ backend: 'async', namespace: 'prefs' });
 await prefs.setBoolean('onboarded', true);
@@ -181,12 +187,21 @@ 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.
+  per-namespace, non-exportable **AndroidKeystore** key, preferring the dedicated
+  **StrongBox** secure element (Titan M / SE) and falling back to the TEE; 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.
+- **Biometric / device-credential gating (`requireAuth`)** — opt-in per secure
+  store. iOS binds the Keychain item to the **Secure Enclave** via `SecAccessControl`
+  (`.userPresence` — Face ID / Touch ID *or* passcode); the OS prompts automatically
+  on read. Android (API 28+) marks the AES key `setUserAuthenticationRequired` and
+  routes every read/write through a framework **`BiometricPrompt`** bound to the
+  operation's `Cipher` (strong biometric; per-operation). With no enrolled
+  authenticator, or on API < 28, gated calls reject rather than silently
+  downgrading. Off by default — nothing prompts unless you ask for it.
 - **iOS `secure`** uses the Keychain with
   `kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly` (not iCloud-synced, not in
   encrypted backups, available to background tasks after first unlock) + the

package/android/src/main/AndroidManifest.xml

@@ -1 +1,4 @@
-<manifest xmlns:android="http://schemas.android.com/apk/res/android" />
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+  <!-- Only used by the opt-in `requireAuth` secure store (BiometricPrompt). -->
+  <uses-permission android:name="android.permission.USE_BIOMETRIC" />
+</manifest>

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

@@ -4,6 +4,7 @@ import android.content.Context
 import android.content.SharedPreferences
 import android.database.sqlite.SQLiteDatabase
 import android.database.sqlite.SQLiteOpenHelper
+import android.os.Build
 import android.security.keystore.KeyGenParameterSpec
 import android.security.keystore.KeyProperties
 import android.util.Base64
@@ -54,7 +55,11 @@ class OkintRnStorageModule(private val reactContext: ReactApplicationContext) :
   // ── Dispatch ────────────────────────────────────────────────────────────────
 
   @ReactMethod
-  fun setItem(service: String, key: String, value: String, store: String, promise: Promise) {
+  fun setItem(service: String, key: String, value: String, store: String, requireAuth: Boolean, promise: Promise) {
+    if (store == STORE_SECURE && requireAuth) {
+      secureSetAuth(service, key, value, promise)
+      return
+    }
     try {
       when (store) {
         STORE_SECURE -> securePrefs(service).edit().putString(key, encrypt(service, value)).commit()
@@ -69,7 +74,11 @@ class OkintRnStorageModule(private val reactContext: ReactApplicationContext) :
   }
 
   @ReactMethod
-  fun getItem(service: String, key: String, store: String, promise: Promise) {
+  fun getItem(service: String, key: String, store: String, requireAuth: Boolean, promise: Promise) {
+    if (store == STORE_SECURE && requireAuth) {
+      secureGetAuth(service, key, promise)
+      return
+    }
     try {
       promise.resolve(readOne(service, key, store))
     } catch (e: Exception) {
@@ -180,30 +189,53 @@ class OkintRnStorageModule(private val reactContext: ReactApplicationContext) :
 
   // ── Crypto core (AES-256-GCM + HMAC token, rooted in AndroidKeystore) ────────
 
-  private fun aesKey(service: String): SecretKey {
-    val alias = "okint_enckey_$service"
+  private fun loadKey(alias: String): SecretKey? {
     val ks = KeyStore.getInstance(ANDROID_KEYSTORE)
     ks.load(null)
-    (ks.getKey(alias, null) as? SecretKey)?.let { return it }
+    return ks.getKey(alias, null) as? SecretKey
+  }
+
+  /**
+   * Generate a Keystore key, preferring the dedicated **StrongBox** secure
+   * element (Titan M / SE) when present and falling back to the TEE otherwise.
+   * Some devices advertise StrongBox but fail at generation time, so we catch
+   * broadly on the StrongBox attempt and retry without it — the documented
+   * pattern. Existing keys are loaded by alias first, so this never re-keys an
+   * install; only brand-new keys gain StrongBox backing.
+   */
+  private fun aesKey(service: String): SecretKey {
+    val alias = "okint_enckey_$service"
+    loadKey(alias)?.let { return it }
+    return generateAesKey(alias, strongBox = true) ?: generateAesKey(alias, strongBox = false)!!
+  }
+
+  private fun generateAesKey(alias: String, strongBox: Boolean): SecretKey? = try {
     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()
+    val builder = KeyGenParameterSpec.Builder(alias, KeyProperties.PURPOSE_ENCRYPT or KeyProperties.PURPOSE_DECRYPT)
+      .setBlockModes(KeyProperties.BLOCK_MODE_GCM)
+      .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_NONE)
+      .setKeySize(256)
+    if (strongBox && Build.VERSION.SDK_INT >= Build.VERSION_CODES.P) builder.setIsStrongBoxBacked(true)
+    kg.init(builder.build())
+    kg.generateKey()
+  } catch (e: Exception) {
+    if (strongBox) null else throw e
   }
 
   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 }
+    loadKey(alias)?.let { return it }
+    return generateHmacKey(alias, strongBox = true) ?: generateHmacKey(alias, strongBox = false)!!
+  }
+
+  private fun generateHmacKey(alias: String, strongBox: Boolean): SecretKey? = try {
     val kg = KeyGenerator.getInstance(KeyProperties.KEY_ALGORITHM_HMAC_SHA256, ANDROID_KEYSTORE)
-    kg.init(KeyGenParameterSpec.Builder(alias, KeyProperties.PURPOSE_SIGN).build())
-    return kg.generateKey()
+    val builder = KeyGenParameterSpec.Builder(alias, KeyProperties.PURPOSE_SIGN)
+    if (strongBox && Build.VERSION.SDK_INT >= Build.VERSION_CODES.P) builder.setIsStrongBoxBacked(true)
+    kg.init(builder.build())
+    kg.generateKey()
+  } catch (e: Exception) {
+    if (strongBox) null else throw e
   }
 
   private fun token(service: String, key: String): String {
@@ -241,6 +273,139 @@ class OkintRnStorageModule(private val reactContext: ReactApplicationContext) :
     null
   }
 
+  // ── secure + requireAuth (biometric-gated AES key, per-operation CryptoObject)
+  //
+  // Opt-in path (createStorage({ backend:'secure', requireAuth:true })). The AES
+  // key is `setUserAuthenticationRequired`, so every encrypt/decrypt must run
+  // through a framework BiometricPrompt bound to the operation's Cipher. Uses a
+  // distinct key alias so it never collides with the non-gated secure key;
+  // ciphertext lives in the same SharedPreferences file, so remove/clear/keys
+  // work unchanged. Strong biometric only (CryptoObject can't combine with
+  // device-credential); API 28+. NOTE: the BiometricPrompt UI cannot be
+  // exercised without a real device — this path is build-verified on-device.
+
+  private fun secureAuthAesKey(service: String): SecretKey {
+    val alias = "okint_secauth_$service"
+    loadKey(alias)?.let { return it }
+    return generateAuthAesKey(alias, strongBox = true) ?: generateAuthAesKey(alias, strongBox = false)!!
+  }
+
+  private fun generateAuthAesKey(alias: String, strongBox: Boolean): SecretKey? = try {
+    val kg = KeyGenerator.getInstance(KeyProperties.KEY_ALGORITHM_AES, ANDROID_KEYSTORE)
+    val builder = KeyGenParameterSpec.Builder(alias, KeyProperties.PURPOSE_ENCRYPT or KeyProperties.PURPOSE_DECRYPT)
+      .setBlockModes(KeyProperties.BLOCK_MODE_GCM)
+      .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_NONE)
+      .setKeySize(256)
+      .setUserAuthenticationRequired(true)
+    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
+      // Timeout 0 → every use requires a fresh auth via CryptoObject.
+      builder.setUserAuthenticationParameters(0, KeyProperties.AUTH_BIOMETRIC_STRONG)
+    }
+    if (strongBox && Build.VERSION.SDK_INT >= Build.VERSION_CODES.P) builder.setIsStrongBoxBacked(true)
+    kg.init(builder.build())
+    kg.generateKey()
+  } catch (e: Exception) {
+    if (strongBox) null else throw e
+  }
+
+  private fun secureSetAuth(service: String, key: String, value: String, promise: Promise) {
+    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.P) {
+      promise.reject("E_OKINT_AUTH", "requireAuth needs Android 9 (API 28)+")
+      return
+    }
+    try {
+      val cipher = Cipher.getInstance("AES/GCM/NoPadding")
+      cipher.init(Cipher.ENCRYPT_MODE, secureAuthAesKey(service))
+      authenticate(cipher, "Authenticate to save", promise) { authed ->
+        val iv = authed.iv
+        val ct = authed.doFinal(value.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)
+        securePrefs(service).edit().putString(key, Base64.encodeToString(out, Base64.NO_WRAP)).commit()
+        null
+      }
+    } catch (e: Exception) {
+      promise.reject("E_OKINT_SET", e.message, e)
+    }
+  }
+
+  private fun secureGetAuth(service: String, key: String, promise: Promise) {
+    val raw = securePrefs(service).getString(key, null)
+    if (raw == null) {
+      promise.resolve(null)
+      return
+    }
+    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.P) {
+      promise.reject("E_OKINT_AUTH", "requireAuth needs Android 9 (API 28)+")
+      return
+    }
+    try {
+      val data = Base64.decode(raw, 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, secureAuthAesKey(service), GCMParameterSpec(128, iv))
+      authenticate(cipher, "Authenticate to access", promise) { authed ->
+        String(authed.doFinal(ct), Charsets.UTF_8)
+      }
+    } catch (e: Exception) {
+      promise.reject("E_OKINT_GET", e.message, e)
+    }
+  }
+
+  /**
+   * Present a framework BiometricPrompt bound to [cipher]; on success run
+   * [onAuthed] with the authenticated cipher and resolve [promise] with its
+   * result. Runs on the UI thread (BiometricPrompt requirement).
+   */
+  @androidx.annotation.RequiresApi(Build.VERSION_CODES.P)
+  private fun authenticate(cipher: Cipher, title: String, promise: Promise, onAuthed: (Cipher) -> String?) {
+    val activity = currentActivity
+    if (activity == null) {
+      promise.reject("E_OKINT_AUTH", "No foreground Activity to present the authentication prompt")
+      return
+    }
+    activity.runOnUiThread {
+      try {
+        val executor = activity.mainExecutor
+        val builder = android.hardware.biometrics.BiometricPrompt.Builder(activity).setTitle(title)
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
+          builder.setAllowedAuthenticators(android.hardware.biometrics.BiometricManager.Authenticators.BIOMETRIC_STRONG)
+        } else {
+          builder.setNegativeButton("Cancel", executor) { _, _ ->
+            promise.reject("E_OKINT_AUTH_CANCELLED", "Authentication cancelled")
+          }
+        }
+        val prompt = builder.build()
+        val crypto = android.hardware.biometrics.BiometricPrompt.CryptoObject(cipher)
+        prompt.authenticate(
+          crypto,
+          android.os.CancellationSignal(),
+          executor,
+          object : android.hardware.biometrics.BiometricPrompt.AuthenticationCallback() {
+            override fun onAuthenticationSucceeded(result: android.hardware.biometrics.BiometricPrompt.AuthenticationResult) {
+              try {
+                val authedCipher = result.cryptoObject?.cipher ?: cipher
+                promise.resolve(onAuthed(authedCipher))
+              } catch (e: Exception) {
+                promise.reject("E_OKINT_AUTH_CRYPTO", e.message, e)
+              }
+            }
+
+            override fun onAuthenticationError(errorCode: Int, errString: CharSequence) {
+              promise.reject("E_OKINT_AUTH", errString.toString())
+            }
+          },
+        )
+      } catch (e: Exception) {
+        promise.reject("E_OKINT_AUTH", e.message, e)
+      }
+    }
+  }
+
   // ── encrypted store (enc_ table: HMAC token + encrypted key + encrypted value)
 
   private fun encTable(service: String): String = "enc_" + service.replace(Regex("[^A-Za-z0-9_]"), "_")

package/ios/OkintRnStorage.m

@@ -75,6 +75,26 @@ static OSStatus OkintKCSetData(NSString *scope, NSString *key, NSData *data) {
   return s;
 }
 
+/**
+ * Store a secret behind device-credential auth: the item is bound to the Secure
+ * Enclave via SecAccessControl (`.userPresence` — Face ID / Touch ID OR device
+ * passcode). The OS prompts automatically on READ; writing doesn't prompt. We
+ * delete-then-add so overwriting an existing gated item never triggers a prompt.
+ */
+static OSStatus OkintKCSetDataAuth(NSString *scope, NSString *key, NSData *data) {
+  SecAccessControlRef ac = SecAccessControlCreateWithFlags(
+      kCFAllocatorDefault,
+      kSecAttrAccessibleWhenUnlockedThisDeviceOnly,
+      kSecAccessControlUserPresence,
+      NULL);
+  if (ac == NULL) return errSecParam;
+  SecItemDelete((__bridge CFDictionaryRef)OkintKCQuery(scope, key));
+  NSMutableDictionary *add = OkintKCQuery(scope, key);
+  add[(__bridge id)kSecValueData] = data;
+  add[(__bridge id)kSecAttrAccessControl] = (__bridge_transfer id)ac; // supersedes kSecAttrAccessible
+  return SecItemAdd((__bridge CFDictionaryRef)add, NULL);
+}
+
 static NSData *OkintKCGetData(NSString *scope, NSString *key) {
   NSMutableDictionary *q = OkintKCQuery(scope, key);
   q[(__bridge id)kSecReturnData] = @YES;
@@ -86,6 +106,23 @@ static NSData *OkintKCGetData(NSString *scope, NSString *key) {
   return nil;
 }
 
+/**
+ * Read a gated secret. If the item carries an access-control (written via
+ * OkintKCSetDataAuth), the Keychain shows the auth UI automatically; `prompt`
+ * sets the reason string. On a plain item this behaves like OkintKCGetData.
+ */
+static NSData *OkintKCGetDataAuth(NSString *scope, NSString *key, NSString *prompt) {
+  NSMutableDictionary *q = OkintKCQuery(scope, key);
+  q[(__bridge id)kSecReturnData] = @YES;
+  q[(__bridge id)kSecMatchLimit] = (__bridge id)kSecMatchLimitOne;
+  if (prompt) q[(__bridge id)kSecUseOperationPrompt] = prompt;
+  CFTypeRef result = NULL;
+  if (SecItemCopyMatching((__bridge CFDictionaryRef)q, &result) == errSecSuccess) {
+    return (__bridge_transfer NSData *)result;
+  }
+  return nil;
+}
+
 #pragma mark - Crypto (encrypted store)
 
 static NSData *OkintRandom(size_t n) {
@@ -345,9 +382,11 @@ static NSDictionary *OkintEncAll(NSString *service) {
 
 #pragma mark - Read dispatch
 
-static NSString *OkintReadOne(NSString *service, NSString *key, NSString *store) {
+static NSString *OkintReadOne(NSString *service, NSString *key, NSString *store, BOOL requireAuth) {
   if ([store isEqualToString:@"secure"]) {
-    NSData *d = OkintKCGetData(OkintScope(@"secure", service), key);
+    NSData *d = requireAuth
+        ? OkintKCGetDataAuth(OkintScope(@"secure", service), key, @"Authenticate to access your saved data")
+        : OkintKCGetData(OkintScope(@"secure", service), key);
     return d ? [[NSString alloc] initWithData:d encoding:NSUTF8StringEncoding] : nil;
   }
   if ([store isEqualToString:@"encrypted"]) return OkintEncGet(service, key);
@@ -358,9 +397,13 @@ static NSString *OkintReadOne(NSString *service, NSString *key, NSString *store)
 #pragma mark - Methods
 
 RCT_EXPORT_METHOD(setItem:(NSString *)service key:(NSString *)key value:(NSString *)value store:(NSString *)store
+                  requireAuth:(BOOL)requireAuth
                   resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject) {
   if ([store isEqualToString:@"secure"]) {
-    OSStatus s = OkintKCSetData(OkintScope(@"secure", service), key, [value dataUsingEncoding:NSUTF8StringEncoding]);
+    NSData *data = [value dataUsingEncoding:NSUTF8StringEncoding];
+    OSStatus s = requireAuth
+        ? OkintKCSetDataAuth(OkintScope(@"secure", service), key, data)
+        : OkintKCSetData(OkintScope(@"secure", service), key, data);
     if (s == errSecSuccess) resolve([NSNull null]);
     else reject(@"E_OKINT_SET", [NSString stringWithFormat:@"Keychain set failed (%d)", (int)s], nil);
     return;
@@ -380,8 +423,9 @@ RCT_EXPORT_METHOD(setItem:(NSString *)service key:(NSString *)key value:(NSStrin
 }
 
 RCT_EXPORT_METHOD(getItem:(NSString *)service key:(NSString *)key store:(NSString *)store
+                  requireAuth:(BOOL)requireAuth
                   resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject) {
-  NSString *v = OkintReadOne(service, key, store);
+  NSString *v = OkintReadOne(service, key, store, requireAuth);
   resolve(v ?: [NSNull null]);
 }
 

package/lib/backends/native-backend.d.ts

@@ -15,7 +15,11 @@ export declare class NativeBackend implements StorageBackend {
     private readonly native;
     private readonly service;
     readonly kind: NativeStoreKind;
-    constructor(native: NativeOkintStorage, service: string, kind: NativeStoreKind);
+    /** Gate reads/writes behind device-credential auth (secure backend only). */
+    private readonly requireAuth;
+    constructor(native: NativeOkintStorage, service: string, kind: NativeStoreKind, 
+    /** Gate reads/writes behind device-credential auth (secure backend only). */
+    requireAuth?: boolean);
     getString(key: string): Promise<string | null>;
     setString(key: string, value: string): Promise<void>;
     remove(key: string): Promise<void>;

package/lib/backends/native-backend.js

@@ -18,14 +18,18 @@ class NativeBackend {
     native;
     service;
     kind;
-    constructor(native, service, kind) {
+    requireAuth;
+    constructor(native, service, kind, 
+    /** Gate reads/writes behind device-credential auth (secure backend only). */
+    requireAuth = false) {
         this.native = native;
         this.service = service;
         this.kind = kind;
+        this.requireAuth = requireAuth;
     }
     async getString(key) {
         try {
-            const v = await this.native.getItem(this.service, key, this.kind);
+            const v = await this.native.getItem(this.service, key, this.kind, this.requireAuth);
             return v ?? null;
         }
         catch (e) {
@@ -34,7 +38,7 @@ class NativeBackend {
     }
     async setString(key, value) {
         try {
-            await this.native.setItem(this.service, key, value, this.kind);
+            await this.native.setItem(this.service, key, value, this.kind, this.requireAuth);
         }
         catch (e) {
             throw wrap(e, `set "${key}"`);

package/lib/index.js

@@ -28,13 +28,15 @@ const DEFAULT_NAMESPACE = 'okint';
  */
 function createStorage(options) {
     const namespace = (0, validate_1.normalizeNamespace)(options.namespace, DEFAULT_NAMESPACE);
-    return new facade_1.StorageFacade(resolveBackend(options.backend, namespace));
+    return new facade_1.StorageFacade(resolveBackend(options.backend, namespace, options.requireAuth === true));
 }
-function resolveBackend(kind, namespace) {
+function resolveBackend(kind, namespace, requireAuth) {
     switch (kind) {
         case 'memory':
             return new memory_1.MemoryBackend('memory');
         case 'secure':
+            // `requireAuth` only gates the secure store (hardware-key crypto).
+            return new native_backend_1.NativeBackend((0, bridge_1.getNativeModule)(), namespace, kind, requireAuth);
         case 'async':
         case 'encrypted':
         case 'sqlite':

package/lib/types.d.ts

@@ -20,6 +20,23 @@ export interface OkintStorageOptions {
      * Defaults to `'okint'`.
      */
     namespace?: string;
+    /**
+     * **`secure` backend only.** Require device-credential / biometric
+     * authentication (Face ID, fingerprint, or device passcode) to access a
+     * secret. Off by default — set it per use case (e.g. gate a payment token but
+     * not a UI preference).
+     *
+     * - **iOS:** the Keychain item is bound to the Secure Enclave via
+     *   `SecAccessControl` (`.userPresence` — biometry *or* passcode). The OS
+     *   shows the auth prompt automatically on read; writes don't prompt.
+     * - **Android (API 28+):** the AES key is `setUserAuthenticationRequired`, so
+     *   reads *and* writes present a `BiometricPrompt` bound to the operation's
+     *   `Cipher`. On API < 28, or with no biometric/credential enrolled, calls
+     *   reject with `NATIVE_ERROR` rather than silently downgrading.
+     *
+     * Ignored by non-`secure` backends.
+     */
+    requireAuth?: boolean;
 }
 /**
  * Low-level backend contract. Everything is async (the secure/native backends
@@ -108,8 +125,8 @@ export interface SyncPersistence {
  * inject a fake implementation. `store` selects which native store to target.
  */
 export interface NativeOkintStorage {
-    setItem(service: string, key: string, value: string, store: NativeStoreKind): Promise<void>;
-    getItem(service: string, key: string, store: NativeStoreKind): Promise<string | null>;
+    setItem(service: string, key: string, value: string, store: NativeStoreKind, requireAuth: boolean): Promise<void>;
+    getItem(service: string, key: string, store: NativeStoreKind, requireAuth: boolean): Promise<string | null>;
     removeItem(service: string, key: string, store: NativeStoreKind): Promise<void>;
     clear(service: string, store: NativeStoreKind): Promise<void>;
     getAllKeys(service: string, store: NativeStoreKind): Promise<string[]>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@okint-digital/okint-rn-storage",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Vanilla, pluggable React Native storage — one API over swappable backends: hardware Keystore/Keychain (secure), AES-encrypted blobs (encrypted), SQLite, SharedPreferences/UserDefaults (async), a synchronous fast store, or in-memory.",
   "keywords": [
     "react-native",

package/src/backends/native-backend.ts

@@ -18,11 +18,13 @@ export class NativeBackend implements StorageBackend {
     private readonly native: NativeOkintStorage,
     private readonly service: string,
     readonly kind: NativeStoreKind,
+    /** Gate reads/writes behind device-credential auth (secure backend only). */
+    private readonly requireAuth: boolean = false,
   ) {}
 
   async getString(key: string): Promise<string | null> {
     try {
-      const v = await this.native.getItem(this.service, key, this.kind);
+      const v = await this.native.getItem(this.service, key, this.kind, this.requireAuth);
       return v ?? null;
     } catch (e) {
       throw wrap(e, `get "${key}"`);
@@ -31,7 +33,7 @@ export class NativeBackend implements StorageBackend {
 
   async setString(key: string, value: string): Promise<void> {
     try {
-      await this.native.setItem(this.service, key, value, this.kind);
+      await this.native.setItem(this.service, key, value, this.kind, this.requireAuth);
     } catch (e) {
       throw wrap(e, `set "${key}"`);
     }

package/src/index.ts

@@ -32,14 +32,16 @@ const DEFAULT_NAMESPACE = 'okint';
  */
 export function createStorage(options: OkintStorageOptions): OkintStorage {
   const namespace = normalizeNamespace(options.namespace, DEFAULT_NAMESPACE);
-  return new StorageFacade(resolveBackend(options.backend, namespace));
+  return new StorageFacade(resolveBackend(options.backend, namespace, options.requireAuth === true));
 }
 
-function resolveBackend(kind: BackendKind, namespace: string): StorageBackend {
+function resolveBackend(kind: BackendKind, namespace: string, requireAuth: boolean): StorageBackend {
   switch (kind) {
     case 'memory':
       return new MemoryBackend('memory');
     case 'secure':
+      // `requireAuth` only gates the secure store (hardware-key crypto).
+      return new NativeBackend(getNativeModule(), namespace, kind, requireAuth);
     case 'async':
     case 'encrypted':
     case 'sqlite':

package/src/types.ts

@@ -23,6 +23,23 @@ export interface OkintStorageOptions {
    * Defaults to `'okint'`.
    */
   namespace?: string;
+  /**
+   * **`secure` backend only.** Require device-credential / biometric
+   * authentication (Face ID, fingerprint, or device passcode) to access a
+   * secret. Off by default — set it per use case (e.g. gate a payment token but
+   * not a UI preference).
+   *
+   * - **iOS:** the Keychain item is bound to the Secure Enclave via
+   *   `SecAccessControl` (`.userPresence` — biometry *or* passcode). The OS
+   *   shows the auth prompt automatically on read; writes don't prompt.
+   * - **Android (API 28+):** the AES key is `setUserAuthenticationRequired`, so
+   *   reads *and* writes present a `BiometricPrompt` bound to the operation's
+   *   `Cipher`. On API < 28, or with no biometric/credential enrolled, calls
+   *   reject with `NATIVE_ERROR` rather than silently downgrading.
+   *
+   * Ignored by non-`secure` backends.
+   */
+  requireAuth?: boolean;
 }
 
 /**
@@ -141,8 +158,8 @@ export interface SyncPersistence {
  * inject a fake implementation. `store` selects which native store to target.
  */
 export interface NativeOkintStorage {
-  setItem(service: string, key: string, value: string, store: NativeStoreKind): Promise<void>;
-  getItem(service: string, key: string, store: NativeStoreKind): Promise<string | null>;
+  setItem(service: string, key: string, value: string, store: NativeStoreKind, requireAuth: boolean): Promise<void>;
+  getItem(service: string, key: string, store: NativeStoreKind, requireAuth: boolean): Promise<string | null>;
   removeItem(service: string, key: string, store: NativeStoreKind): Promise<void>;
   clear(service: string, store: NativeStoreKind): Promise<void>;
   getAllKeys(service: string, store: NativeStoreKind): Promise<string[]>;