@onekeyfe/react-native-aes-crypto 3.0.33 → 3.0.35

package/AesCrypto.podspec

@@ -15,7 +15,18 @@ Pod::Spec.new do |s|
 
   s.source_files = "ios/**/*.{h,m,mm,swift}"
 
-  s.frameworks = 'Security'
+  s.frameworks = ['Security', 'CryptoKit']
+  # Workaround: `AesCrypto.mm` imports the generated `AesCrypto-Swift.h`
+  # bridging header for the `AesCryptoGcm` Swift helper. With Xcode 15+
+  # explicit Swift modules turned on, that bridging header conflicts with
+  # the explicit module map for `AesCryptoSpec` (the TurboModule C++ spec),
+  # producing module-map redefinition errors at pod build time. Disabling
+  # explicit modules on this pod target is the same pattern other RN modules
+  # mixing ObjC++ + Swift use; revisit once the Swift toolchain handles the
+  # combination natively.
+  s.pod_target_xcconfig = {
+    'SWIFT_ENABLE_EXPLICIT_MODULES' => 'NO'
+  }
 
   install_modules_dependencies(s)
 end

package/android/src/main/java/com/aescrypto/AesCryptoModule.kt

@@ -9,6 +9,7 @@ import java.security.SecureRandom
 import java.util.UUID
 import javax.crypto.Cipher
 import javax.crypto.Mac
+import javax.crypto.spec.GCMParameterSpec
 import javax.crypto.spec.IvParameterSpec
 import javax.crypto.spec.SecretKeySpec
 import org.spongycastle.crypto.Digest
@@ -31,12 +32,18 @@ class AesCryptoModule(reactContext: ReactApplicationContext) :
         const val NAME = "AesCrypto"
         private const val CIPHER_CBC_ALGORITHM = "AES/CBC/PKCS7Padding"
         private const val CIPHER_CTR_ALGORITHM = "AES/CTR/PKCS5Padding"
+        private const val CIPHER_GCM_ALGORITHM = "AES/GCM/NoPadding"
+        private const val GCM_AUTH_TAG_LENGTH_BITS = 128
+        // AES-GCM nonce length: NIST SP 800-38D recommends 96 bits (12 bytes).
+        // CryptoKit on iOS enforces 12 bytes for the default nonce, so locking
+        // Android to the same length avoids the platform mismatch where
+        // GCMParameterSpec would otherwise accept a non-12-byte nonce that
+        // CryptoKit cannot decrypt.
+        private const val GCM_NONCE_LENGTH_BYTES = 12
         private const val HMAC_SHA_256 = "HmacSHA256"
         private const val HMAC_SHA_512 = "HmacSHA512"
         private const val KEY_ALGORITHM = "AES"
 
-        private val emptyIvSpec = IvParameterSpec(ByteArray(16) { 0x00 })
-
         @JvmStatic
         fun bytesToHex(bytes: ByteArray): String {
             val hexArray = "0123456789abcdef".toCharArray()
@@ -48,12 +55,47 @@ class AesCryptoModule(reactContext: ReactApplicationContext) :
             }
             return String(hexChars)
         }
