@sigx/lynx-secure-storage 0.4.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Andreas Ekdahl
+
+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,191 @@
+# @sigx/lynx-secure-storage
+
+Encrypted at-rest key-value storage for sigx-lynx — iOS Keychain, Android Keystore + `EncryptedSharedPreferences`.
+
+For plaintext settings (theme, last-used tab, feature flags) use [`@sigx/lynx-storage`](../lynx-storage). Use this package for **credentials, refresh tokens, PII, recovery keys** — anything that must survive a casual filesystem dump or backup exfiltration.
+
+Pairs with [`@sigx/lynx-biometric`](../lynx-biometric) when you also need an explicit "unlock the app" gate; the `requireBiometric` option here gates the *individual key* via the OS Keychain / Keystore.
+
+- **iOS**: `kSecClassGenericPassword` items via the Keychain Services API. `kSecAccessControlBiometryCurrentSet` for biometric-gated keys; `kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly` otherwise — items are never included in iCloud / iTunes backups.
+- **Android**: AES-256-GCM via the Android Keystore. Non-biometric keys land in `EncryptedSharedPreferences` (`androidx.security:security-crypto`); biometric-gated keys use a per-key Keystore alias with `setUserAuthenticationRequired(true)` and a `BiometricPrompt.CryptoObject` on read.
+
+## Install
+
+```bash
+pnpm add @sigx/lynx-secure-storage
+```
+
+`sigx prebuild` auto-discovers the package, links the native module, adds the `androidx.security` + `androidx.biometric` dependencies, and adds `<uses-permission android:name="android.permission.USE_BIOMETRIC"/>` to the Android manifest.
+
+### Android Auto Backup
+
+`EncryptedSharedPreferences` files are included in Android Auto Backup by default. The data is encrypted but the master key is device-bound, so restoring to a new device produces unreadable blobs that the next `get()` call will fail on. **Recommended:** exclude both of this module's prefs files from backup.
+
+Create `android/app/src/main/res/xml/sigx_backup_rules.xml`:
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<full-backup-content>
+    <exclude domain="sharedpref" path="sigx_secure_storage_v1.xml" />
+    <exclude domain="sharedpref" path="sigx_secure_storage_biometric_v1.xml" />
+</full-backup-content>
+```
+
+And the Android 12+ equivalent at `android/app/src/main/res/xml/sigx_data_extraction_rules.xml`:
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<data-extraction-rules>
+    <cloud-backup>
+        <exclude domain="sharedpref" path="sigx_secure_storage_v1.xml" />
+        <exclude domain="sharedpref" path="sigx_secure_storage_biometric_v1.xml" />
+    </cloud-backup>
+    <device-transfer>
+        <exclude domain="sharedpref" path="sigx_secure_storage_v1.xml" />
+        <exclude domain="sharedpref" path="sigx_secure_storage_biometric_v1.xml" />
+    </device-transfer>
+</data-extraction-rules>
+```
+
+Wire both in your `AndroidManifest.xml`'s `<application>` element:
+
+```xml
+<application
+    android:fullBackupContent="@xml/sigx_backup_rules"
+    android:dataExtractionRules="@xml/sigx_data_extraction_rules"
+    …>
+```
+
+Biometric-gated keys are intrinsically safe — the Keystore alias can't be restored to a different device — but the encrypted blob's still useless on restore, so excluding both files keeps the user out of a confusing "stale ciphertext" state.
+
+## Usage
+
+```ts
+import { SecureStorage } from '@sigx/lynx-secure-storage';
+
+// Plain encrypted set/get — no biometric prompt.
+await SecureStorage.set('refresh_token', refreshToken);
+const value = await SecureStorage.get('refresh_token');
+
+// Biometric-gated key.
+await SecureStorage.set('access_token', accessToken, { requireBiometric: true });
+
+// Reading a biometric-gated key triggers Face ID / BiometricPrompt.
+const token = await SecureStorage.get('access_token', {
+    biometricPrompt: {
+        reason: 'Unlock your account',   // iOS LAContext / Android subtitle
+        title: 'Acme Bank',              // Android only — prompt title
+    },
+});
+
+// Cheap existence check (never decrypts, never prompts).
+if (await SecureStorage.hasKey('access_token')) { /* … */ }
+
+// Per-key delete + namespaced clear.
+await SecureStorage.delete('refresh_token');
+await SecureStorage.clear();   // wipes only THIS module's items
+```
+
+`get`, `set`, `delete`, and `clear` reject on failure — wrap them in try/catch when handling user-driven cancels (e.g. user cancelled biometric prompt). `hasKey` only rejects on infrastructure failure.
+
+## API
+
+| Method | Returns |
+|---|---|
+| `SecureStorage.set(key, value, opts?)` | `Promise<void>` |
+| `SecureStorage.get(key, opts?)` | `Promise<string \| null>` |
+| `SecureStorage.delete(key)` | `Promise<void>` |
+| `SecureStorage.clear()` | `Promise<void>` — only this module's keys |
+| `SecureStorage.hasKey(key)` | `Promise<boolean>` — no prompt, no decrypt |
+| `SecureStorage.isAvailable()` | `boolean` |
+
+`set` options:
+- `requireBiometric?: boolean` — gate this key with the OS biometric prompt.
+
+`get` options:
+- `biometricPrompt?: { reason: string; title?: string }` — strings shown on the OS prompt for biometric-gated keys. If omitted (or `reason` is empty), a generic `"Authenticate to read secure data"` default is used so the prompt still appears with a non-blank subtitle. On iOS the `reason` is passed via `kSecUseOperationPrompt`; on Android it becomes the `BiometricPrompt` subtitle.
+
+## Recipes
+
+### Access token + refresh token
+
+The common shape: a long-lived **refresh** token (no biometric gate, used at app start to mint a new access token) plus a short-lived **access** token (biometric-gated, read on every sensitive request).
+
+```ts
+import { SecureStorage } from '@sigx/lynx-secure-storage';
+
+async function onLoginSuccess(accessToken: string, refreshToken: string) {
+    // Refresh token: needed silently on cold start, so no prompt.
+    await SecureStorage.set('refresh_token', refreshToken);
+    // Access token: short-lived, prompt every time it's read.
+    await SecureStorage.set('access_token', accessToken, { requireBiometric: true });
+}
+
+async function getAccessTokenWithPrompt(): Promise<string | null> {
+    return SecureStorage.get('access_token', {
+        biometricPrompt: { reason: 'Unlock your account', title: 'Acme Bank' },
+    });
+}
+
+async function silentRefresh(): Promise<string | null> {
+    // No prompt — refresh_token has no requireBiometric flag.
+    return SecureStorage.get('refresh_token');
+}
+
+async function logout() {
+    await SecureStorage.delete('access_token');
+    await SecureStorage.delete('refresh_token');
+}
+```
+
+### Handle key invalidation after biometric enrollment changes
+
+Both platforms invalidate biometric-gated keys when the user adds or removes a biometric (iOS: `.biometryCurrentSet`; Android: `setInvalidatedByBiometricEnrollment(true)`). The stored blob remains on disk but `get()` rejects because the underlying key is gone. Treat this as "the user needs to sign in again":
+
+```ts
+async function readAccessToken(): Promise<string | null> {
+    try {
+        return await SecureStorage.get('access_token', {
+            biometricPrompt: { reason: 'Unlock your account' },
+        });
+    } catch (err) {
+        const msg = (err as Error).message;
+        // Android surfaces the underlying KeyPermanentlyInvalidatedException
+        // through the native error message we wrap as "Cipher init failed
+        // (key may be invalidated)". Detect it by substring.
+        const androidInvalidated =
+            /may be invalidated|KeyPermanentlyInvalidated/i.test(msg);
+        if (androidInvalidated) {
+            await SecureStorage.delete('access_token');
+            return null;   // app should send the user back to sign-in
+        }
+        throw err;
+    }
+}
+```
+
+**iOS caveat.** On iOS the Keychain returns `errSecAuthFailed` for both genuine biometric mismatch and "the biometric set changed since this item was stored" — the JS surface currently normalises both to `authenticationFailed`, so they can't be told apart from JS alone. Recommended approach: if `get()` for a biometric-gated key rejects with `authenticationFailed` and the user just retried, treat it the same as the Android invalidation path (delete + re-auth) rather than looping. A future module version will expose a richer `errorCode` field so the two cases can be distinguished cleanly.
+
+The same delete-then-re-auth pattern applies when the user disables biometrics entirely between launches.
+
+## Threat model
+
+**Protects against:**
+- Other apps reading the credential. Both Keychain (per-app entitlement) and Keystore (per-app alias namespace) enforce this at the OS level.
+- Casual device theft if `requireBiometric: true` is used — the encrypted blob is on disk but the key requires user presence to unwrap.
+- Backup exfiltration on iOS — all items use `…ThisDeviceOnly` accessibility, so they don't appear in iCloud or encrypted iTunes backups.
+- Filesystem inspection (e.g. `adb pull`, jailbroken backup) on values that aren't biometric-gated, because `EncryptedSharedPreferences` and the Keychain blob are encrypted at rest with a hardware-backed key.
+
+**Does NOT protect against:**
+- A jailbroken / rooted device with a determined attacker — Keychain and Keystore can be dumped offline. `requireBiometric: true` raises the bar (the attacker also needs to bypass biometric auth or extract the key from the secure element), but does not eliminate the risk.
+- Memory inspection while the app is running. Once `get` returns, the decrypted string lives in the JS heap.
+- Screen scraping, accessibility tree leakage, or screen recording. If you display the secret in a `<TextInput>`, treat it as already-public.
+- App-level data binding (state-management, dev-tools time-travel, error reporting). If you put the decrypted secret in a Redux store and ship Sentry breadcrumbs, you've leaked it.
+- An attacker who knows the device PIN if they can also defeat the biometric (e.g. with a registered fingerprint). The OS treats biometric + passcode equivalently in `LAPolicy.deviceOwnerAuthentication` / Android `DEVICE_CREDENTIAL`.
+- Android Auto Backup leaking non-biometric values to Google Drive unless you add an `<exclude>` rule (see Install). Biometric-gated values are bound to a Keystore alias that can't be restored to a different device.
+
+For "Strong" guarantees we always request the strongest available biometric class (iOS `.biometryCurrentSet`; Android `BIOMETRIC_STRONG`). Weaker face unlock sensors that don't meet `BIOMETRIC_STRONG` are reported as unavailable rather than silently downgraded.
+
+## Reference
+
+The showcase app's "Auth demo" screen (`examples/showcase/src/screens/AuthDemo.tsx`) demonstrates the full sign-in → encrypted store → biometric unlock → reveal flow.

