Merge pull request #22 from smallcase/device-passcode-biometrics-fallback

LonelyCpp · web-flow · commit 2bb8b1a65528 · 2025-08-25T20:45:30.000+05:30
feat(device-passcode-biometrics-fallback): add device passcode as fallback incase biometrics aren't enabled
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -0,0 +1,36 @@
+### Description
+
+Provide a brief description of the problem this PR solves and the solution implemented
+
+### Problem
+
+Describe the issue, bug, or enhancement you're addressing
+
+### Solution
+
+Explain how you've implemented the fix or feature
+
+### Manual Testing Checklist
+
+- [ ] Tested on iOS device/simulator
+- [ ] Tested on Android device/emulator
+
+### Screen Recordings
+
+Please attach screen recordings demonstrating the functionality on both platforms
+
+### Breaking Changes
+
+Document any breaking changes to the API
+
+### Related Issues
+
+Link to any related issues
+
+### Additional Notes
+
+Any additional information that reviewers should know
+
+---
+
+**Note**: Please ensure all screen recordings are uploaded and accessible to reviewers. If you're unable to provide screen recordings, please explain why and provide alternative testing evidence.
diff --git a/README.md b/README.md
@@ -6,7 +6,7 @@
 
 React Native Simple Biometrics is a straightforward and minimalistic React Native package designed to provide developers with an API for implementing user authentication using on-device biometrics. This library facilitates the quick verification of the app's user, ensuring that sensitive information is only accessible to authorized individuals, such as the phone owner or a trustee.
 
-![demo](./demo.gif?raw=true "demo")
+![demo](./demo.gif?raw=true 'demo')
 
 ## Installation
 
@@ -18,7 +18,7 @@ $ yarn add react-native-simple-biometrics
 
 ## Minimum Requirements
 
-- iOS target: `8.0`
+- iOS target: `10.0`
 - Android minSdkVersion: `21`
 
 ## iOS Permission
@@ -36,21 +36,55 @@ When you call the `authenticate` function, iOS users will be automatically promp
 
 React Native Simple Biometrics offers two main methods:
 
-1. `canAuthenticate()`: Checks whether the device supports biometric authentication. Returns `true` if the hardware is available or if permission for Face ID (iOS) was granted.
+1. `canAuthenticate(options?: Options)`: Checks whether the device supports biometric authentication. Returns `true` if the hardware is available or if permission for Face ID (iOS) was granted.
 