+
+        // Reject empty strings at every native entry point. Callers MUST
+        // supply concrete bytes for every argument; an empty hex string is
+        // almost always an upstream bug (forgotten parameter, miswired AAD,
+        // truncated input) that we want to fail loudly instead of letting
+        // it sneak past the cipher layer.
+        private fun requireNonEmpty(value: String?, method: String, paramName: String): String {
+            if (value.isNullOrEmpty()) {
+                throw IllegalArgumentException("$method: $paramName must not be empty")
+            }
+            return value
+        }
+
+        // Numeric arguments from the JS side arrive as Double. Coerce them to
+        // a positive 32-bit integer, but reject NaN, infinities, fractional
+        // values, and anything outside Int range up front — otherwise toInt()
+        // would silently truncate (1.5 -> 1) or saturate (NaN -> 0), and the
+        // `<= 0` guard alone would let either path slip through into cipher /
+        // KDF code that subsequently treats the value as a buffer size.
+        private fun requirePositiveInt(value: Double, method: String, paramName: String): Int {
+            if (!value.isFinite()
+                || value <= 0.0
+                || value != Math.floor(value)
+                || value > Int.MAX_VALUE.toDouble()
+            ) {
+                throw IllegalArgumentException(
+                    "$method: $paramName must be a positive finite integer (<= ${Int.MAX_VALUE})"
+                )
+            }
+            return value.toInt()
+        }
     }
 
     override fun getName(): String = NAME
 
     override fun encrypt(data: String, key: String, iv: String, algorithm: String, promise: Promise) {
         try {
+            requireNonEmpty(data, "encrypt", "data")
+            requireNonEmpty(key, "encrypt", "key")
+            requireNonEmpty(iv, "encrypt", "iv")
+            requireNonEmpty(algorithm, "encrypt", "algorithm")
             val cipherAlgorithm = if (algorithm.lowercase().contains("cbc")) CIPHER_CBC_ALGORITHM else CIPHER_CTR_ALGORITHM
             val result = encryptImpl(data, key, iv, cipherAlgorithm)
             promise.resolve(result)
@@ -64,6 +106,10 @@ class AesCryptoModule(reactContext: ReactApplicationContext) :
 
     override fun decrypt(base64: String, key: String, iv: String, algorithm: String, promise: Promise) {
         try {
+            requireNonEmpty(base64, "decrypt", "ciphertext")
+            requireNonEmpty(key, "decrypt", "key")
+            requireNonEmpty(iv, "decrypt", "iv")
+            requireNonEmpty(algorithm, "decrypt", "algorithm")
             val cipherAlgorithm = if (algorithm.lowercase().contains("cbc")) CIPHER_CBC_ALGORITHM else CIPHER_CTR_ALGORITHM
             val result = decryptImpl(base64, key, iv, cipherAlgorithm)
             promise.resolve(result)
@@ -72,9 +118,45 @@ class AesCryptoModule(reactContext: ReactApplicationContext) :
         }
     }
 
+    override fun aesGcmEncrypt(data: String, key: String, nonce: String, aad: String, promise: Promise) {
+        try {
+            // `data` is intentionally NOT required to be non-empty: AEAD with an
+            // empty plaintext is a legitimate operation that yields a 16-byte
+            // authentication tag, and CryptoKit on iOS supports it directly.
+            requireNonEmpty(key, "aesGcmEncrypt", "key")
+            requireNonEmpty(nonce, "aesGcmEncrypt", "nonce")
+            requireNonEmpty(aad, "aesGcmEncrypt", "aad")
+            val result = aesGcmEncryptImpl(data, key, nonce, aad)
+            promise.resolve(result)
+        } catch (e: Exception) {
+            promise.reject("-1", e.message)
+        }
+    }
+
+    override fun aesGcmDecrypt(ciphertextWithTag: String, key: String, nonce: String, aad: String, promise: Promise) {
+        try {
+            // `ciphertextWithTag` is intentionally NOT validated here for
+            // non-emptiness — `aesGcmDecryptImpl` enforces the stronger
+            // `>= 16 bytes` (auth-tag length) guard, which already covers the
+            // empty-string case.
+            requireNonEmpty(key, "aesGcmDecrypt", "key")
+            requireNonEmpty(nonce, "aesGcmDecrypt", "nonce")
+            requireNonEmpty(aad, "aesGcmDecrypt", "aad")
+            val result = aesGcmDecryptImpl(ciphertextWithTag, key, nonce, aad)
+            promise.resolve(result)
+        } catch (e: Exception) {
+            promise.reject("-1", e.message)
+        }
+    }
+
     override fun pbkdf2(password: String, salt: String, cost: Double, length: Double, algorithm: String, promise: Promise) {
         try {
-            val result = pbkdf2Impl(password, salt, cost.toInt(), length.toInt(), algorithm)
+            requireNonEmpty(password, "pbkdf2", "password")
+            requireNonEmpty(salt, "pbkdf2", "salt")
+            requireNonEmpty(algorithm, "pbkdf2", "algorithm")
+            val costInt = requirePositiveInt(cost, "pbkdf2", "cost")
+            val lengthInt = requirePositiveInt(length, "pbkdf2", "length")
+            val result = pbkdf2Impl(password, salt, costInt, lengthInt, algorithm)
             promise.resolve(result)
         } catch (e: Exception) {
             promise.reject("-1", e.message)
@@ -83,6 +165,8 @@ class AesCryptoModule(reactContext: ReactApplicationContext) :
 
     override fun hmac256(data: String, key: String, promise: Promise) {
         try {
+            requireNonEmpty(data, "hmac256", "data")
+            requireNonEmpty(key, "hmac256", "key")
             val result = hmacX(data, key, HMAC_SHA_256)
             promise.resolve(result)
         } catch (e: Exception) {
@@ -92,6 +176,8 @@ class AesCryptoModule(reactContext: ReactApplicationContext) :
 
     override fun hmac512(data: String, key: String, promise: Promise) {
         try {
+            requireNonEmpty(data, "hmac512", "data")
+            requireNonEmpty(key, "hmac512", "key")
             val result = hmacX(data, key, HMAC_SHA_512)
             promise.resolve(result)
         } catch (e: Exception) {
@@ -101,6 +187,7 @@ class AesCryptoModule(reactContext: ReactApplicationContext) :
 
     override fun sha1(text: String, promise: Promise) {
         try {
+            requireNonEmpty(text, "sha1", "text")
             val result = shaX(text, "SHA-1")
             promise.resolve(result)
         } catch (e: Exception) {
@@ -110,6 +197,7 @@ class AesCryptoModule(reactContext: ReactApplicationContext) :
 
     override fun sha256(text: String, promise: Promise) {
         try {
+            requireNonEmpty(text, "sha256", "text")
             val result = shaX(text, "SHA-256")
             promise.resolve(result)
         } catch (e: Exception) {
@@ -119,6 +207,7 @@ class AesCryptoModule(reactContext: ReactApplicationContext) :
 
     override fun sha512(text: String, promise: Promise) {
         try {
+            requireNonEmpty(text, "sha512", "text")
             val result = shaX(text, "SHA-512")
             promise.resolve(result)
         } catch (e: Exception) {
@@ -136,7 +225,8 @@ class AesCryptoModule(reactContext: ReactApplicationContext) :
 
     override fun randomKey(length: Double, promise: Promise) {
         try {
-            val key = ByteArray(length.toInt())
+            val keyLength = requirePositiveInt(length, "randomKey", "length")
+            val key = ByteArray(keyLength)
             SecureRandom().nextBytes(key)
             promise.resolve(bytesToHex(key))
         } catch (e: Exception) {
@@ -174,27 +264,55 @@ class AesCryptoModule(reactContext: ReactApplicationContext) :
         return bytesToHex(mac.doFinal(contentData))
     }
 
-    private fun encryptImpl(text: String, hexKey: String, hexIv: String?, algorithm: String): String? {
-        if (text.isEmpty()) return null
-
+    private fun encryptImpl(text: String, hexKey: String, hexIv: String, algorithm: String): String {
         val key = Hex.decode(hexKey)
         val secretKey = SecretKeySpec(key, KEY_ALGORITHM)
         val cipher = Cipher.getInstance(algorithm)
-        val ivSpec = if (hexIv == null || hexIv.isEmpty()) emptyIvSpec else IvParameterSpec(Hex.decode(hexIv))
-        cipher.init(Cipher.ENCRYPT_MODE, secretKey, ivSpec)
+        cipher.init(Cipher.ENCRYPT_MODE, secretKey, IvParameterSpec(Hex.decode(hexIv)))
         val encrypted = cipher.doFinal(Hex.decode(text))
         return bytesToHex(encrypted)
     }
 
-    private fun decryptImpl(ciphertext: String, hexKey: String, hexIv: String?, algorithm: String): String? {
-        if (ciphertext.isEmpty()) return null
-
+    private fun decryptImpl(ciphertext: String, hexKey: String, hexIv: String, algorithm: String): String {
         val key = Hex.decode(hexKey)
         val secretKey = SecretKeySpec(key, KEY_ALGORITHM)
         val cipher = Cipher.getInstance(algorithm)
-        val ivSpec = if (hexIv == null || hexIv.isEmpty()) emptyIvSpec else IvParameterSpec(Hex.decode(hexIv))
-        cipher.init(Cipher.DECRYPT_MODE, secretKey, ivSpec)
+        cipher.init(Cipher.DECRYPT_MODE, secretKey, IvParameterSpec(Hex.decode(hexIv)))
         val decrypted = cipher.doFinal(Hex.decode(ciphertext))
         return bytesToHex(decrypted)
     }
+
+    private fun decodeGcmNonce(hexNonce: String): ByteArray {
+        val nonceBytes = Hex.decode(hexNonce)
+        if (nonceBytes.size != GCM_NONCE_LENGTH_BYTES) {
+            throw IllegalArgumentException(
+                "AES-GCM nonce must be exactly $GCM_NONCE_LENGTH_BYTES bytes (got ${nonceBytes.size})"
+            )
+        }
+        return nonceBytes
+    }
+
+    private fun aesGcmEncryptImpl(text: String, hexKey: String, hexNonce: String, aad: String): String {
+        val secretKey = SecretKeySpec(Hex.decode(hexKey), KEY_ALGORITHM)
+        val cipher = Cipher.getInstance(CIPHER_GCM_ALGORITHM)
+        val gcmSpec = GCMParameterSpec(GCM_AUTH_TAG_LENGTH_BITS, decodeGcmNonce(hexNonce))
+        cipher.init(Cipher.ENCRYPT_MODE, secretKey, gcmSpec)
+        cipher.updateAAD(Hex.decode(aad))
+        return bytesToHex(cipher.doFinal(Hex.decode(text)))
+    }
+
+    private fun aesGcmDecryptImpl(ciphertextWithTag: String, hexKey: String, hexNonce: String, aad: String): String {
+        val encrypted = Hex.decode(ciphertextWithTag)
+        val tagBytes = GCM_AUTH_TAG_LENGTH_BITS / 8
+        if (encrypted.size < tagBytes) {
+            throw IllegalArgumentException("AES-GCM ciphertext must include the ${tagBytes}-byte authentication tag")
+        }
+
+        val secretKey = SecretKeySpec(Hex.decode(hexKey), KEY_ALGORITHM)
+        val cipher = Cipher.getInstance(CIPHER_GCM_ALGORITHM)
+        val gcmSpec = GCMParameterSpec(GCM_AUTH_TAG_LENGTH_BITS, decodeGcmNonce(hexNonce))
+        cipher.init(Cipher.DECRYPT_MODE, secretKey, gcmSpec)
+        cipher.updateAAD(Hex.decode(aad))
+        return bytesToHex(cipher.doFinal(encrypted))
+    }
 }

package/ios/AesCrypto.h

@@ -1,3 +1,11 @@
+// The TurboModule spec header `<AesCryptoSpec/AesCryptoSpec.h>` is generated
+// as ObjC++ (the `NativeAesCryptoSpecBase` base class uses C++ types from
+// React Native's TurboModule runtime). The `@interface` is wrapped in the
+// same `#ifdef __cplusplus` block as the import because it inherits from
+// `NativeAesCryptoSpecBase`, which only resolves in an ObjC++ translation
+// unit. Pure ObjC `.m` files therefore cannot include this header — that is
+// intentional; AesCrypto.mm is the sole consumer.
+#ifdef __cplusplus
 #import <AesCryptoSpec/AesCryptoSpec.h>
 
 @interface AesCrypto : NativeAesCryptoSpecBase <NativeAesCryptoSpec>
@@ -16,6 +24,20 @@
         resolve:(RCTPromiseResolveBlock)resolve
          reject:(RCTPromiseRejectBlock)reject;
 
+- (void)aesGcmEncrypt:(NSString *)data
+                  key:(NSString *)key
+                nonce:(NSString *)nonce
+                  aad:(NSString *)aad
+              resolve:(RCTPromiseResolveBlock)resolve
+               reject:(RCTPromiseRejectBlock)reject;
+
+- (void)aesGcmDecrypt:(NSString *)ciphertextWithTag
+                  key:(NSString *)key
+                nonce:(NSString *)nonce
+                  aad:(NSString *)aad
+              resolve:(RCTPromiseResolveBlock)resolve
+               reject:(RCTPromiseRejectBlock)reject;
+
 - (void)pbkdf2:(NSString *)password
            salt:(NSString *)salt
            cost:(double)cost
@@ -54,3 +76,4 @@
            reject:(RCTPromiseRejectBlock)reject;
 
 @end
+#endif

package/ios/AesCrypto.mm

@@ -1,9 +1,48 @@
 #import "AesCrypto.h"
+#import "AesCrypto-Swift.h"
 #import <CommonCrypto/CommonCryptor.h>
 #import <CommonCrypto/CommonDigest.h>
 #import <CommonCrypto/CommonHMAC.h>
 #import <CommonCrypto/CommonKeyDerivation.h>
 #import <Security/Security.h>
+#import <limits.h>
+#import <math.h>
+
+// Reject empty string / non-positive numeric arguments at every native
+// entry point. An empty hex string is almost always an upstream bug —
+// forgotten parameter, miswired AAD, truncated input. Fail loudly here
+// instead of silently feeding zero-length bytes into the cipher layer.
+#define ONEKEY_AES_REQUIRE_NON_EMPTY(value, method, paramName, reject) \
+    do { \
+        if ((value) == nil || [(value) length] == 0) { \
+            (reject)(@"-1", \
+                     [NSString stringWithFormat:@"%@: %@ must not be empty", \
+                                                (method), (paramName)], \
+                     nil); \
+            return; \
+        } \
+    } while (0)
+
+// Numeric arguments arrive as `double` from the JS bridge. A plain `<= 0`
+// check lets NaN, Infinity, and fractional values slip through (NaN compares
+// false against every value, and 1.5 would later cast to 1). This guard
+// rejects all of those — and anything larger than INT_MAX — up front so
+// callers cannot smuggle a malformed numeric into a buffer allocation or
+// KDF iteration count.
+#define ONEKEY_AES_REQUIRE_POSITIVE(value, method, paramName, reject) \
+    do { \
+        double _onekeyAesValue = (double)(value); \
+        if (!isfinite(_onekeyAesValue) \
+            || _onekeyAesValue <= 0.0 \
+            || _onekeyAesValue != floor(_onekeyAesValue) \
+            || _onekeyAesValue > (double)INT_MAX) { \
+            (reject)(@"-1", \
+                     [NSString stringWithFormat:@"%@: %@ must be a positive finite integer (<= %d)", \
+                                                (method), (paramName), INT_MAX], \
+                     nil); \
+            return; \
+        } \
+    } while (0)
 
 // ---------------------------------------------------------------------------
 // MARK: - Internal helpers
@@ -155,6 +194,10 @@ static NSData *aesCTR(NSString *operation, NSData *inputData, NSString *key, NSS
         resolve:(RCTPromiseResolveBlock)resolve
          reject:(RCTPromiseRejectBlock)reject
 {
+    ONEKEY_AES_REQUIRE_NON_EMPTY(data, @"encrypt", @"data", reject);
+    ONEKEY_AES_REQUIRE_NON_EMPTY(key, @"encrypt", @"key", reject);
+    ONEKEY_AES_REQUIRE_NON_EMPTY(iv, @"encrypt", @"iv", reject);
+    ONEKEY_AES_REQUIRE_NON_EMPTY(algorithm, @"encrypt", @"algorithm", reject);
     dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
         @try {
             NSData *inputData = fromHex(data);
@@ -165,12 +208,12 @@ static NSData *aesCTR(NSString *operation, NSData *inputData, NSString *key, NSS
                 result = aesCBC(@"encrypt", inputData, key, iv, algorithm);
             }
             if (result == nil) {
-                reject(@"encrypt_fail", @"Encrypt error", nil);
+                reject(@"-1", @"Encrypt error", nil);
             } else {
                 resolve(toHex(result));
             }
         } @catch (NSException *exception) {
-            reject(@"encrypt_fail", exception.reason, nil);
+            reject(@"-1", exception.reason, nil);
         }
     });
 }
@@ -184,6 +227,10 @@ static NSData *aesCTR(NSString *operation, NSData *inputData, NSString *key, NSS
         resolve:(RCTPromiseResolveBlock)resolve
          reject:(RCTPromiseRejectBlock)reject
 {
+    ONEKEY_AES_REQUIRE_NON_EMPTY(base64, @"decrypt", @"ciphertext", reject);
+    ONEKEY_AES_REQUIRE_NON_EMPTY(key, @"decrypt", @"key", reject);
+    ONEKEY_AES_REQUIRE_NON_EMPTY(iv, @"decrypt", @"iv", reject);
+    ONEKEY_AES_REQUIRE_NON_EMPTY(algorithm, @"decrypt", @"algorithm", reject);
     dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
         @try {
             NSData *inputData = fromHex(base64);
@@ -194,12 +241,71 @@ static NSData *aesCTR(NSString *operation, NSData *inputData, NSString *key, NSS
                 result = aesCBC(@"decrypt", inputData, key, iv, algorithm);
             }
             if (result == nil) {
-                reject(@"decrypt_fail", @"Decrypt failed", nil);
+                reject(@"-1", @"Decrypt failed", nil);
             } else {
                 resolve(toHex(result));
             }
         } @catch (NSException *exception) {
-            reject(@"decrypt_fail", exception.reason, nil);
+            reject(@"-1", exception.reason, nil);
+        }
+    });
+}
+
+// MARK: - aesGcmEncrypt
+
+- (void)aesGcmEncrypt:(NSString *)data
+                  key:(NSString *)key
+                nonce:(NSString *)nonce
+                  aad:(NSString *)aad
+              resolve:(RCTPromiseResolveBlock)resolve
+               reject:(RCTPromiseRejectBlock)reject
+{
+    // `data` is intentionally NOT required to be non-empty: empty plaintext
+    // is a legitimate AEAD operation that yields the 16-byte auth tag.
+    ONEKEY_AES_REQUIRE_NON_EMPTY(key, @"aesGcmEncrypt", @"key", reject);
+    ONEKEY_AES_REQUIRE_NON_EMPTY(nonce, @"aesGcmEncrypt", @"nonce", reject);
+    ONEKEY_AES_REQUIRE_NON_EMPTY(aad, @"aesGcmEncrypt", @"aad", reject);
+    dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
+        @try {
+            NSError *error = nil;
+            NSString *result = [AesCryptoGcm encryptWithDataHex:data keyHex:key nonceHex:nonce aadHex:aad error:&error];
+            if (result == nil) {
+                reject(@"-1", error.localizedDescription ?: @"AES-GCM encrypt error", error);
+            } else {
+                resolve(result);
+            }
+        } @catch (NSException *exception) {
+            reject(@"-1", exception.reason, nil);
+        }
+    });
+}
+
+// MARK: - aesGcmDecrypt
+
+- (void)aesGcmDecrypt:(NSString *)ciphertextWithTag
+                  key:(NSString *)key
+                nonce:(NSString *)nonce
+                  aad:(NSString *)aad
+              resolve:(RCTPromiseResolveBlock)resolve
+               reject:(RCTPromiseRejectBlock)reject
+{
+    // `ciphertextWithTag` is intentionally NOT required to be non-empty
+    // here — the Swift impl enforces a stronger `>= 16 bytes` guard which
+    // already covers the empty / truncated cases.
+    ONEKEY_AES_REQUIRE_NON_EMPTY(key, @"aesGcmDecrypt", @"key", reject);
+    ONEKEY_AES_REQUIRE_NON_EMPTY(nonce, @"aesGcmDecrypt", @"nonce", reject);
+    ONEKEY_AES_REQUIRE_NON_EMPTY(aad, @"aesGcmDecrypt", @"aad", reject);
+    dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
+        @try {
+            NSError *error = nil;
+            NSString *result = [AesCryptoGcm decryptWithCiphertextWithTagHex:ciphertextWithTag keyHex:key nonceHex:nonce aadHex:aad error:&error];
+            if (result == nil) {
+                reject(@"-1", error.localizedDescription ?: @"AES-GCM decrypt failed", error);
+            } else {
+                resolve(result);
+            }
+        } @catch (NSException *exception) {
+            reject(@"-1", exception.reason, nil);
         }
     });
 }
@@ -214,6 +320,11 @@ static NSData *aesCTR(NSString *operation, NSData *inputData, NSString *key, NSS
         resolve:(RCTPromiseResolveBlock)resolve
          reject:(RCTPromiseRejectBlock)reject
 {
+    ONEKEY_AES_REQUIRE_NON_EMPTY(password, @"pbkdf2", @"password", reject);
+    ONEKEY_AES_REQUIRE_NON_EMPTY(salt, @"pbkdf2", @"salt", reject);
+    ONEKEY_AES_REQUIRE_NON_EMPTY(algorithm, @"pbkdf2", @"algorithm", reject);
+    ONEKEY_AES_REQUIRE_POSITIVE(cost, @"pbkdf2", @"cost", reject);
+    ONEKEY_AES_REQUIRE_POSITIVE(length, @"pbkdf2", @"length", reject);
     dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
         @try {
             NSData *passwordData = fromHex(password);
@@ -241,12 +352,12 @@ static NSData *aesCTR(NSString *operation, NSData *inputData, NSString *key, NSS
                 (uint8_t *)hashKeyData.mutableBytes, hashKeyData.length);
 
             if (status == kCCParamError) {
-                reject(@"keygen_fail", @"Key derivation parameter error", nil);
+                reject(@"-1", @"Key derivation parameter error", nil);
             } else {
                 resolve(toHex(hashKeyData));
             }
         } @catch (NSException *exception) {
-            reject(@"keygen_fail", exception.reason, nil);
+            reject(@"-1", exception.reason, nil);
         }
     });
 }
@@ -258,13 +369,15 @@ static NSData *aesCTR(NSString *operation, NSData *inputData, NSString *key, NSS
         resolve:(RCTPromiseResolveBlock)resolve
          reject:(RCTPromiseRejectBlock)reject
 {
+    ONEKEY_AES_REQUIRE_NON_EMPTY(base64, @"hmac256", @"data", reject);
+    ONEKEY_AES_REQUIRE_NON_EMPTY(key, @"hmac256", @"key", reject);
     dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
         @try {
             NSData *keyData   = fromHex(key);
             NSData *inputData = fromHex(base64);
             void *buffer = malloc(CC_SHA256_DIGEST_LENGTH);
             if (!buffer) {
-                reject(@"hmac_fail", @"Memory allocation error", nil);
+                reject(@"-1", @"Memory allocation error", nil);
                 return;
             }
             CCHmac(kCCHmacAlgSHA256,
@@ -276,7 +389,7 @@ static NSData *aesCTR(NSString *operation, NSData *inputData, NSString *key, NSS
                                             freeWhenDone:YES];
             resolve(toHex(result));
         } @catch (NSException *exception) {
-            reject(@"hmac_fail", exception.reason, nil);
+            reject(@"-1", exception.reason, nil);
         }
     });
 }
@@ -288,13 +401,15 @@ static NSData *aesCTR(NSString *operation, NSData *inputData, NSString *key, NSS
         resolve:(RCTPromiseResolveBlock)resolve
          reject:(RCTPromiseRejectBlock)reject
 {
+    ONEKEY_AES_REQUIRE_NON_EMPTY(base64, @"hmac512", @"data", reject);
+    ONEKEY_AES_REQUIRE_NON_EMPTY(key, @"hmac512", @"key", reject);
     dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
         @try {
             NSData *keyData   = fromHex(key);
             NSData *inputData = fromHex(base64);
             void *buffer = malloc(CC_SHA512_DIGEST_LENGTH);
             if (!buffer) {
-                reject(@"hmac_fail", @"Memory allocation error", nil);
+                reject(@"-1", @"Memory allocation error", nil);
                 return;
             }
             CCHmac(kCCHmacAlgSHA512,
@@ -306,7 +421,7 @@ static NSData *aesCTR(NSString *operation, NSData *inputData, NSString *key, NSS
                                             freeWhenDone:YES];
             resolve(toHex(result));
         } @catch (NSException *exception) {
-            reject(@"hmac_fail", exception.reason, nil);
+            reject(@"-1", exception.reason, nil);
         }
     });
 }
@@ -317,6 +432,7 @@ static NSData *aesCTR(NSString *operation, NSData *inputData, NSString *key, NSS
      resolve:(RCTPromiseResolveBlock)resolve
       reject:(RCTPromiseRejectBlock)reject
 {
+    ONEKEY_AES_REQUIRE_NON_EMPTY(text, @"sha1", @"text", reject);
     dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
         @try {
             NSData *inputData = fromHex(text);
@@ -324,7 +440,7 @@ static NSData *aesCTR(NSString *operation, NSData *inputData, NSString *key, NSS
             CC_SHA1((const void *)inputData.bytes, (CC_LONG)inputData.length, (unsigned char *)result.mutableBytes);
             resolve(toHex(result));
         } @catch (NSException *exception) {
-            reject(@"sha1_fail", exception.reason, nil);
+            reject(@"-1", exception.reason, nil);
         }
     });
 }
@@ -335,12 +451,13 @@ static NSData *aesCTR(NSString *operation, NSData *inputData, NSString *key, NSS
        resolve:(RCTPromiseResolveBlock)resolve
         reject:(RCTPromiseRejectBlock)reject
 {
+    ONEKEY_AES_REQUIRE_NON_EMPTY(text, @"sha256", @"text", reject);
     dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
         @try {
             NSData *inputData = fromHex(text);
             unsigned char *buffer = (unsigned char *)malloc(CC_SHA256_DIGEST_LENGTH);
             if (!buffer) {
-                reject(@"sha256_fail", @"Memory allocation error", nil);
+                reject(@"-1", @"Memory allocation error", nil);
                 return;
             }
             CC_SHA256((const void *)inputData.bytes, (CC_LONG)inputData.length, buffer);
@@ -349,7 +466,7 @@ static NSData *aesCTR(NSString *operation, NSData *inputData, NSString *key, NSS
                                             freeWhenDone:YES];
             resolve(toHex(result));
         } @catch (NSException *exception) {
-            reject(@"sha256_fail", exception.reason, nil);
+            reject(@"-1", exception.reason, nil);
         }
     });
 }
@@ -360,12 +477,13 @@ static NSData *aesCTR(NSString *operation, NSData *inputData, NSString *key, NSS
        resolve:(RCTPromiseResolveBlock)resolve
         reject:(RCTPromiseRejectBlock)reject
 {
+    ONEKEY_AES_REQUIRE_NON_EMPTY(text, @"sha512", @"text", reject);
     dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
         @try {
             NSData *inputData = fromHex(text);
             unsigned char *buffer = (unsigned char *)malloc(CC_SHA512_DIGEST_LENGTH);
             if (!buffer) {
-                reject(@"sha512_fail", @"Memory allocation error", nil);
+                reject(@"-1", @"Memory allocation error", nil);
                 return;
             }
             CC_SHA512((const void *)inputData.bytes, (CC_LONG)inputData.length, buffer);
@@ -374,7 +492,7 @@ static NSData *aesCTR(NSString *operation, NSData *inputData, NSString *key, NSS
                                             freeWhenDone:YES];
             resolve(toHex(result));
         } @catch (NSException *exception) {
-            reject(@"sha512_fail", exception.reason, nil);
+            reject(@"-1", exception.reason, nil);
         }
     });
 }
@@ -389,7 +507,7 @@ static NSData *aesCTR(NSString *operation, NSData *inputData, NSString *key, NSS
             NSString *uuid = [[NSUUID UUID] UUIDString];
             resolve(uuid);
         } @catch (NSException *exception) {
-            reject(@"uuid_fail", exception.reason, nil);
+            reject(@"-1", exception.reason, nil);
         }
     });
 }
@@ -400,18 +518,19 @@ static NSData *aesCTR(NSString *operation, NSData *inputData, NSString *key, NSS
           resolve:(RCTPromiseResolveBlock)resolve
            reject:(RCTPromiseRejectBlock)reject
 {
+    ONEKEY_AES_REQUIRE_POSITIVE(length, @"randomKey", @"length", reject);
     dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
         @try {
             NSUInteger len = (NSUInteger)length;
             NSMutableData *data = [NSMutableData dataWithLength:len];
             int result = SecRandomCopyBytes(kSecRandomDefault, len, data.mutableBytes);
             if (result != errSecSuccess) {
-                reject(@"random_fail", @"Random key generation error", nil);
+                reject(@"-1", @"Random key generation error", nil);
             } else {
                 resolve(toHex(data));
             }
         } @catch (NSException *exception) {
-            reject(@"random_fail", exception.reason, nil);
+            reject(@"-1", exception.reason, nil);
         }
     });
 }

package/ios/AesCryptoGcm.swift

@@ -0,0 +1,144 @@
+import CryptoKit
+import Foundation
+
+@objc(AesCryptoGcm)
+public final class AesCryptoGcm: NSObject {
+  // AES-GCM nonce length: NIST SP 800-38D recommends 96 bits (12 bytes), and
+  // `CryptoKit.AES.GCM.Nonce(data:)` is the canonical 12-byte path. Locking
+  // the bridge layer to 12 bytes keeps Android (where GCMParameterSpec would
+  // otherwise accept other lengths) and iOS byte-compatible.
+  private static let gcmNonceLengthBytes = 12
+
+  @objc(encryptWithDataHex:keyHex:nonceHex:aadHex:error:)
+  public static func encrypt(
+    dataHex: String,
+    keyHex: String,
+    nonceHex: String,
+    aadHex: String,
+    error: NSErrorPointer
+  ) -> String? {
+    do {
+      // `dataHex` is intentionally NOT required to be non-empty: empty
+      // plaintext is a legitimate AEAD operation (produces the 16-byte
+      // authentication tag).
+      try requireNonEmpty(keyHex, method: "aesGcmEncrypt", paramName: "key")
+      try requireNonEmpty(nonceHex, method: "aesGcmEncrypt", paramName: "nonce")
+      try requireNonEmpty(aadHex, method: "aesGcmEncrypt", paramName: "aad")
+      let plaintext = try dataFromHex(dataHex)
+      let key = SymmetricKey(data: try dataFromHex(keyHex))
+      let nonce = try gcmNonce(fromHex: nonceHex, method: "aesGcmEncrypt")
+      let aad = try dataFromHex(aadHex)
+      let sealedBox = try AES.GCM.seal(plaintext, using: key, nonce: nonce, authenticating: aad)
+      var ciphertextWithTag = Data(sealedBox.ciphertext)
+      ciphertextWithTag.append(sealedBox.tag)
+      return hexFromData(ciphertextWithTag)
+    } catch let caughtError as NSError {
+      error?.pointee = caughtError
+      return nil
+    }
+  }
+
+  @objc(decryptWithCiphertextWithTagHex:keyHex:nonceHex:aadHex:error:)
+  public static func decrypt(
+    ciphertextWithTagHex: String,
+    keyHex: String,
+    nonceHex: String,
+    aadHex: String,
+    error: NSErrorPointer
+  ) -> String? {
+    do {
+      // `ciphertextWithTagHex` is intentionally NOT validated for non-emptiness
+      // here — the `encrypted.count < 16` check below is stronger and covers
+      // the empty-hex case.
+      try requireNonEmpty(keyHex, method: "aesGcmDecrypt", paramName: "key")
+      try requireNonEmpty(nonceHex, method: "aesGcmDecrypt", paramName: "nonce")
+      try requireNonEmpty(aadHex, method: "aesGcmDecrypt", paramName: "aad")
+      let encrypted = try dataFromHex(ciphertextWithTagHex)
+      if encrypted.count < 16 {
+        throw AesCryptoGcmError.invalidCiphertext
+      }
+      let ciphertext = encrypted.prefix(encrypted.count - 16)
+      let tag = encrypted.suffix(16)
+      let key = SymmetricKey(data: try dataFromHex(keyHex))
+      let nonce = try gcmNonce(fromHex: nonceHex, method: "aesGcmDecrypt")
+      let aad = try dataFromHex(aadHex)
+      let sealedBox = try AES.GCM.SealedBox(nonce: nonce, ciphertext: ciphertext, tag: tag)
+      let plaintext = try AES.GCM.open(sealedBox, using: key, authenticating: aad)
+      return hexFromData(plaintext)
+    } catch let caughtError as NSError {
+      error?.pointee = caughtError
+      return nil
+    }
+  }
+
+  // The GCM entry points enforce a strict non-empty contract on key / nonce /
+  // aad; `data` and `ciphertextWithTag` are allowed to be empty hex (the
+  // `< 16-byte` guard in decrypt handles the truncated case explicitly).
+  private static func requireNonEmpty(_ value: String, method: String, paramName: String) throws {
+    if value.isEmpty {
+      throw NSError(
+        domain: "AesCryptoGcmError",
+        code: 1,
+        userInfo: [NSLocalizedDescriptionKey: "\(method): \(paramName) must not be empty"]
+      )
+    }
+  }
+
+  private static func gcmNonce(fromHex hex: String, method: String) throws -> AES.GCM.Nonce {
+    let bytes = try dataFromHex(hex)
+    if bytes.count != gcmNonceLengthBytes {
+      throw NSError(
+        domain: "AesCryptoGcmError",
+        code: 2,
+        userInfo: [NSLocalizedDescriptionKey:
+          "\(method): nonce must be exactly \(gcmNonceLengthBytes) bytes (got \(bytes.count))"]
+      )
+    }
+    return try AES.GCM.Nonce(data: bytes)
+  }
+
+  private static func dataFromHex(_ hex: String) throws -> Data {
+    // Empty hex is reachable when callers pass empty plaintext (encrypt) or
+    // when the `< 16-byte` ciphertext check fires (decrypt) — return an
+    // empty `Data` so AES.GCM.seal can produce the bare 16-byte tag.
+    if hex.isEmpty {
+      return Data()
+    }
+    if hex.count % 2 != 0 {
+      throw AesCryptoGcmError.invalidHex
+    }
+
+    var data = Data(capacity: hex.count / 2)
+    var index = hex.startIndex
+    while index < hex.endIndex {
+      let nextIndex = hex.index(index, offsetBy: 2)
+      guard let byte = UInt8(hex[index..<nextIndex], radix: 16) else {
+        throw AesCryptoGcmError.invalidHex
+      }
+      data.append(byte)
+      index = nextIndex
+    }
+    return data
+  }
+
+  private static func hexFromData(_ data: Data) -> String {
+    data.map { String(format: "%02x", $0) }.joined()
+  }
+}
+
+// Use `LocalizedError` so that when these enum cases bridge to `NSError`,
+// `(error as NSError).localizedDescription` returns the message below instead
+// of Cocoa's default "The operation couldn't be completed. (... error N.)".
+private enum AesCryptoGcmError: LocalizedError {
+  case invalidHex
+  case invalidCiphertext
+
+  var errorDescription: String? {
+    switch self {
+    case .invalidHex:
+      return "AES-GCM: hex string must have even length and contain only [0-9a-fA-F]"
+    case .invalidCiphertext:
+      return "AES-GCM: ciphertextWithTag must be at least 16 bytes (the auth tag length)"
+    }
+  }
+}

package/lib/module/index.js

@@ -3,6 +3,48 @@
 import NativeAesCrypto from "./NativeAesCrypto.js";
 export const encrypt = NativeAesCrypto.encrypt.bind(NativeAesCrypto);
 export const decrypt = NativeAesCrypto.decrypt.bind(NativeAesCrypto);
+
+/**
+ * AES-256-GCM authenticated encryption.
+ *
+ * Contract (intentionally tighter than RFC 5116 / NIST SP 800-38D):
+ * - `data`, `key`, `nonce`, `aad` are lowercase hex strings.
+ * - `key` must be non-empty hex and decode to a valid AES key length
+ *   (16 / 24 / 32 bytes).
+ * - `nonce` must be **exactly** 12 bytes (24 hex chars). The standard
+ *   permits other lengths, but `CryptoKit.AES.GCM.Nonce` on iOS is the
+ *   12-byte canonical path; Android is locked to the same length to keep
+ *   ciphertexts byte-compatible across platforms.
+ * - `aad` must be non-empty. AEAD allows 0-byte AAD, but every consumer
+ *   of this module supplies an explicit context binding (envelope header
+ *   bytes / keyless AAD constants); empty AAD almost always means a
+ *   forgotten parameter and is rejected.
+ * - `data` MAY be empty — that yields a 16-byte tag with no ciphertext.
+ *
+ * @returns hex string `ciphertext || tag` (tag is always the last 16 bytes).
+ *
+ * @throws Promise rejects with code `"-1"` for any contract violation
+ *   (empty key / nonce / aad, wrong nonce length, malformed hex) or for
+ *   the underlying CryptoKit / JCE error.
+ */
+export const aesGcmEncrypt = NativeAesCrypto.aesGcmEncrypt.bind(NativeAesCrypto);
+
+/**
+ * AES-256-GCM authenticated decryption with the same contract as
+ * {@link aesGcmEncrypt}.
+ *
+ * - `ciphertextWithTag` is the hex form of `ciphertext || tag` produced
+ *   by {@link aesGcmEncrypt}; its decoded length must be `>= 16` bytes
+ *   (i.e. at least the auth tag).
+ * - `key` / `nonce` / `aad` must match the encryption call **byte for
+ *   byte**; any mismatch surfaces as a tag-verification rejection.
+ *
+ * @returns hex string of the recovered plaintext (may be empty).
+ *
+ * @throws Promise rejects with code `"-1"` for contract violations or
+ *   GCM tag mismatch (tampered ciphertext / tag / AAD / wrong key).
+ */
+export const aesGcmDecrypt = NativeAesCrypto.aesGcmDecrypt.bind(NativeAesCrypto);
 export const pbkdf2 = NativeAesCrypto.pbkdf2.bind(NativeAesCrypto);
 export const hmac256 = NativeAesCrypto.hmac256.bind(NativeAesCrypto);
 export const hmac512 = NativeAesCrypto.hmac512.bind(NativeAesCrypto);

package/lib/typescript/src/NativeAesCrypto.d.ts

@@ -2,6 +2,8 @@ import type { TurboModule } from 'react-native';
 export interface Spec extends TurboModule {
     encrypt(data: string, key: string, iv: string, algorithm: string): Promise<string>;
     decrypt(base64: string, key: string, iv: string, algorithm: string): Promise<string>;
+    aesGcmEncrypt(data: string, key: string, nonce: string, aad: string): Promise<string>;
+    aesGcmDecrypt(ciphertextWithTag: string, key: string, nonce: string, aad: string): Promise<string>;
     pbkdf2(password: string, salt: string, cost: number, length: number, algorithm: string): Promise<string>;
     hmac256(base64: string, key: string): Promise<string>;
     hmac512(base64: string, key: string): Promise<string>;

package/lib/typescript/src/index.d.ts

@@ -1,6 +1,46 @@
 import NativeAesCrypto from './NativeAesCrypto';
 export declare const encrypt: (data: string, key: string, iv: string, algorithm: string) => Promise<string>;
 export declare const decrypt: (base64: string, key: string, iv: string, algorithm: string) => Promise<string>;
+/**
+ * AES-256-GCM authenticated encryption.
+ *
+ * Contract (intentionally tighter than RFC 5116 / NIST SP 800-38D):
+ * - `data`, `key`, `nonce`, `aad` are lowercase hex strings.
+ * - `key` must be non-empty hex and decode to a valid AES key length
+ *   (16 / 24 / 32 bytes).
+ * - `nonce` must be **exactly** 12 bytes (24 hex chars). The standard
+ *   permits other lengths, but `CryptoKit.AES.GCM.Nonce` on iOS is the
+ *   12-byte canonical path; Android is locked to the same length to keep
+ *   ciphertexts byte-compatible across platforms.
+ * - `aad` must be non-empty. AEAD allows 0-byte AAD, but every consumer
+ *   of this module supplies an explicit context binding (envelope header
+ *   bytes / keyless AAD constants); empty AAD almost always means a
+ *   forgotten parameter and is rejected.
+ * - `data` MAY be empty — that yields a 16-byte tag with no ciphertext.
+ *
+ * @returns hex string `ciphertext || tag` (tag is always the last 16 bytes).
+ *
+ * @throws Promise rejects with code `"-1"` for any contract violation
+ *   (empty key / nonce / aad, wrong nonce length, malformed hex) or for
+ *   the underlying CryptoKit / JCE error.
+ */
+export declare const aesGcmEncrypt: (data: string, key: string, nonce: string, aad: string) => Promise<string>;
+/**
+ * AES-256-GCM authenticated decryption with the same contract as
+ * {@link aesGcmEncrypt}.
+ *
+ * - `ciphertextWithTag` is the hex form of `ciphertext || tag` produced
+ *   by {@link aesGcmEncrypt}; its decoded length must be `>= 16` bytes
+ *   (i.e. at least the auth tag).
+ * - `key` / `nonce` / `aad` must match the encryption call **byte for
+ *   byte**; any mismatch surfaces as a tag-verification rejection.
+ *
+ * @returns hex string of the recovered plaintext (may be empty).
+ *
+ * @throws Promise rejects with code `"-1"` for contract violations or
+ *   GCM tag mismatch (tampered ciphertext / tag / AAD / wrong key).
+ */
+export declare const aesGcmDecrypt: (ciphertextWithTag: string, key: string, nonce: string, aad: string) => Promise<string>;
 export declare const pbkdf2: (password: string, salt: string, cost: number, length: number, algorithm: string) => Promise<string>;
 export declare const hmac256: (base64: string, key: string) => Promise<string>;
 export declare const hmac512: (base64: string, key: string) => Promise<string>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onekeyfe/react-native-aes-crypto",
-  "version": "3.0.33",
+  "version": "3.0.35",
   "description": "react-native-aes-crypto",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",

package/src/NativeAesCrypto.ts

@@ -14,6 +14,8 @@ export interface Spec extends TurboModule {
     iv: string,
     algorithm: string,
   ): Promise<string>;
+  aesGcmEncrypt(data: string, key: string, nonce: string, aad: string): Promise<string>;
+  aesGcmDecrypt(ciphertextWithTag: string, key: string, nonce: string, aad: string): Promise<string>;
   pbkdf2(
     password: string,
     salt: string,

package/src/index.tsx

@@ -2,6 +2,50 @@ import NativeAesCrypto from './NativeAesCrypto';
 
 export const encrypt = NativeAesCrypto.encrypt.bind(NativeAesCrypto);
 export const decrypt = NativeAesCrypto.decrypt.bind(NativeAesCrypto);
+
+/**
+ * AES-256-GCM authenticated encryption.
+ *
+ * Contract (intentionally tighter than RFC 5116 / NIST SP 800-38D):
+ * - `data`, `key`, `nonce`, `aad` are lowercase hex strings.
+ * - `key` must be non-empty hex and decode to a valid AES key length
+ *   (16 / 24 / 32 bytes).
+ * - `nonce` must be **exactly** 12 bytes (24 hex chars). The standard
+ *   permits other lengths, but `CryptoKit.AES.GCM.Nonce` on iOS is the
+ *   12-byte canonical path; Android is locked to the same length to keep
+ *   ciphertexts byte-compatible across platforms.
+ * - `aad` must be non-empty. AEAD allows 0-byte AAD, but every consumer
+ *   of this module supplies an explicit context binding (envelope header
+ *   bytes / keyless AAD constants); empty AAD almost always means a
+ *   forgotten parameter and is rejected.
+ * - `data` MAY be empty — that yields a 16-byte tag with no ciphertext.
+ *
+ * @returns hex string `ciphertext || tag` (tag is always the last 16 bytes).
+ *
+ * @throws Promise rejects with code `"-1"` for any contract violation
+ *   (empty key / nonce / aad, wrong nonce length, malformed hex) or for
+ *   the underlying CryptoKit / JCE error.
+ */
+export const aesGcmEncrypt =
+  NativeAesCrypto.aesGcmEncrypt.bind(NativeAesCrypto);
+
+/**
+ * AES-256-GCM authenticated decryption with the same contract as
+ * {@link aesGcmEncrypt}.
+ *
+ * - `ciphertextWithTag` is the hex form of `ciphertext || tag` produced
+ *   by {@link aesGcmEncrypt}; its decoded length must be `>= 16` bytes
+ *   (i.e. at least the auth tag).
+ * - `key` / `nonce` / `aad` must match the encryption call **byte for
+ *   byte**; any mismatch surfaces as a tag-verification rejection.
+ *
+ * @returns hex string of the recovered plaintext (may be empty).
+ *
+ * @throws Promise rejects with code `"-1"` for contract violations or
+ *   GCM tag mismatch (tampered ciphertext / tag / AAD / wrong key).
+ */
+export const aesGcmDecrypt =
+  NativeAesCrypto.aesGcmDecrypt.bind(NativeAesCrypto);
 export const pbkdf2 = NativeAesCrypto.pbkdf2.bind(NativeAesCrypto);
 export const hmac256 = NativeAesCrypto.hmac256.bind(NativeAesCrypto);
 export const hmac512 = NativeAesCrypto.hmac512.bind(NativeAesCrypto);