package/android/com/sigx/securestorage/SecureStorageActivityHolder.kt

@@ -0,0 +1,22 @@
+package com.sigx.securestorage
+
+import androidx.fragment.app.FragmentActivity
+import java.lang.ref.WeakReference
+
+internal object SecureStorageActivityHolder {
+
+    private var ref: WeakReference<FragmentActivity>? = null
+
+    fun setActivity(activity: FragmentActivity) {
+        ref = WeakReference(activity)
+    }
+
+    fun clearIf(activity: Any) {
+        val current = ref?.get() ?: return
+        if (current === activity) {
+            ref = null
+        }
+    }
+
+    fun current(): FragmentActivity? = ref?.get()
+}

package/android/com/sigx/securestorage/SecureStorageActivityHook.kt

@@ -0,0 +1,35 @@
+package com.sigx.securestorage
+
+import android.app.Activity
+import android.os.Bundle
+import androidx.fragment.app.FragmentActivity
+
+/**
+ * Activity-lifecycle hook for `@sigx/lynx-secure-storage`.
+ *
+ * Discovered by the auto-linker via `signalx-module.json`'s
+ * `android.activityHook`. We need a [FragmentActivity] to drive
+ * `BiometricPrompt` when reading a key stored with
+ * `setUserAuthenticationRequired(true)`.
+ */
+object SecureStorageActivityHook {
+
+    @JvmStatic
+    fun onCreate(activity: Activity, savedInstanceState: Bundle?) {
+        if (activity is FragmentActivity) {
+            SecureStorageActivityHolder.setActivity(activity)
+        }
+    }
+
+    @JvmStatic
+    fun onResume(activity: Activity) {
+        if (activity is FragmentActivity) {
+            SecureStorageActivityHolder.setActivity(activity)
+        }
+    }
+
+    @JvmStatic
+    fun onPause(activity: Activity) {
+        SecureStorageActivityHolder.clearIf(activity)
+    }
+}