-2. `requestBioAuth(promptTitle: string, promptMessage: string)`: Initiates the biometric authentication process, displaying a user-friendly prompt with the specified title and message. This function can be used for user authentication.
+Parameters
+
+- `options` (optional): An object containing configuration options
+  - `allowDeviceCredentials` (boolean, default: true): Whether to allow device credentials (passcode/password) as a fallback when biometric authentication is not available
+
+Return Value
+
+Returns a Promise<boolean> that resolves to:
+
+- true if authentication is possible with the specified options
+- false if authentication is not possible
+
+2. `requestBioAuth(promptTitle: string, promptMessage: string, options?: Options)`: Initiates the biometric authentication process, displaying a user-friendly prompt with the specified title and message. This function can be used for user authentication.
+
+Required Parameters
+
+- `promptTitle` (string): The title displayed in the authentication dialog
+  Must be a non-empty string
+  Throws an error if not provided or empty
+- `promptMessage` (string): The subtitle/reason for requesting authentication
+  Must be a non-empty string
+  Throws an error if not provided or empty
+  Displays in the authentication dialog to explain why authentication is needed
+
+Optional Parameters
+
+- `options` (object, optional): Configuration options
+  - `allowDeviceCredentials` (boolean, default: true): Whether to allow device credentials (passcode/password) as a fallback when biometric authentication is not available
+
+Return Value
+
+Returns a Promise<boolean> that:
+
+- Resolves to true when authentication is successful
+- Rejects with an error when authentication fails or is cancelled
 
 Here's a code snippet demonstrating how to use these methods:
 
 ```javascript
-import RNBiometrics from "react-native-simple-biometrics";
+import RNBiometrics from 'react-native-simple-biometrics';
 
-// Check if biometric authentication is available
+// Check if biometric authentication is available, will fallback to device passcode by default if not
 const can = await RNBiometrics.canAuthenticate();
 
 if (can) {
   try {
-    await RNBiometrics.requestBioAuth("prompt-title", "prompt-message");
+    await RNBiometrics.requestBioAuth('prompt-title', 'prompt-message');
     // Code to execute when authenticated
     // ...
   } catch (error) {
@@ -62,4 +96,4 @@ if (can) {
 
 ## Credits
 
-React Native Simple Biometrics is a simplified version of [react-native-biometrics](https://www.npmjs.com/package/react-native-biometrics). If you require advanced features such as key generation, signatures, and more, consider using react-native-biometrics.
+React Native Simple Biometrics is a simplified version of [react-native-biometrics](https://www.npmjs.com/package/react-native-biometrics). If you require advanced features such as key generation, signatures, and more, consider using react-native-biometrics.
diff --git a/android/src/main/java/com/reactnativesimplebiometrics/SimpleBiometricsModule.java b/android/src/main/java/com/reactnativesimplebiometrics/SimpleBiometricsModule.java
@@ -1,9 +1,11 @@
 package com.reactnativesimplebiometrics;
 
 import android.app.Activity;
+
 import androidx.annotation.NonNull;
 
 import java.util.concurrent.Executor;
+
 import com.facebook.react.bridge.Promise;
 import com.facebook.react.bridge.ReactMethod;
 import com.facebook.react.bridge.UiThreadUtil;
@@ -16,16 +18,10 @@
 import androidx.core.content.ContextCompat;
 import androidx.fragment.app.FragmentActivity;
 
-
-
 @ReactModule(name = SimpleBiometricsModule.NAME)
 public class SimpleBiometricsModule extends ReactContextBaseJavaModule {
     public static final String NAME = "SimpleBiometrics";
 
-    static final int authenticators =  BiometricManager.Authenticators.BIOMETRIC_STRONG
-        | BiometricManager.Authenticators.BIOMETRIC_WEAK
-        | BiometricManager.Authenticators.DEVICE_CREDENTIAL;
-
     public SimpleBiometricsModule(ReactApplicationContext reactContext) {
         super(reactContext);
     }
@@ -36,12 +32,27 @@ public String getName() {
         return NAME;
     }
 
+    /**
+     * Helper to choose allowed authenticators depending on API level and JS param.
+     */
+    private int getAllowedAuthenticators(boolean allowDeviceCredentials) {
+        if (allowDeviceCredentials) {
+            return BiometricManager.Authenticators.BIOMETRIC_STRONG |
+                    BiometricManager.Authenticators.BIOMETRIC_WEAK |
+                    BiometricManager.Authenticators.DEVICE_CREDENTIAL;
+        }
+        // Default to biometrics only
+        return BiometricManager.Authenticators.BIOMETRIC_STRONG |
+                BiometricManager.Authenticators.BIOMETRIC_WEAK;
+    }
+
     @ReactMethod
-    public void canAuthenticate(Promise promise) {
+    public void canAuthenticate(boolean allowDeviceCredentials, Promise promise) {
         try {
             ReactApplicationContext context = getReactApplicationContext();
             BiometricManager biometricManager = BiometricManager.from(context);
 
+            int authenticators = getAllowedAuthenticators(allowDeviceCredentials);
             int res = biometricManager.canAuthenticate(authenticators);
             boolean can = res == BiometricManager.BIOMETRIC_SUCCESS;
 
@@ -52,7 +63,8 @@ public void canAuthenticate(Promise promise) {
     }
 
     @ReactMethod
-    public void requestBioAuth(final String title, final String subtitle, final Promise promise) {
+    public void requestBioAuth(final String title, final String subtitle, final boolean allowDeviceCredentials,
+            final Promise promise) {
         UiThreadUtil.runOnUiThread(
                 new Runnable() {
                     @Override
@@ -69,15 +81,18 @@ public void onAuthenticationError(int errorCode, @NonNull CharSequence errString
                                 }
 
                                 @Override
-                                public void onAuthenticationSucceeded(@NonNull BiometricPrompt.AuthenticationResult result) {
+                                public void onAuthenticationSucceeded(
+                                        @NonNull BiometricPrompt.AuthenticationResult result) {
                                     super.onAuthenticationSucceeded(result);
                                     promise.resolve(true);
                                 }
                             };
 
                             if (activity != null) {
-                                BiometricPrompt prompt = new BiometricPrompt((FragmentActivity) activity, mainExecutor, authenticationCallback);
+                                BiometricPrompt prompt = new BiometricPrompt((FragmentActivity) activity, mainExecutor,
+                                        authenticationCallback);
 
+                                int authenticators = getAllowedAuthenticators(allowDeviceCredentials);
                                 BiometricPrompt.PromptInfo promptInfo = new BiometricPrompt.PromptInfo.Builder()
                                         .setAllowedAuthenticators(authenticators)
                                         .setTitle(title)
@@ -92,8 +107,7 @@ public void onAuthenticationSucceeded(@NonNull BiometricPrompt.AuthenticationRes
                             promise.reject(e);
                         }
                     }
-                }
-        );
+                });
 
     }
 }
diff --git a/ios/SimpleBiometrics.mm b/ios/SimpleBiometrics.mm
@@ -10,58 +10,80 @@
 @implementation SimpleBiometrics
 RCT_EXPORT_MODULE()
 
-RCT_REMAP_METHOD(canAuthenticate,
-                 canAuthenticateWithResolver:(RCTPromiseResolveBlock)resolve
-                 rejecter:(RCTPromiseRejectBlock)reject)
-{
-    LAContext *context = [[LAContext alloc] init];
-    NSError *la_error = nil;
-    BOOL canEvaluatePolicy = [context canEvaluatePolicy:LAPolicyDeviceOwnerAuthenticationWithBiometrics error:&la_error];
-
-    if (canEvaluatePolicy) {
-        resolve(@(YES));
-    } else {
-        resolve(@(NO));
-    }
+- (LAPolicy)getLocalAuthPolicy:(BOOL)allowDeviceCredentials {
+  if (allowDeviceCredentials) {
+    // LAPolicyDeviceOwnerAuthentication allows authentication using
+    // biometrics (Face ID/Touch ID) or device passcode.
+    // If biometry is available, enrolled, and not disabled, the system
+    // uses that first. When these options aren’t available, the system
+    // prompts the user for the device passcode or user’s password.
+    return LAPolicyDeviceOwnerAuthentication;
+  } else {
+    // LAPolicyDeviceOwnerAuthenticationWithBiometrics policy evaluation
+    // fails if Touch ID or Face ID is unavailable or not enrolled.
+    return LAPolicyDeviceOwnerAuthenticationWithBiometrics;
+  }
 }
 
-RCT_REMAP_METHOD(requestBioAuth,
-                 title:(NSString *)title
-                 subtitle:(NSString *)subtitle
-                 requestBioAuthWithResolver:(RCTPromiseResolveBlock)resolve
-                 rejecter:(RCTPromiseRejectBlock)reject)
-{
+RCT_REMAP_METHOD(canAuthenticate, allowDeviceCredentials
+                 : (BOOL)allowDeviceCredentials canAuthenticateWithResolver
+                 : (RCTPromiseResolveBlock)resolve rejecter
+                 : (RCTPromiseRejectBlock)reject) {
+  LAContext *context = [[LAContext alloc] init];
+  NSError *la_error = nil;
 
-    dispatch_async(dispatch_get_global_queue( DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
+  LAPolicy localAuthPolicy = [self getLocalAuthPolicy:allowDeviceCredentials];
+
+  BOOL canEvaluatePolicy = [context canEvaluatePolicy:localAuthPolicy
+                                                error:&la_error];
+
+  if (canEvaluatePolicy) {
+    resolve(@(YES));
+  } else {
+    resolve(@(NO));
+  }
+}
+
+RCT_REMAP_METHOD(requestBioAuth, title
+                 : (NSString *)title subtitle
+                 : (NSString *)subtitle allowDeviceCredentials
+                 : (BOOL)allowDeviceCredentials requestBioAuthWithResolver
+                 : (RCTPromiseResolveBlock)resolve rejecter
+                 : (RCTPromiseRejectBlock)reject) {
+
+  dispatch_async(
+      dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
         NSString *promptMessage = subtitle;
 
         LAContext *context = [[LAContext alloc] init];
         context.localizedFallbackTitle = nil;
 
-        LAPolicy localAuthPolicy = LAPolicyDeviceOwnerAuthenticationWithBiometrics;
-        if (![[UIDevice currentDevice].systemVersion hasPrefix:@"8."]) {
-            localAuthPolicy = LAPolicyDeviceOwnerAuthentication;
-        }
-
-        [context evaluatePolicy:localAuthPolicy localizedReason:promptMessage reply:^(BOOL success, NSError *biometricError) {
-            if (success) {
-                resolve( @(YES));
+        LAPolicy localAuthPolicy =
+            [self getLocalAuthPolicy:allowDeviceCredentials];
 
-            } else {
-                NSString *message = [NSString stringWithFormat:@"%@", biometricError.localizedDescription];
-                reject(@"biometric_error", message, nil);
-            }
-        }];
-    });
+        [context evaluatePolicy:localAuthPolicy
+                localizedReason:promptMessage
+                          reply:^(BOOL success, NSError *biometricError) {
+                            if (success) {
+                              resolve(@(YES));
 
+                            } else {
+                              NSString *message = [NSString
+                                  stringWithFormat:@"%@",
+                                                   biometricError
+                                                       .localizedDescription];
+                              reject(@"biometric_error", message, nil);
+                            }
+                          }];
+      });
 }
 
 // Don't compile this code when we build for the old architecture.
 #ifdef RCT_NEW_ARCH_ENABLED
 - (std::shared_ptr<facebook::react::TurboModule>)getTurboModule:
-    (const facebook::react::ObjCTurboModule::InitParams &)params
-{
-    return std::make_shared<facebook::react::NativeSimpleBiometricsSpecJSI>(params);
+    (const facebook::react::ObjCTurboModule::InitParams &)params {
+  return std::make_shared<facebook::react::NativeSimpleBiometricsSpecJSI>(
+      params);
 }
 #endif
 
diff --git a/ios/SimpleBiometrics.xcodeproj/project.pbxproj b/ios/SimpleBiometrics.xcodeproj/project.pbxproj
@@ -176,7 +176,7 @@
 				GCC_WARN_UNINITIALIZED_AUTOS = YES_AGGRESSIVE;
 				GCC_WARN_UNUSED_FUNCTION = YES;
 				GCC_WARN_UNUSED_VARIABLE = YES;
-				IPHONEOS_DEPLOYMENT_TARGET = 8.0;
+				IPHONEOS_DEPLOYMENT_TARGET = 10.0;
 				MTL_ENABLE_DEBUG_INFO = YES;
 				ONLY_ACTIVE_ARCH = YES;
 				SDKROOT = iphoneos;
@@ -220,7 +220,7 @@
 				GCC_WARN_UNINITIALIZED_AUTOS = YES_AGGRESSIVE;
 				GCC_WARN_UNUSED_FUNCTION = YES;
 				GCC_WARN_UNUSED_VARIABLE = YES;
-				IPHONEOS_DEPLOYMENT_TARGET = 8.0;
+				IPHONEOS_DEPLOYMENT_TARGET = 10.0;
 				MTL_ENABLE_DEBUG_INFO = NO;
 				SDKROOT = iphoneos;
 				VALIDATE_PRODUCT = YES;
diff --git a/src/index.tsx b/src/index.tsx
