react-native-security-suite 0.9.22 → 1.0.0-rc.1

package/README.md

@@ -4,7 +4,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Downloads](https://img.shields.io/npm/dm/react-native-security-suite.svg)](https://www.npmjs.com/package/react-native-security-suite)
 
-**Comprehensive security solutions for React Native applications** - Protect your mobile apps with advanced security features including root/jailbreak detection, SSL certificate pinning, encryption, secure storage, screenshot protection, and network monitoring.
+**Comprehensive security solutions for React Native applications** — Protect your mobile apps with root/jailbreak detection, SSL certificate pinning, RFC 7515 JWS request signing, hardware-backed secure storage, X25519 key exchange, screenshot protection, and network monitoring.
 
 <div style="display: flex; flex-direction: row; justify-content: center; align-items: center; gap: 20px;">
 <img src="https://raw.githubusercontent.com/mohamadnavabi/react-native-security-suite/master/pulse.gif" alt="iOS Pulse Network Monitor" width="200" />
@@ -23,17 +23,18 @@
 
 ### Data Security & Encryption
 
-- **Text Encryption/Decryption**: Secure data encryption with multiple algorithms
-- **Secure Storage**: Encrypted local storage with AsyncStorage integration
-- **Diffie-Hellman Key Exchange**: Secure key generation and sharing
-- **Hard & Soft Encryption**: Multiple encryption levels for different security needs
+- **Secure Storage**: Hardware-backed encrypted storage (Keychain on iOS, EncryptedSharedPreferences on Android)
+- **Diffie-Hellman / X25519 Key Exchange**: Configurable key agreement with `CryptoOptions`
+- **Shared-Key Encryption**: AES-GCM encrypt/decrypt using a derived shared secret
+- **Obfuscation**: Local string obfuscation with an explicit secret (not for credentials at rest)
 
 ### Network Security & Monitoring
 
+- **JWS Request Signing (RFC 7515)**: HMAC-signed compact JWS tokens for `fetch` requests (HS256/HS384/HS512)
+- **SSL Certificate Pinning**: Pin SPKI SHA-256 hashes with domain allowlists
 - **Network Logger**: Built-in request/response logging
 - **Android Chucker Integration**: Advanced network debugging
 - **iOS Pulse Integration**: Network monitoring for iOS
-- **SSL Pinning with Custom Certificates**: Enhanced security for API calls
 
 ## 📱 Supported Platforms
 
@@ -43,18 +44,16 @@
 
 ## 🛠 Installation
 
-> **Note:** You must add `@react-native-async-storage/async-storage` in your app's `package.json` as well. React Native only autolinks native modules that are listed in your project's dependencies, so AsyncStorage must be a direct dependency of your app.
-
 ### Using Yarn
 
 ```bash
-yarn add react-native-security-suite @react-native-async-storage/async-storage
+yarn add react-native-security-suite
 ```
 
 ### Using NPM
 
 ```bash
-npm install react-native-security-suite @react-native-async-storage/async-storage
+npm install react-native-security-suite
 ```
 
 ### iOS Setup
@@ -63,6 +62,34 @@ npm install react-native-security-suite @react-native-async-storage/async-storag
 cd ios && pod install
 ```
 
+## 📁 Project Structure
+
+The public API is exported from `src/index.tsx`. JWS validation and normalization live in a dedicated module so TypeScript and native code share the same contract.
+
+```
+src/
+├── index.tsx          # Public API (fetch, crypto, SecureStorage, SecureView)
+├── jws.ts             # JWS types, validation, payload normalization
+├── SecureView.tsx     # Screenshot-protected view component
+└── helpers.ts         # Internal utilities
+
+android/src/main/java/com/securitysuite/
+├── SecureStorageNative.java # EncryptedSharedPreferences + Android Keystore
+├── JWSGenerator.java      # RFC 7515 compact JWS (sign + verify)
+├── JwsFetchPayload.java   # Default fetch signing payload builder
+├── SecuritySuiteModule.java
+└── Sslpinning.java        # fetch + SSL pinning + JWS header injection
+
+ios/
+├── SecureStorageNative.swift # Keychain-backed secure storage
+├── KeychainHelper.swift      # Keychain read/write/query helpers
+├── JWSGenerator.swift     # RFC 7515 compact JWS (sign + verify)
+├── SecuritySuite.swift    # Native module + fetch
+└── SslPinning.swift
+```
+
+**JWS flow:** JavaScript validates options in `src/jws.ts` (secret, algorithm, headers, payload shape), normalizes the payload to the exact UTF-8 signing string, then calls native `generateJWS` on Android/iOS. For `fetch`, native code builds the signing payload when `jws.payload` is omitted, signs it, and attaches the compact token to the request header.
+
 ## 📖 Usage Examples
 
 ### 1. Root/Jailbreak Detection
@@ -108,33 +135,22 @@ const SensitiveScreen = () => {
 };
 ```
 
-### 3. Text Encryption & Decryption
+### 3. Obfuscation (local only)
 
-Secure your data with multiple encryption methods:
+Obfuscation requires an explicit secret and is intended for non-sensitive local encoding — not for credentials, tokens, or PII at rest. Use `SecureStorage` for persisted secrets.
 
 ```javascript
-import { encrypt, decrypt } from 'react-native-security-suite';
-
-const handleEncryption = async () => {
-  // Soft encryption (faster, less secure)
-  const softEncrypted = await encrypt('Sensitive data', false);
-  console.log('Soft encrypted:', softEncrypted);
-
-  const softDecrypted = await decrypt(softEncrypted, false);
-  console.log('Soft decrypted:', softDecrypted);
+import { obfuscate, deobfuscate } from 'react-native-security-suite';
 
-  // Hard encryption (slower, more secure)
-  const hardEncrypted = await encrypt('Highly sensitive data', true);
-  console.log('Hard encrypted:', hardEncrypted);
-
-  const hardDecrypted = await decrypt(hardEncrypted, true);
-  console.log('Hard decrypted:', hardDecrypted);
-};
+const encoded = await obfuscate('local-cache-value', 'app-specific-secret');
+const decoded = await deobfuscate(encoded, 'app-specific-secret');
 ```
 
+> `encrypt()` / `decrypt()` remain available but are deprecated. They now require an explicit `secretKey` and should be replaced with `obfuscate()` / `deobfuscate()` or `SecureStorage`.
+
 ### 4. Secure Storage
 
-Store sensitive data securely with automatic encryption:
+Store sensitive data in hardware-backed encrypted storage. On **iOS**, values are stored in the Keychain (`kSecClassGenericPassword`). On **Android**, values are encrypted with **EncryptedSharedPreferences** backed by Android Keystore (`AES256_GCM`).
 
 ```javascript
 import { SecureStorage } from 'react-native-security-suite';
@@ -154,24 +170,39 @@ const handleSecureStorage = async () => {
       })
     );
 
-    // Retrieve and decrypt data
+    // Retrieve data
     const token = await SecureStorage.getItem('userToken');
     const credentials = await SecureStorage.getItem('userCredentials');
+    const allKeys = await SecureStorage.getAllKeys();
 
     console.log('Retrieved token:', token);
     console.log('Retrieved credentials:', JSON.parse(credentials));
+    console.log('Stored keys:', allKeys);
 
     // Remove sensitive data
     await SecureStorage.removeItem('userToken');
+
+    // Clear all secure storage entries
+    await SecureStorage.clear();
   } catch (error) {
     console.error('Secure storage error:', error);
   }
 };
 ```
 
-### 5. Diffie-Hellman Key Exchange
+#### Security Guarantee
+
+`SecureStorage` no longer uses AsyncStorage or any JavaScript-side persistence. All keys and values are:
+
+- **Encrypted at rest** — AES-GCM (Android) / Keychain-protected blobs (iOS)
+- **Hardware-backed where available** — Android Keystore master key; iOS Keychain with `kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly`
+- **System-managed keys** — No hardcoded salts or encryption keys in app code; the OS generates and protects master keys
+
+If a native read/write fails (for example, KeyStore initialization errors on Android), the Promise rejects with a clear `Secure storage operation failed` error.
+
+### 5. Diffie-Hellman / X25519 Key Exchange
 
-Implement secure key exchange for encrypted communications:
+Implement secure key exchange with optional `CryptoOptions` (defaults: X25519 key agreement, AES-256-GCM, HMAC-SHA-512):
 
 ```javascript
 import {
@@ -181,33 +212,124 @@ import {
   decryptBySharedKey,
 } from 'react-native-security-suite';
 
+const cryptoOptions = {
+  keyAgreementAlgorithm: 'X25519',
+  keyType: 'OKP',
+  encryptionKeyAlgorithm: 'AES-256',
+  hmacAlgorithm: 'HMAC-SHA-512',
+  cipher: 'AES-GCM',
+};
+
 const handleKeyExchange = async () => {
-  try {
-    // Generate client public key
-    const clientPublicKey = await getPublicKey();
-    console.log('Client public key:', clientPublicKey);
+  const clientPublicKey = await getPublicKey();
+  const serverPublicKey = 'SERVER_PUBLIC_KEY_FROM_API';
 
-    // Send to server and receive server's public key
-    const serverPublicKey = 'SERVER_PUBLIC_KEY_FROM_API';
+  await getSharedKey(serverPublicKey, cryptoOptions);
 
-    // Generate shared secret key
-    const sharedKey = await getSharedKey(serverPublicKey);
-    console.log('Shared key generated:', sharedKey);
+  const encryptedMessage = await encryptBySharedKey('Secret message', cryptoOptions);
+  const decryptedMessage = await decryptBySharedKey(encryptedMessage, cryptoOptions);
+};
+```
 
-    // Encrypt data with shared key
-    const encryptedMessage = await encryptBySharedKey('Secret message');
-    console.log('Encrypted message:', encryptedMessage);
+### 6. JWS Generation (RFC 7515)
 
-    // Decrypt data with shared key
-    const decryptedMessage = await decryptBySharedKey(encryptedMessage);
-    console.log('Decrypted message:', decryptedMessage);
-  } catch (error) {
-    console.error('Key exchange error:', error);
-  }
-};
+Generate [RFC 7515](https://datatracker.ietf.org/doc/html/rfc7515) compact JWS tokens. Supported algorithms: **HS256**, **HS384**, **HS512**. An explicit `secret` is always required.
+
+**How it works**
+
+1. TypeScript (`src/jws.ts`) validates `secret`, `algorithm`, and custom headers.
+2. The payload is normalized to the exact UTF-8 string used for signing (objects/arrays are `JSON.stringify`'d; `undefined`/`null`/`''` become an empty payload).
+3. Native code builds sorted protected headers (always including `alg`), base64url-encodes header and payload, signs `base64url(header).base64url(payload)` with HMAC, and returns the compact token.
+
+**Empty payload** (`undefined`, `null`, or `''`) produces three segments with an empty middle segment:
+
+```javascript
+import { generateJWS } from 'react-native-security-suite';
+
+const jws = await generateJWS({
+  algorithm: 'HS256',
+  secret: 'my-temporary-secret',
+  headers: { kid: 'key-1' },
+});
+
+// compact form: <protectedHeader>.<payload>.<signature>
+// jws.split('.').length === 3
+// jws.split('.')[1] === ''   // empty payload segment
+```
+
+**JSON payload:**
+
+```javascript
+const jws = await generateJWS({
+  algorithm: 'HS512',
+  secret: 'my-temporary-secret',
+  payload: { amount: 1000, currency: 'USD' },
+  headers: { kid: 'key-1', request_id: 'req-123', typ: 'JWS' },
+});
 ```
 
-### 6. SSL Certificate Pinning
+**Header rules:** keys must match `^[a-zA-Z][a-zA-Z0-9_-]*$`; values must be JSON primitives (`string`, `number`, `boolean`, `null`). String values must be printable ASCII (`0x20`–`0x7E`). If both `algorithm` and `headers.alg` are set, they must match.
+
+> **Security note:** HS* JWS on mobile uses a client-side shared secret. It helps with request integrity when combined with TLS, but it is not proof against a fully compromised client.
+
+### 7. Fetch Request Signing with JWS
+
+Pass a `jws` object on `fetch` options. The signed token is sent as an HTTP header (default: `X-Request-Signature`).
+
+```javascript
+import { fetch } from 'react-native-security-suite';
+
+await fetch('https://api.example.com/payments', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: { amount: 1000 },
+  jws: {
+    algorithm: 'HS256',
+    secret: 'temporary-session-secret',
+    headers: {
+      kid: 'key-1',
+      request_id: 'req-123',
+      timestamp: Date.now(),
+      nonce: 'unique-nonce-per-request',
+    },
+    headerName: 'X-Request-Signature',
+    detached: false,
+  },
+});
+```
+
+**Default signing payload** (when `jws.payload` is omitted): native code builds a sorted JSON object from:
+
+| Field | Source |
+|-------|--------|
+| `method` | HTTP method (uppercased) |
+| `path` | URL path (`/` if empty) |
+| `query` | Query string (if present) |
+| `bodyHash` | Base64url SHA-256 of request body (if body present) |
+| `timestamp`, `nonce`, `request_id` | Copied from `jws.headers` when provided |
+
+**Explicit fetch payload:** when you set `jws.payload`, it must already be a string (use `JSON.stringify` for objects). For fetch, object payloads are not auto-serialized — only `generateJWS` accepts object payloads directly.
+
+```javascript
+jws: {
+  secret: 'temporary-session-secret',
+  payload: JSON.stringify({ amount: 1000, currency: 'USD' }),
+}
+```
+
+**Detached fetch signing** — set `jws.detached: true` to send `header..signature` while the raw payload remains in the request body:
+
+```javascript
+jws: {
+  secret: 'temporary-session-secret',
+  detached: true,
+  headers: { kid: 'key-1', request_id: 'req-123' },
+}
+```
+
+**Migration from legacy options:** `options.keyId`, `options.requestId`, and top-level `options.secret` are deprecated. Use `options.jws` with `secret`, `headers.kid`, and `headers.request_id` instead. Legacy signing always used detached HS256 and the `X-JWS-Signature` header.
+
+### 8. SSL Certificate Pinning
 
 Secure your API communications with certificate pinning:
 
@@ -243,7 +365,7 @@ const secureApiCall = async () => {
 };
 ```
 
-### 7. Network Monitoring & Debugging
+### 9. Network Monitoring & Debugging
 
 Monitor network requests in development:
 
@@ -274,37 +396,81 @@ const monitoredRequest = async () => {
 
 ### Security Detection
 
-- `deviceHasSecurityRisk()` - Detect rooted/jailbroken devices
+- `deviceHasSecurityRisk()` — Detect rooted/jailbroken devices
 
 ### Encryption & Storage
 
-- `encrypt(text, hardEncryption?, secretKey?)` - Encrypt text
-- `decrypt(encryptedText, hardEncryption?, secretKey?)` - Decrypt text
-- `SecureStorage` - Encrypted storage methods
+- `obfuscate(input, secret)` — Local obfuscation with explicit secret
+- `deobfuscate(input, secret)` — Reverse `obfuscate`
+- `SecureStorage` — Hardware-backed encrypted storage (`setItem`, `getItem`, `removeItem`, `getAllKeys`, `clear`, `multiGet`, `multiSet`, `multiRemove`)
+- `encrypt(text, hardEncryption?, secretKey?)` — **deprecated**; requires `secretKey`
+- `decrypt(encryptedText, hardEncryption?, secretKey?)` — **deprecated**; requires `secretKey`
 
 ### Key Exchange
 
-- `getPublicKey()` - Generate public key
-- `getSharedKey(serverPublicKey)` - Generate shared key
-- `encryptBySharedKey(text)` - Encrypt with shared key
-- `decryptBySharedKey(encryptedText)` - Decrypt with shared key
+- `getPublicKey()` — Generate client public key (JWK)
+- `getSharedKey(serverPublicKey, options?)` — Derive shared secret; accepts `CryptoOptions`
+- `encryptBySharedKey(text, options?)` — AES-GCM encrypt with derived key
+- `decryptBySharedKey(encryptedText, options?)` — AES-GCM decrypt with derived key
+
+#### `CryptoOptions`
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `keyAgreementAlgorithm` | `'X25519'` | Key agreement (e.g. `X25519`, `ECDH`) |
+| `keyType` | `'OKP'` | JWK key type (`OKP`, `EC`) |
+| `encryptionKeyAlgorithm` | `'AES-256'` | Symmetric key algorithm |
+| `hmacAlgorithm` | `'HMAC-SHA-512'` | HMAC for signing and key derivation |
+| `cipher` | `'AES-GCM'` | AEAD cipher mode |
+| `tagLength` | `128` | GCM authentication tag length (bits) |
+| `ivLength` | `12` | GCM IV length (bytes) |
+
+### JWS
+
+- `generateJWS(options: GenerateJWSOptions)` — Generate compact or detached JWS
+
+#### `GenerateJWSOptions`
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `secret` | yes | Non-empty HMAC secret |
+| `algorithm` | no | `HS256` (default), `HS384`, or `HS512` |
+| `payload` | no | String, object, array, number, boolean, `null`, or `undefined` |
+| `headers` | no | Custom protected headers (`kid`, `request_id`, etc.) |
+
+#### `JwsFetchOptions` (on `fetch` options)
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `secret` | yes | Non-empty HMAC secret |
+| `algorithm` | no | `HS256` (default), `HS384`, or `HS512` |
+| `headers` | no | Protected headers; `timestamp`/`nonce`/`request_id` also feed the default payload |
+| `payload` | no | Explicit signing string; omit to use the default fetch payload |
+| `detached` | no | Detached compact form (default: `false`) |
+| `headerName` | no | Request header name (default: `X-Request-Signature`) |
+
+Exported types: `JwsAlgorithm`, `JwsPayload`, `JwsHeaders`, `JwsHeaderValue`, `GenerateJWSOptions`, `JwsFetchOptions`.
 
 ### Network Security
 
-- `fetch(url, options, loggerEnabled?)` - Secure fetch with SSL pinning
+- `fetch(url, options, loggerEnabled?)` — Secure fetch with SSL pinning and optional JWS signing
+
+`fetch` `options` also accepts `certificates` + `validDomains` for SSL pinning, and deprecated top-level `keyId`, `requestId`, `secret` for legacy JWS.
 
 ### UI Components
 
-- `SecureView` - Screenshot-protected view component
+- `SecureView` — Screenshot-protected view component
 
 ## 🛡️ Security Best Practices
 
-1. **Always validate certificates** - Use SSL pinning for production APIs
-2. **Detect compromised devices** - Check for root/jailbreak before sensitive operations
-3. **Use appropriate encryption levels** - Hard encryption for highly sensitive data
-4. **Protect sensitive UI** - Wrap sensitive content in SecureView
-5. **Monitor network traffic** - Use built-in logging for debugging
-6. **Secure key management** - Implement proper key exchange protocols
+1. **Always validate certificates** — Use SSL pinning for production APIs
+2. **Detect compromised devices** — Check for root/jailbreak before sensitive operations
+3. **Store secrets in SecureStorage** — Use hardware-backed storage for tokens and credentials
+4. **Protect sensitive UI** — Wrap sensitive content in `SecureView`
+5. **Sign requests with JWS** — Include `timestamp`, `nonce`, and `request_id` in `jws.headers` for replay protection; never embed long-lived secrets in the app binary
+6. **Use detached JWS for body signing** — When the request body is the signed payload, set `jws.detached: true` so the body is not duplicated inside the token
+7. **Monitor network traffic** — Use built-in logging for debugging only; disable in production
+8. **Rotate session secrets** — Treat `jws.secret` as a short-lived session or request-scoped value from your backend
 
 ## 🐛 Troubleshooting
 

package/android/build.gradle

@@ -76,6 +76,12 @@ android {
     }
   }
 
+  testOptions {
+    unitTests.all {
+      it.useJUnit()
+    }
+  }
+
   lintOptions {
     disable "GradleCompatible"
   }
@@ -90,6 +96,7 @@ android {
   }
 
   buildFeatures {
+    buildConfig true
     dataBinding true
   }
 }
@@ -111,5 +118,9 @@ dependencies {
   implementation "com.squareup.okhttp3:okhttp:4.12.0"
   implementation "com.scottyab:rootbeer-lib:0.1.0"
   implementation "com.github.chuckerteam.chucker:library:4.1.0"
+  implementation "androidx.security:security-crypto:1.1.0-alpha06"
+
+  testImplementation "junit:junit:4.13.2"
+  testImplementation "com.facebook.react:react-native:+"
 }
 

package/android/gradle.properties

@@ -1,5 +1,5 @@
 SecuritySuite_kotlinVersion=1.7.0
-SecuritySuite_minSdkVersion=21
+SecuritySuite_minSdkVersion=23
 SecuritySuite_targetSdkVersion=31
 SecuritySuite_compileSdkVersion=31
 SecuritySuite_ndkversion=21.4.7075529

package/android/src/main/java/com/securitysuite/CryptoConfig.java

@@ -0,0 +1,158 @@
+package com.securitysuite;
+
+import com.facebook.react.bridge.ReadableMap;
+
+/**
+ * Configurable cryptographic parameters with secure defaults and whitelist validation.
+ */
+public final class CryptoConfig {
+  public static final String DEFAULT_KEY_AGREEMENT = "ECDH";
+  public static final String DEFAULT_KEY_FACTORY = "EC";
+  public static final String DEFAULT_ENCRYPTION_KEY_ALGORITHM = "AES";
+  public static final String DEFAULT_HMAC_KEY_ALGORITHM = "HmacSHA256";
+  public static final String DEFAULT_CIPHER_TRANSFORMATION = "AES/GCM/NoPadding";
+  public static final int DEFAULT_GCM_TAG_LENGTH = 128;
+  public static final int DEFAULT_GCM_IV_LENGTH = 12;
+
+  public final String keyAgreementAlgorithm;
+  public final String keyFactoryAlgorithm;
+  public final String encryptionKeyAlgorithm;
+  public final String hmacKeyAlgorithm;
+  public final String cipherTransformation;
+  public final int gcmTagLength;
+  public final int gcmIvLength;
+
+  private CryptoConfig(
+      String keyAgreementAlgorithm,
+      String keyFactoryAlgorithm,
+      String encryptionKeyAlgorithm,
+      String hmacKeyAlgorithm,
+      String cipherTransformation,
+      int gcmTagLength,
+      int gcmIvLength
+  ) {
+    this.keyAgreementAlgorithm = keyAgreementAlgorithm;
+    this.keyFactoryAlgorithm = keyFactoryAlgorithm;
+    this.encryptionKeyAlgorithm = encryptionKeyAlgorithm;
+    this.hmacKeyAlgorithm = hmacKeyAlgorithm;
+    this.cipherTransformation = cipherTransformation;
+    this.gcmTagLength = gcmTagLength;
+    this.gcmIvLength = gcmIvLength;
+  }
+
+  public static CryptoConfig defaults() {
+    return new CryptoConfig(
+        DEFAULT_KEY_AGREEMENT,
+        DEFAULT_KEY_FACTORY,
+        DEFAULT_ENCRYPTION_KEY_ALGORITHM,
+        DEFAULT_HMAC_KEY_ALGORITHM,
+        DEFAULT_CIPHER_TRANSFORMATION,
+        DEFAULT_GCM_TAG_LENGTH,
+        DEFAULT_GCM_IV_LENGTH
+    );
+  }
+
+  public static CryptoConfig fromReadableMap(ReadableMap options) {
+    if (options == null) {
+      return defaults();
+    }
+
+    return new CryptoConfig(
+        validateKeyAgreement(readString(options, "keyAgreementAlgorithm", DEFAULT_KEY_AGREEMENT)),
+        validateKeyFactory(readString(options, "keyFactoryAlgorithm", DEFAULT_KEY_FACTORY)),
+        validateEncryptionKeyAlgorithm(
+            readString(options, "encryptionKeyAlgorithm", DEFAULT_ENCRYPTION_KEY_ALGORITHM)
+        ),
+        validateHmacKeyAlgorithm(readString(options, "hmacKeyAlgorithm", DEFAULT_HMAC_KEY_ALGORITHM)),
+        validateCipherTransformation(
+            readString(options, "cipherTransformation", DEFAULT_CIPHER_TRANSFORMATION)
+        ),
+        options.hasKey("gcmTagLength") ? options.getInt("gcmTagLength") : DEFAULT_GCM_TAG_LENGTH,
+        options.hasKey("gcmIvLength") ? options.getInt("gcmIvLength") : DEFAULT_GCM_IV_LENGTH
+    );
+  }
+
+  public CryptoConfig merge(ReadableMap options) {
+    return options == null ? this : fromReadableMap(mergeMaps(this, options));
+  }
+
+  private static ReadableMap mergeMaps(CryptoConfig base, ReadableMap overrides) {
+    com.facebook.react.bridge.WritableMap map = com.facebook.react.bridge.Arguments.createMap();
+    map.putString("keyAgreementAlgorithm", base.keyAgreementAlgorithm);
+    map.putString("keyFactoryAlgorithm", base.keyFactoryAlgorithm);
+    map.putString("encryptionKeyAlgorithm", base.encryptionKeyAlgorithm);
+    map.putString("hmacKeyAlgorithm", base.hmacKeyAlgorithm);
+    map.putString("cipherTransformation", base.cipherTransformation);
+    map.putInt("gcmTagLength", base.gcmTagLength);
+    map.putInt("gcmIvLength", base.gcmIvLength);
+
+    if (overrides.hasKey("keyAgreementAlgorithm")) {
+      map.putString("keyAgreementAlgorithm", overrides.getString("keyAgreementAlgorithm"));
+    }
+    if (overrides.hasKey("keyFactoryAlgorithm")) {
+      map.putString("keyFactoryAlgorithm", overrides.getString("keyFactoryAlgorithm"));
+    }
+    if (overrides.hasKey("encryptionKeyAlgorithm")) {
+      map.putString("encryptionKeyAlgorithm", overrides.getString("encryptionKeyAlgorithm"));
+    }
+    if (overrides.hasKey("hmacKeyAlgorithm")) {
+      map.putString("hmacKeyAlgorithm", overrides.getString("hmacKeyAlgorithm"));
+    }
+    if (overrides.hasKey("cipherTransformation")) {
+      map.putString("cipherTransformation", overrides.getString("cipherTransformation"));
+    }
+    if (overrides.hasKey("gcmTagLength")) {
+      map.putInt("gcmTagLength", overrides.getInt("gcmTagLength"));
+    }
+    if (overrides.hasKey("gcmIvLength")) {
+      map.putInt("gcmIvLength", overrides.getInt("gcmIvLength"));
+    }
+    return map;
+  }
+
+  private static String readString(ReadableMap map, String key, String defaultValue) {
+    if (map.hasKey(key) && map.getString(key) != null) {
+      return map.getString(key).trim();
+    }
+    return defaultValue;
+  }
+
+  private static String validateKeyAgreement(String algorithm) {
+    if ("ECDH".equals(algorithm)) {
+      return algorithm;
+    }
+    throw new IllegalArgumentException("Unsupported keyAgreementAlgorithm: " + algorithm);
+  }
+
+  private static String validateKeyFactory(String algorithm) {
+    if ("EC".equals(algorithm)) {
+      return algorithm;
+    }
+    throw new IllegalArgumentException("Unsupported keyFactoryAlgorithm: " + algorithm);
+  }
+
+  private static String validateEncryptionKeyAlgorithm(String algorithm) {
+    if ("AES".equals(algorithm)) {
+      return algorithm;
+    }
+    throw new IllegalArgumentException("Unsupported encryptionKeyAlgorithm: " + algorithm);
+  }
+
+  private static String validateHmacKeyAlgorithm(String algorithm) {
+    switch (algorithm) {
+      case "HmacSHA256":
+      case "HmacSHA384":
+      case "HmacSHA512":
+        return algorithm;
+      default:
+        throw new IllegalArgumentException("Unsupported hmacKeyAlgorithm: " + algorithm);
+    }
+  }
+
+  private static String validateCipherTransformation(String transformation) {
+    if ("AES/GCM/NoPadding".equals(transformation)) {
+      return transformation;
+    }
+    throw new IllegalArgumentException("Unsupported cipherTransformation: " + transformation);
+  }
+}