package/android/com/sigx/securestorage/SecureStorageModule.kt

@@ -0,0 +1,348 @@
+package com.sigx.securestorage
+
+import android.content.Context
+import android.content.SharedPreferences
+import android.os.Build
+import android.security.keystore.KeyGenParameterSpec
+import android.security.keystore.KeyProperties
+import android.util.Base64
+import androidx.biometric.BiometricManager
+import androidx.biometric.BiometricManager.Authenticators.BIOMETRIC_STRONG
+import androidx.biometric.BiometricPrompt
+import androidx.core.content.ContextCompat
+import androidx.security.crypto.EncryptedSharedPreferences
+import androidx.security.crypto.MasterKey
+import com.lynx.jsbridge.LynxMethod
+import com.lynx.jsbridge.LynxModule
+import com.lynx.react.bridge.Callback
+import com.lynx.react.bridge.JavaOnlyMap
+import com.lynx.react.bridge.ReadableMap
+import java.security.KeyStore
+import javax.crypto.Cipher
+import javax.crypto.KeyGenerator
+import javax.crypto.SecretKey
+import javax.crypto.spec.GCMParameterSpec
+
+/**
+ * Encrypted KV storage backed by Android Keystore.
+ *
+ * JS usage: `NativeModules.SecureStorage.<method>(...)`.
+ *
+ * Two storage paths:
+ *
+ * - **Without `requireBiometric`** — values stored in
+ *   `EncryptedSharedPreferences` (`sigx_secure_storage_v1.xml`). The master
+ *   key is hardware-backed via Keystore; values are AES-256-GCM encrypted
+ *   on disk.
+ *
+ * - **With `requireBiometric: true`** — a per-key Keystore alias is created
+ *   with `setUserAuthenticationRequired(true)` + biometric strong
+ *   authenticator. Encryption happens with a `Cipher` we initialise
+ *   ourselves; the IV and ciphertext are base64-stored in a plain
+ *   `SharedPreferences` (`sigx_secure_storage_biometric_v1.xml`). On
+ *   `get`, the `Cipher` is initialised in DECRYPT mode and authorised
+ *   through `BiometricPrompt.CryptoObject` before `doFinal`.
+ */
+class SecureStorageModule(context: Context) : LynxModule(context) {
+
+    companion object {
+        private const val ANDROID_KEYSTORE = "AndroidKeyStore"
+        private const val PLAIN_PREFS = "sigx_secure_storage_v1"
+        private const val BIOMETRIC_PREFS = "sigx_secure_storage_biometric_v1"
+        private const val KEY_ALIAS_PREFIX = "sigx.secure-storage."
+        private const val GCM_TAG_BITS = 128
+        // Marker prefix on the stored blob so a future format change can be
+        // detected and migrated. v1 = `${base64Iv}:${base64Ciphertext}`.
+        private const val BLOB_VERSION = "v1:"
+    }
+
+    private val plainPrefs: SharedPreferences by lazy { buildEncryptedPrefs() }
+    private val biometricPrefs: SharedPreferences by lazy {
+        mContext.getSharedPreferences(BIOMETRIC_PREFS, Context.MODE_PRIVATE)
+    }
+
+    @LynxMethod
+    fun set(key: String?, value: String?, options: ReadableMap?, callback: Callback?) {
+        if (key.isNullOrEmpty()) {
+            callback?.invoke(errorPayload("key is required")); return
+        }
+        if (value == null) {
+            callback?.invoke(errorPayload("value must be a string")); return
+        }
+        val requireBiometric = options?.takeIf { it.hasKey("requireBiometric") }
+            ?.getBoolean("requireBiometric") ?: false
+
+        try {
+            // A key transitioning between plain and biometric storage must
+            // be removed from the old bucket so `get` doesn't read stale
+            // data of the wrong shape.
+            if (requireBiometric) {
+                plainPrefs.edit().remove(key).apply()
+                writeBiometricValue(key, value)
+            } else {
+                removeBiometricValue(key)
+                plainPrefs.edit().putString(key, value).apply()
+            }
+            callback?.invoke(JavaOnlyMap().apply { putBoolean("ok", true) })
+        } catch (e: Exception) {
+            callback?.invoke(errorPayload("set failed: ${e.message ?: e.javaClass.simpleName}"))
+        }
+    }
+
+    @LynxMethod
+    fun get(key: String?, options: ReadableMap?, callback: Callback?) {
+        if (key.isNullOrEmpty()) {
+            callback?.invoke(errorPayload("key is required")); return
+        }
+        try {
+            // Biometric items always win when both exist — we removed the
+            // plain entry on `set` so this is also the only possibility.
+            if (biometricPrefs.contains(key)) {
+                decryptBiometricValue(key, options, callback)
+                return
+            }
+            val value = plainPrefs.getString(key, null)
+            val result = JavaOnlyMap()
+            if (value == null) result.putNull("value") else result.putString("value", value)
+            callback?.invoke(result)
+        } catch (e: Exception) {
+            callback?.invoke(errorPayload("get failed: ${e.message ?: e.javaClass.simpleName}"))
+        }
+    }
+
+    @LynxMethod
+    fun delete(key: String?, callback: Callback?) {
+        if (key.isNullOrEmpty()) {
+            callback?.invoke(errorPayload("key is required")); return
+        }
+        try {
+            plainPrefs.edit().remove(key).apply()
+            removeBiometricValue(key)
+            callback?.invoke(JavaOnlyMap().apply { putBoolean("ok", true) })
+        } catch (e: Exception) {
+            callback?.invoke(errorPayload("delete failed: ${e.message ?: e.javaClass.simpleName}"))
+        }
+    }
+
+    @LynxMethod
+    fun clear(callback: Callback?) {
+        try {
+            plainPrefs.edit().clear().apply()
+            val keystore = KeyStore.getInstance(ANDROID_KEYSTORE).apply { load(null) }
+            biometricPrefs.all.keys.toList().forEach { key ->
+                runCatching { keystore.deleteEntry(keyAlias(key)) }
+            }
+            biometricPrefs.edit().clear().apply()
+            callback?.invoke(JavaOnlyMap().apply { putBoolean("ok", true) })
+        } catch (e: Exception) {
+            callback?.invoke(errorPayload("clear failed: ${e.message ?: e.javaClass.simpleName}"))
+        }
+    }
+
+    @LynxMethod
+    fun hasKey(key: String?, callback: Callback?) {
+        if (key.isNullOrEmpty()) {
+            callback?.invoke(JavaOnlyMap().apply { putBoolean("exists", false) }); return
+        }
+        val exists = plainPrefs.contains(key) || biometricPrefs.contains(key)
+        callback?.invoke(JavaOnlyMap().apply { putBoolean("exists", exists) })
+    }
+
+    // MARK: - EncryptedSharedPreferences (non-biometric path)
+
+    private fun buildEncryptedPrefs(): SharedPreferences {
+        val masterKey = MasterKey.Builder(mContext)
+            .setKeyScheme(MasterKey.KeyScheme.AES256_GCM)
+            .build()
+        return EncryptedSharedPreferences.create(
+            mContext,
+            PLAIN_PREFS,
+            masterKey,
+            EncryptedSharedPreferences.PrefKeyEncryptionScheme.AES256_SIV,
+            EncryptedSharedPreferences.PrefValueEncryptionScheme.AES256_GCM,
+        )
+    }
+
+    // MARK: - Biometric-gated path
+
+    private fun keyAlias(key: String): String = KEY_ALIAS_PREFIX + key
+
+    private fun writeBiometricValue(key: String, value: String) {
+        val secretKey = getOrCreateBiometricKey(key)
+        val cipher = Cipher.getInstance("AES/GCM/NoPadding").apply {
+            init(Cipher.ENCRYPT_MODE, secretKey)
+        }
+        val ciphertext = cipher.doFinal(value.toByteArray(Charsets.UTF_8))
+        val iv = cipher.iv
+        val blob = BLOB_VERSION +
+            Base64.encodeToString(iv, Base64.NO_WRAP) + ":" +
+            Base64.encodeToString(ciphertext, Base64.NO_WRAP)
+        biometricPrefs.edit().putString(key, blob).apply()
+    }
+
+    private fun decryptBiometricValue(key: String, options: ReadableMap?, callback: Callback?) {
+        val blob = biometricPrefs.getString(key, null)
+        if (blob == null || !blob.startsWith(BLOB_VERSION)) {
+            callback?.invoke(JavaOnlyMap().apply { putNull("value") }); return
+        }
+        val parts = blob.removePrefix(BLOB_VERSION).split(":")
+        if (parts.size != 2) {
+            callback?.invoke(errorPayload("corrupt biometric blob for key=$key")); return
+        }
+        val iv = Base64.decode(parts[0], Base64.NO_WRAP)
+        val ciphertext = Base64.decode(parts[1], Base64.NO_WRAP)
+
+        val secretKey = try {
+            loadBiometricKey(key)
+        } catch (e: Exception) {
+            callback?.invoke(errorPayload("Keystore key missing or invalidated: ${e.message}"))
+            return
+        }
+        if (secretKey == null) {
+            callback?.invoke(errorPayload("Keystore key missing for key=$key")); return
+        }
+
+        val cipher: Cipher = try {
+            Cipher.getInstance("AES/GCM/NoPadding").apply {
+                init(Cipher.DECRYPT_MODE, secretKey, GCMParameterSpec(GCM_TAG_BITS, iv))
+            }
+        } catch (e: Exception) {
+            // KeyPermanentlyInvalidatedException lives in android.security.keystore;
+            // catching by superclass avoids a hard dep and keeps the error generic.
+            callback?.invoke(errorPayload("Cipher init failed (key may be invalidated): ${e.message}"))
+            return
+        }
+
+        val activity = SecureStorageActivityHolder.current()
+        if (activity == null) {
+            callback?.invoke(errorPayload("No FragmentActivity in foreground for BiometricPrompt"))
+            return
+        }
+
+        val promptOpts = options?.takeIf { it.hasKey("biometricPrompt") }?.getMap("biometricPrompt")
+        val reason = promptOpts?.takeIf { it.hasKey("reason") }?.getString("reason")
+            ?.takeIf { it.isNotEmpty() } ?: "Authenticate to read secure data"
+        val title = promptOpts?.takeIf { it.hasKey("title") }?.getString("title")
+            ?.takeIf { it.isNotEmpty() } ?: "Authenticate"
+
+        val promptInfo = BiometricPrompt.PromptInfo.Builder()
+            .setTitle(title)
+            .setSubtitle(reason)
+            .setAllowedAuthenticators(BIOMETRIC_STRONG)
+            .setNegativeButtonText("Cancel")
+            .build()
+
+        // Up-front canAuthenticate check — surfaces NO_HARDWARE, NONE_ENROLLED,
+        // SECURITY_UPDATE_REQUIRED etc. as a clean error instead of letting
+        // BiometricPrompt fail mid-flow. Genuine "SUCCESS but still fails" cases
+        // (rare hardware bugs) are caught by the try/catch around
+        // prompt.authenticate below.
+        val canAuth = BiometricManager.from(mContext).canAuthenticate(BIOMETRIC_STRONG)
+        if (canAuth != BiometricManager.BIOMETRIC_SUCCESS) {
+            callback?.invoke(errorPayload("Biometrics unavailable (canAuthenticate=$canAuth)"))
+            return
+        }
+
+        val executor = ContextCompat.getMainExecutor(mContext)
+        val prompt = BiometricPrompt(
+            activity, executor,
+            object : BiometricPrompt.AuthenticationCallback() {
+                override fun onAuthenticationSucceeded(result: BiometricPrompt.AuthenticationResult) {
+                    val authedCipher = result.cryptoObject?.cipher
+                    if (authedCipher == null) {
+                        callback?.invoke(errorPayload("BiometricPrompt returned no Cipher"))
+                        return
+                    }
+                    try {
+                        val plaintext = authedCipher.doFinal(ciphertext)
+                        callback?.invoke(JavaOnlyMap().apply {
+                            putString("value", String(plaintext, Charsets.UTF_8))
+                        })
+                    } catch (e: Exception) {
+                        callback?.invoke(errorPayload("Decrypt failed: ${e.message}"))
+                    }
+                }
+
+                override fun onAuthenticationError(errorCode: Int, errString: CharSequence) {
+                    val mapped = when (errorCode) {
+                        BiometricPrompt.ERROR_USER_CANCELED,
+                        BiometricPrompt.ERROR_NEGATIVE_BUTTON -> "userCancel"
+                        BiometricPrompt.ERROR_LOCKOUT,
+                        BiometricPrompt.ERROR_LOCKOUT_PERMANENT -> "biometryLockout"
+                        else -> "authenticationFailed"
+                    }
+                    callback?.invoke(errorPayload(mapped))
+                }
+
+                override fun onAuthenticationFailed() {
+                    // Single failed attempt — prompt stays up. Don't invoke.
+                }
+            },
+        )
+
+        try {
+            prompt.authenticate(promptInfo, BiometricPrompt.CryptoObject(cipher))
+        } catch (e: Exception) {
+            callback?.invoke(errorPayload("BiometricPrompt.authenticate failed: ${e.message}"))
+        }
+    }
+
+    private fun removeBiometricValue(key: String) {
+        if (biometricPrefs.contains(key)) {
+            biometricPrefs.edit().remove(key).apply()
+        }
+        runCatching {
+            val keystore = KeyStore.getInstance(ANDROID_KEYSTORE).apply { load(null) }
+            if (keystore.containsAlias(keyAlias(key))) {
+                keystore.deleteEntry(keyAlias(key))
+            }
+        }
+    }
+
+    private fun loadBiometricKey(key: String): SecretKey? {
+        val keystore = KeyStore.getInstance(ANDROID_KEYSTORE).apply { load(null) }
+        return keystore.getKey(keyAlias(key), null) as? SecretKey
+    }
+
+    private fun getOrCreateBiometricKey(key: String): SecretKey {
+        val alias = keyAlias(key)
+        val existing = runCatching { loadBiometricKey(key) }.getOrNull()
+        if (existing != null) return existing
+
+        val keyGen = KeyGenerator.getInstance(KeyProperties.KEY_ALGORITHM_AES, ANDROID_KEYSTORE)
+        val specBuilder = 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) {
+            specBuilder.setUserAuthenticationParameters(0, KeyProperties.AUTH_BIOMETRIC_STRONG)
+        } else {
+            // Pre-API 30 only has the legacy timeout-seconds API. `-1`
+            // means "biometric required for every cryptographic operation"
+            // (positive values would let one auth cover N seconds of
+            // subsequent uses, which is not what we want for a credential
+            // store). `0` is not valid for this setter.
+            @Suppress("DEPRECATION")
+            specBuilder.setUserAuthenticationValidityDurationSeconds(-1)
+        }
+
+        // `setInvalidatedByBiometricEnrollment` invalidates the key if the
+        // user adds or removes a fingerprint/face — matches iOS's
+        // `.biometryCurrentSet` semantic. Callers must handle the
+        // "key invalidated" error and re-authenticate to re-create.
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.N) {
+            specBuilder.setInvalidatedByBiometricEnrollment(true)
+        }
+
+        keyGen.init(specBuilder.build())
+        return keyGen.generateKey()
+    }
+
+    private fun errorPayload(message: String): JavaOnlyMap =
+        JavaOnlyMap().apply { putString("error", message) }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { SecureStorage } from './secure-storage.js';
+export type { SecureStorageSetOptions, SecureStorageGetOptions, SecureStorageBiometricPrompt, } from './secure-storage.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,YAAY,EACR,uBAAuB,EACvB,uBAAuB,EACvB,4BAA4B,GAC/B,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { SecureStorage } from './secure-storage.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/secure-storage.d.ts

@@ -0,0 +1,92 @@
+export interface SecureStorageSetOptions {
+    /**
+     * When true, the OS will require biometric authentication on every
+     * subsequent `get` of this key.
+     *
+     * - iOS: stored with `kSecAccessControlBiometryCurrentSet`. The OS shows
+     *   the Face ID / Touch ID prompt automatically inside the Keychain
+     *   query — no extra JS call is needed.
+     * - Android: the key is generated with
+     *   `setUserAuthenticationRequired(true)`. `get` must drive a
+     *   `BiometricPrompt` to authorise the `Cipher`, which is why
+     *   [SecureStorageGetOptions] exposes `biometricPrompt`.
+     */
+    requireBiometric?: boolean;
+}
+export interface SecureStorageBiometricPrompt {
+    /** iOS: localizedReason for LAContext. Android: prompt subtitle. */
+    reason: string;
+    /** Android only — prompt title. Defaults to "Authenticate". */
+    title?: string;
+}
+export interface SecureStorageGetOptions {
+    /**
+     * Required when the key was stored with `requireBiometric: true`.
+     * Android needs the strings to render `BiometricPrompt`; iOS only uses
+     * `reason` (the OS prompt title is fixed).
+     */
+    biometricPrompt?: SecureStorageBiometricPrompt;
+}
+/**
+ * Encrypted at-rest key-value storage — iOS Keychain, Android Keystore +
+ * EncryptedSharedPreferences.
+ *
+ * For plaintext settings use [`@sigx/lynx-storage`](../lynx-storage). Use
+ * this package for credentials, refresh tokens, PII, and anything else
+ * that must survive a casual filesystem dump.
+ *
+ * Pairs with [`@sigx/lynx-biometric`](../lynx-biometric) when you also need
+ * an explicit auth gate (e.g. unlock-on-launch). The `requireBiometric`
+ * flag here gates the *individual key* via the OS Keychain / Keystore;
+ * use lynx-biometric for the broader "unlock the app" flow.
+ *
+ * @example
+ * ```ts
+ * import { SecureStorage } from '@sigx/lynx-secure-storage';
+ *
+ * await SecureStorage.set('access_token', token, { requireBiometric: true });
+ *
+ * const value = await SecureStorage.get('access_token', {
+ *     biometricPrompt: { reason: 'Unlock your account', title: 'Acme Bank' },
+ * });
+ * ```
+ */
+export declare const SecureStorage: {
+    /**
+     * Store an encrypted string. Overwrites any existing value for `key`.
+     * Setting `requireBiometric: true` makes future `get` calls prompt for
+     * biometrics; the `set` call itself never prompts.
+     */
+    readonly set: (key: string, value: string, opts?: SecureStorageSetOptions) => Promise<void>;
+    /**
+     * Read an encrypted string. Returns `null` if the key is not present.
+     *
+     * For keys stored with `requireBiometric: true`, the OS shows a prompt
+     * before the value is returned. Pass `biometricPrompt.reason` to set
+     * the displayed string; if omitted (or empty), a generic
+     * "Authenticate to read secure data" default is used so the prompt
+     * still appears.
+     *
+     * - **iOS**: `reason` is passed as `kSecUseOperationPrompt` on the
+     *   Keychain query.
+     * - **Android**: `reason` becomes the `BiometricPrompt` subtitle and
+     *   `title` (or "Authenticate") becomes the prompt title.
+     */
+    readonly get: (key: string, opts?: SecureStorageGetOptions) => Promise<string | null>;
+    /** Delete a single key. No-op if the key doesn't exist. */
+    readonly delete: (key: string) => Promise<void>;
+    /**
+     * Delete every key owned by this module's service identifier. Does NOT
+     * touch other apps' Keychain items, nor other Lynx packages'
+     * SharedPreferences.
+     */
+    readonly clear: () => Promise<void>;
+    /**
+     * Check whether a key is present without decrypting it (no biometric
+     * prompt). Safe to call on every render.
+     */
+    readonly hasKey: (key: string) => Promise<boolean>;
+    /** Whether the native module is wired in the current build. */
+    readonly isAvailable: () => boolean;
+};
+//# sourceMappingURL=secure-storage.d.ts.map

package/dist/secure-storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secure-storage.d.ts","sourceRoot":"","sources":["../src/secure-storage.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,uBAAuB;IACpC;;;;;;;;;;;OAWG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,WAAW,4BAA4B;IACzC,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,uBAAuB;IACpC;;;;OAIG;IACH,eAAe,CAAC,EAAE,4BAA4B,CAAC;CAClD;AAiBD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,aAAa;IACtB;;;;OAIG;aACG,GAAG,QACA,MAAM,SACJ,MAAM,SACP,uBAAuB,KAC9B,OAAO,CAAC,IAAI,CAAC;IAWhB;;;;;;;;;;;;;OAaG;aACG,GAAG,QAAM,MAAM,SAAQ,uBAAuB,KAAQ,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAalF,2DAA2D;aACrD,MAAM,QAAM,MAAM,KAAG,OAAO,CAAC,IAAI,CAAC;IAQxC;;;;OAIG;aACG,KAAK,QAAI,OAAO,CAAC,IAAI,CAAC;IAK5B;;;OAGG;aACG,MAAM,QAAM,MAAM,KAAG,OAAO,CAAC,OAAO,CAAC;IAa3C,+DAA+D;aAC/D,WAAW,QAAI,OAAO;CAGhB,CAAC"}

package/dist/secure-storage.js

@@ -0,0 +1,108 @@
+import { callAsync, isModuleAvailable } from '@sigx/lynx-core';
+const MODULE = 'SecureStorage';
+function unwrap(result, action) {
+    if (!result || result.error) {
+        throw new Error(`[@sigx/lynx-secure-storage] ${action} failed: ${result?.error ?? 'unknown error'}`);
+    }
+}
+/**
+ * Encrypted at-rest key-value storage — iOS Keychain, Android Keystore +
+ * EncryptedSharedPreferences.
+ *
+ * For plaintext settings use [`@sigx/lynx-storage`](../lynx-storage). Use
+ * this package for credentials, refresh tokens, PII, and anything else
+ * that must survive a casual filesystem dump.
+ *
+ * Pairs with [`@sigx/lynx-biometric`](../lynx-biometric) when you also need
+ * an explicit auth gate (e.g. unlock-on-launch). The `requireBiometric`
+ * flag here gates the *individual key* via the OS Keychain / Keystore;
+ * use lynx-biometric for the broader "unlock the app" flow.
+ *
+ * @example
+ * ```ts
+ * import { SecureStorage } from '@sigx/lynx-secure-storage';
+ *
+ * await SecureStorage.set('access_token', token, { requireBiometric: true });
+ *
+ * const value = await SecureStorage.get('access_token', {
+ *     biometricPrompt: { reason: 'Unlock your account', title: 'Acme Bank' },
+ * });
+ * ```
+ */
+export const SecureStorage = {
+    /**
+     * Store an encrypted string. Overwrites any existing value for `key`.
+     * Setting `requireBiometric: true` makes future `get` calls prompt for
+     * biometrics; the `set` call itself never prompts.
+     */
+    async set(key, value, opts = {}) {
+        if (typeof key !== 'string' || key.length === 0) {
+            throw new Error('[@sigx/lynx-secure-storage] key must be a non-empty string');
+        }
+        if (typeof value !== 'string') {
+            throw new Error('[@sigx/lynx-secure-storage] value must be a string');
+        }
+        const result = await callAsync(MODULE, 'set', key, value, opts);
+        unwrap(result, `set(${key})`);
+    },
+    /**
+     * Read an encrypted string. Returns `null` if the key is not present.
+     *
+     * For keys stored with `requireBiometric: true`, the OS shows a prompt
+     * before the value is returned. Pass `biometricPrompt.reason` to set
+     * the displayed string; if omitted (or empty), a generic
+     * "Authenticate to read secure data" default is used so the prompt
+     * still appears.
+     *
+     * - **iOS**: `reason` is passed as `kSecUseOperationPrompt` on the
+     *   Keychain query.
+     * - **Android**: `reason` becomes the `BiometricPrompt` subtitle and
+     *   `title` (or "Authenticate") becomes the prompt title.
+     */
+    async get(key, opts = {}) {
+        if (typeof key !== 'string' || key.length === 0) {
+            throw new Error('[@sigx/lynx-secure-storage] key must be a non-empty string');
+        }
+        const result = await callAsync(MODULE, 'get', key, opts);
+        if (result?.error) {
+            throw new Error(`[@sigx/lynx-secure-storage] get(${key}) failed: ${result.error}`);
+        }
+        return result?.value ?? null;
+    },
+    /** Delete a single key. No-op if the key doesn't exist. */
+    async delete(key) {
+        if (typeof key !== 'string' || key.length === 0) {
+            throw new Error('[@sigx/lynx-secure-storage] key must be a non-empty string');
+        }
+        const result = await callAsync(MODULE, 'delete', key);
+        unwrap(result, `delete(${key})`);
+    },
+    /**
+     * Delete every key owned by this module's service identifier. Does NOT
+     * touch other apps' Keychain items, nor other Lynx packages'
+     * SharedPreferences.
+     */
+    async clear() {
+        const result = await callAsync(MODULE, 'clear');
+        unwrap(result, 'clear');
+    },
+    /**
+     * Check whether a key is present without decrypting it (no biometric
+     * prompt). Safe to call on every render.
+     */
+    async hasKey(key) {
+        if (typeof key !== 'string' || key.length === 0) {
+            return false;
+        }
+        const result = await callAsync(MODULE, 'hasKey', key);
+        if (result?.error) {
+            throw new Error(`[@sigx/lynx-secure-storage] hasKey(${key}) failed: ${result.error}`);
+        }
+        return result?.exists === true;
+    },
+    /** Whether the native module is wired in the current build. */
+    isAvailable() {
+        return isModuleAvailable(MODULE);
+    },
+};
+//# sourceMappingURL=secure-storage.js.map

package/dist/secure-storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secure-storage.js","sourceRoot":"","sources":["../src/secure-storage.ts"],"names":[],"mappings":"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"}

package/ios/SecureStorageModule.swift

@@ -0,0 +1,197 @@
+import Foundation
+import Lynx
+import Security
+
+/// Encrypted KV storage backed by the iOS Keychain.
+///
+/// JS usage: `NativeModules.SecureStorage.<method>(...)`.
+///
+/// All items are stored as `kSecClassGenericPassword` with a per-bundle
+/// service identifier. Items requested with `requireBiometric: true` are
+/// stored with a `SecAccessControl` of `.biometryCurrentSet`, which causes
+/// `SecItemCopyMatching` to show the OS biometric prompt automatically on
+/// read. Non-biometric items use `kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly`
+/// so they never appear in iCloud or encrypted iTunes backups.
+class SecureStorageModule: NSObject, LynxModule {
+
+    @objc static var name: String { "SecureStorage" }
+
+    @objc static var methodLookup: [String: String] {
+        [
+            "set": NSStringFromSelector(#selector(set(_:value:options:callback:))),
+            "get": NSStringFromSelector(#selector(get(_:options:callback:))),
+            "delete": NSStringFromSelector(#selector(delete(_:callback:))),
+            "clear": NSStringFromSelector(#selector(clear(_:))),
+            "hasKey": NSStringFromSelector(#selector(hasKey(_:callback:))),
+        ]
+    }
+
+    required override init() { super.init() }
+    required init(param: Any) { super.init() }
+
+    private var service: String {
+        // Namespacing the service id with `.sigx.secure-storage` keeps our
+        // items separate from anything else the host app stores in the
+        // Keychain (other libraries, host SDKs).
+        let bundleId = Bundle.main.bundleIdentifier ?? "com.sigx.app"
+        return "\(bundleId).sigx.secure-storage"
+    }
+
+    @objc func set(
+        _ key: String?,
+        value: String?,
+        options: [String: Any]?,
+        callback: LynxCallbackBlock?,
+    ) {
+        guard let key = key, !key.isEmpty else {
+            callback?(["error": "key is required"])
+            return
+        }
+        guard let value = value, let data = value.data(using: .utf8) else {
+            callback?(["error": "value must be a string"])
+            return
+        }
+        let requireBiometric = (options?["requireBiometric"] as? Bool) ?? false
+
+        // Delete any prior entry under this key — `SecItemUpdate` can't
+        // change `kSecAttrAccessControl`, so we always wipe + add.
+        let baseQuery: [String: Any] = [
+            kSecClass as String: kSecClassGenericPassword,
+            kSecAttrService as String: service,
+            kSecAttrAccount as String: key,
+        ]
+        SecItemDelete(baseQuery as CFDictionary)
+
+        var addQuery: [String: Any] = baseQuery
+        addQuery[kSecValueData as String] = data
+
+        if requireBiometric {
+            var acError: Unmanaged<CFError>?
+            guard let access = SecAccessControlCreateWithFlags(
+                kCFAllocatorDefault,
+                kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly,
+                .biometryCurrentSet,
+                &acError,
+            ) else {
+                let err = acError?.takeRetainedValue() as Error?
+                callback?([
+                    "error": "Failed to create SecAccessControl: \(err?.localizedDescription ?? "unknown")"
+                ])
+                return
+            }
+            addQuery[kSecAttrAccessControl as String] = access
+        } else {
+            addQuery[kSecAttrAccessible as String] = kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly
+        }
+
+        let status = SecItemAdd(addQuery as CFDictionary, nil)
+        if status == errSecSuccess {
+            callback?(["ok": true])
+        } else {
+            callback?(["error": "SecItemAdd failed: \(status)"])
+        }
+    }
+
+    @objc func get(
+        _ key: String?,
+        options: [String: Any]?,
+        callback: LynxCallbackBlock?,
+    ) {
+        guard let key = key, !key.isEmpty else {
+            callback?(["error": "key is required"])
+            return
+        }
+
+        // The user-visible prompt string for a Keychain item with a
+        // biometric ACL goes on the query via `kSecUseOperationPrompt`,
+        // NOT on an LAContext (LAContext's `localizedReason` only feeds
+        // `evaluatePolicy`, not Keychain UI). For non-biometric items the
+        // prompt key is ignored.
+        let reason = (options?["biometricPrompt"] as? [String: Any])?["reason"] as? String
+        let prompt = (reason?.isEmpty == false ? reason : "Authenticate to read secure data")
+            ?? "Authenticate to read secure data"
+
+        let query: [String: Any] = [
+            kSecClass as String: kSecClassGenericPassword,
+            kSecAttrService as String: service,
+            kSecAttrAccount as String: key,
+            kSecReturnData as String: true,
+            kSecMatchLimit as String: kSecMatchLimitOne,
+            kSecUseOperationPrompt as String: prompt,
+        ]
+
+        var result: AnyObject?
+        let status = SecItemCopyMatching(query as CFDictionary, &result)
+
+        switch status {
+        case errSecSuccess:
+            if let data = result as? Data, let value = String(data: data, encoding: .utf8) {
+                callback?(["value": value])
+            } else {
+                callback?(["value": NSNull()])
+            }
+        case errSecItemNotFound:
+            callback?(["value": NSNull()])
+        case errSecUserCanceled, -128:
+            callback?(["error": "userCancel"])
+        case errSecAuthFailed:
+            callback?(["error": "authenticationFailed"])
+        default:
+            callback?(["error": "SecItemCopyMatching failed: \(status)"])
+        }
+    }
+
+    @objc func delete(_ key: String?, callback: LynxCallbackBlock?) {
+        guard let key = key, !key.isEmpty else {
+            callback?(["error": "key is required"])
+            return
+        }
+        let query: [String: Any] = [
+            kSecClass as String: kSecClassGenericPassword,
+            kSecAttrService as String: service,
+            kSecAttrAccount as String: key,
+        ]
+        let status = SecItemDelete(query as CFDictionary)
+        if status == errSecSuccess || status == errSecItemNotFound {
+            callback?(["ok": true])
+        } else {
+            callback?(["error": "SecItemDelete failed: \(status)"])
+        }
+    }
+
+    @objc func clear(_ callback: LynxCallbackBlock?) {
+        let query: [String: Any] = [
+            kSecClass as String: kSecClassGenericPassword,
+            kSecAttrService as String: service,
+        ]
+        let status = SecItemDelete(query as CFDictionary)
+        if status == errSecSuccess || status == errSecItemNotFound {
+            callback?(["ok": true])
+        } else {
+            callback?(["error": "SecItemDelete failed: \(status)"])
+        }
+    }
+
+    @objc func hasKey(_ key: String?, callback: LynxCallbackBlock?) {
+        guard let key = key, !key.isEmpty else {
+            callback?(["exists": false])
+            return
+        }
+        // `kSecUseAuthenticationUIFail` makes the query return without
+        // prompting when an ACL would normally require auth — we just want
+        // to know if the item exists, not to read it.
+        let query: [String: Any] = [
+            kSecClass as String: kSecClassGenericPassword,
+            kSecAttrService as String: service,
+            kSecAttrAccount as String: key,
+            kSecReturnData as String: false,
+            kSecMatchLimit as String: kSecMatchLimitOne,
+            kSecUseAuthenticationUI as String: kSecUseAuthenticationUIFail,
+        ]
+        let status = SecItemCopyMatching(query as CFDictionary, nil)
+        // errSecInteractionNotAllowed (-25308) means the item exists but
+        // needs UI we suppressed — count it as "exists".
+        let exists = status == errSecSuccess || status == -25308
+        callback?(["exists": exists])
+    }
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@sigx/lynx-secure-storage",
+  "version": "0.4.1",
+  "description": "Encrypted at-rest key-value storage for sigx-lynx (iOS Keychain, Android Keystore + EncryptedSharedPreferences)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./signalx-module.json": "./signalx-module.json"
+  },
+  "files": [
+    "dist",
+    "ios",
+    "android",
+    "signalx-module.json"
+  ],
+  "dependencies": {
+    "@sigx/lynx-core": "^0.4.1"
+  },
+  "devDependencies": {
+    "@typescript/native-preview": "7.0.0-dev.20260521.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.7"
+  },
+  "author": "Andreas Ekdahl",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/signalxjs/lynx.git",
+    "directory": "packages/lynx-secure-storage"
+  },
+  "homepage": "https://github.com/signalxjs/lynx/tree/main/packages/lynx-secure-storage",
+  "bugs": {
+    "url": "https://github.com/signalxjs/lynx/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "signalx",
+    "sigx",
+    "lynx",
+    "mobile",
+    "ios",
+    "android",
+    "secure-storage",
+    "keychain",
+    "keystore",
+    "encrypted-shared-preferences"
+  ],
+  "scripts": {
+    "build": "node ../../scripts/clean.mjs dist && tsgo",
+    "dev": "tsgo --watch",
+    "test": "vitest run",
+    "clean": "node ../../scripts/clean.mjs dist .turbo"
+  }
+}

package/signalx-module.json

@@ -0,0 +1,24 @@
+{
+    "name": "SecureStorage",
+    "package": "@sigx/lynx-secure-storage",
+    "description": "Encrypted key-value storage (iOS Keychain, Android Keystore + EncryptedSharedPreferences)",
+    "platforms": ["android", "ios"],
+    "ios": {
+        "moduleClass": "SecureStorageModule",
+        "sourceDir": "ios",
+        "methods": ["set", "get", "delete", "clear", "hasKey"]
+    },
+    "android": {
+        "moduleClass": "com.sigx.securestorage.SecureStorageModule",
+        "sourceDir": "android",
+        "activityHook": {
+            "class": "com.sigx.securestorage.SecureStorageActivityHook",
+            "methods": ["onCreate", "onResume", "onPause"]
+        },
+        "dependencies": [
+            "androidx.security:security-crypto:1.1.0-alpha06",
+            "androidx.biometric:biometric:1.2.0-alpha05"
+        ],
+        "permissions": ["android.permission.USE_BIOMETRIC"]
+    }
+}