@capgo/capacitor-native-biometric 5.0.1 → 5.1.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) Ariel Hernandez Musa.
+Copyright (c) Martin Donadieu.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -18,4 +18,4 @@ 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.
+SOFTWARE.

package/{readme.md → README.md}

@@ -9,9 +9,9 @@ Use biometrics confirm device owner presence or authenticate users. A couple of
 ## Usage
 
 ```ts
-import { NativeBiometric } from "@capgo/capacitor-native-biometric";
+import { NativeBiometric, BiometryType } from "@capgo/capacitor-native-biometric";
 
-async performBiometricVerificatin(){
+async performBiometricVerification(){
   const result = await NativeBiometric.isAvailable();
 
   if(!result.isAvailable) return;
@@ -46,6 +46,27 @@ NativeBiometric.deleteCredentials({
   server: "www.example.com",
 }).then();
 ```
+
+### Biometric Auth Errors
+
+This is a plugin specific list of error codes that can be thrown on verifyIdentity failure, or set as a part of isAvailable. It consolidates Android and iOS specific Authentication Error codes into one combined error list.
+
+| Code | Description                 | Platform                     |
+| ---- | --------------------------- | ---------------------------- |
+| 0    | Unknown Error               | Android, iOS                 |
+| 1    | Biometrics Unavailable      | Android, iOS                 |
+| 2    | User Lockout                | Android, iOS                 |
+| 3    | Biometrics Not Enrolled     | Android, iOS                 |
+| 4    | User Temporary Lockout      | Android (Lockout for 30sec)  |
+| 10   | Authentication Failed       | Android, iOS                 |
+| 11   | App Cancel                  | iOS                          |
+| 12   | Invalid Context             | iOS                          |
+| 13   | Not Interactive             | iOS                          |
+| 14   | Passcode Not Set            | Android, iOS                 |
+| 15   | System Cancel               | Android, iOS                 |
+| 16   | User Cancel                 | Android, iOS                 |
+| 17   | User Fallback               | Android, iOS                 |
+
 <docgen-index>
 
 * [`isAvailable(...)`](#isavailable)
@@ -64,7 +85,7 @@ NativeBiometric.deleteCredentials({
 ### isAvailable(...)
 
 ```typescript
-isAvailable(options?: IsAvailableOptions) => any
+isAvailable(options?: IsAvailableOptions | undefined) => any
 ```
 
 Checks if biometric authentication hardware is available.
@@ -83,7 +104,7 @@ Checks if biometric authentication hardware is available.
 ### verifyIdentity(...)
 
 ```typescript
-verifyIdentity(options?: BiometricOptions) => any
+verifyIdentity(options?: BiometricOptions | undefined) => any
 ```
 
 Prompts the user to authenticate with biometrics.
@@ -177,15 +198,16 @@ Deletes the stored credentials for a given server.
 
 #### BiometricOptions
 
-| Prop                     | Type                 | Description                                                                                                           | Default        |
-| ------------------------ | -------------------- | --------------------------------------------------------------------------------------------------------------------- | -------------- |
-| **`reason`**             | <code>string</code>  |                                                                                                                       |                |
-| **`title`**              | <code>string</code>  |                                                                                                                       |                |
-| **`subtitle`**           | <code>string</code>  |                                                                                                                       |                |
-| **`description`**        | <code>string</code>  |                                                                                                                       |                |
-| **`negativeButtonText`** | <code>string</code>  |                                                                                                                       |                |
-| **`useFallback`**        | <code>boolean</code> |                                                                                                                       |                |
-| **`maxAttempts`**        | <code>number</code>  | Only for Android. Set a maximum number of attempts for biometric authentication. The maximum allowed by android is 5. | <code>1</code> |
+| Prop                     | Type                 | Description                                                                                                                                                | Default        |
+| ------------------------ | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
+| **`reason`**             | <code>string</code>  |                                                                                                                                                            |                |
+| **`title`**              | <code>string</code>  |                                                                                                                                                            |                |
+| **`subtitle`**           | <code>string</code>  |                                                                                                                                                            |                |
+| **`description`**        | <code>string</code>  |                                                                                                                                                            |                |
+| **`negativeButtonText`** | <code>string</code>  |                                                                                                                                                            |                |
+| **`useFallback`**        | <code>boolean</code> | Specifies if should fallback to passcode authentication if biometric authentication fails.                                                                 |                |
+| **`fallbackTitle`**      | <code>string</code>  | Only for iOS. Set the text for the fallback button in the authentication dialog. If this property is not specified, the default text is set by the system. |                |
+| **`maxAttempts`**        | <code>number</code>  | Only for Android. Set a maximum number of attempts for biometric authentication. The maximum allowed by android is 5.                                      | <code>1</code> |
 
 
 #### GetCredentialOptions
@@ -224,15 +246,15 @@ Deletes the stored credentials for a given server.
 
 #### BiometryType
 
-| Members                   |
-| ------------------------- |
-| **`NONE`**                |
-| **`TOUCH_ID`**            |
-| **`FACE_ID`**             |
-| **`FINGERPRINT`**         |
-| **`FACE_AUTHENTICATION`** |
-| **`IRIS_AUTHENTICATION`** |
-| **`MULTIPLE`**            |
+| Members                   | Value          |
+| ------------------------- | -------------- |
+| **`NONE`**                | <code>0</code> |
+| **`TOUCH_ID`**            | <code>1</code> |
+| **`FACE_ID`**             | <code>2</code> |
+| **`FINGERPRINT`**         | <code>3</code> |
+| **`FACE_AUTHENTICATION`** | <code>4</code> |
+| **`IRIS_AUTHENTICATION`** | <code>5</code> |
+| **`MULTIPLE`**            | <code>6</code> |
 
 </docgen-api>
 ## Face ID (iOS)
@@ -278,6 +300,11 @@ public class MainActivity extends BridgeActivity {
 
 [Jonthia](https://github.com/jonthia)
 [One Click Web Studio](https://github.com/oneclickwebstudio)
+[Brian Weasner](https://github.com/brian-weasner)
+[Mohamed Diarra](https://github.com/mohdiarra)
+### Want to Contribute?
+
+Learn about contributing [HERE](./CONTRIBUTING.md)
 
 ## Notes
 

package/android/build.gradle

@@ -2,15 +2,16 @@ ext {
     junitVersion = project.hasProperty('junitVersion') ? rootProject.ext.junitVersion : '4.13.2'
     androidxJunitVersion = project.hasProperty('androidxJunitVersion') ? rootProject.ext.androidxJunitVersion : '1.1.5'
     androidxEspressoCoreVersion = project.hasProperty('androidxEspressoCoreVersion') ? rootProject.ext.androidxEspressoCoreVersion : '3.5.1'
+    androidxAppCompatVersion = project.hasProperty('androidxAppCompatVersion') ? rootProject.ext.androidxAppCompatVersion : '1.6.1'
 }
 
 buildscript {
     repositories {
         google()
-        jcenter()
+        mavenCentral()
     }
     dependencies {
-        classpath 'com.android.tools.build:gradle:8.0.0'
+        classpath 'com.android.tools.build:gradle:8.0.2'
     }
 }
 
@@ -39,20 +40,19 @@ android {
 
 repositories {
     google()
-    jcenter()
     mavenCentral()
 }
 
 
 dependencies {
-    implementation 'androidx.biometric:biometric:1.0.1'
+    implementation 'androidx.biometric:biometric:1.1.0'
     implementation fileTree(dir: 'libs', include: ['*.jar'])
     implementation project(':capacitor-android')
-    implementation 'androidx.appcompat:appcompat:1.1.0'
-    implementation 'com.google.android.material:material:1.1.0'
-    implementation 'androidx.constraintlayout:constraintlayout:1.1.3'
-    implementation 'androidx.navigation:navigation-fragment:2.0.0'
-    implementation 'androidx.navigation:navigation-ui:2.0.0'
+    implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
+    implementation 'com.google.android.material:material:1.9.0'
+    implementation 'androidx.constraintlayout:constraintlayout:2.1.4'
+    implementation 'androidx.navigation:navigation-fragment:2.5.3'
+    implementation 'androidx.navigation:navigation-ui:2.5.3'
     testImplementation "junit:junit:$junitVersion"
     androidTestImplementation "androidx.test.ext:junit:$androidxJunitVersion"
     androidTestImplementation "androidx.test.espresso:espresso-core:$androidxEspressoCoreVersion"

package/android/gradlew

@@ -85,9 +85,6 @@ done
 APP_BASE_NAME=${0##*/}
 APP_HOME=$( cd "${APP_HOME:-./}" && pwd -P ) || exit
 
-# Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
-DEFAULT_JVM_OPTS='"-Xmx64m" "-Xms64m"'
-
 # Use the maximum available, or set MAX_FD != -1 to use that value.
 MAX_FD=maximum
 
@@ -133,10 +130,13 @@ location of your Java installation."
     fi
 else
     JAVACMD=java
-    which java >/dev/null 2>&1 || die "ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
+    if ! command -v java >/dev/null 2>&1
+    then
+        die "ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
 
 Please set the JAVA_HOME variable in your environment to match the
 location of your Java installation."
+    fi
 fi
 
 # Increase the maximum file descriptors if we can.
@@ -197,6 +197,10 @@ if "$cygwin" || "$msys" ; then
     done
 fi
 
+
+# Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
+DEFAULT_JVM_OPTS='"-Xmx64m" "-Xms64m"'
+
 # Collect all arguments for the java command;
 #   * $DEFAULT_JVM_OPTS, $JAVA_OPTS, and $GRADLE_OPTS can contain fragments of
 #     shell script including quotes and variable substitutions, so put them in

package/android/src/main/java/ee/forgr/biometric/AuthActivity.java

@@ -4,15 +4,10 @@ import android.content.Intent;
 import android.os.Build;
 import android.os.Bundle;
 import android.os.Handler;
-import android.util.Log;
-import android.view.View;
 import androidx.annotation.NonNull;
 import androidx.appcompat.app.AppCompatActivity;
-import androidx.appcompat.widget.Toolbar;
 import androidx.biometric.BiometricPrompt;
 import ee.forgr.biometric.capacitornativebiometric.R;
-import com.google.android.material.floatingactionbutton.FloatingActionButton;
-import com.google.android.material.snackbar.Snackbar;
 import java.util.concurrent.Executor;
 
 public class AuthActivity extends AppCompatActivity {
@@ -40,29 +35,31 @@ public class AuthActivity extends AppCompatActivity {
         };
     }
 
-    BiometricPrompt.PromptInfo.Builder builder =
-      new BiometricPrompt.PromptInfo.Builder()
-        .setTitle(
-          getIntent().hasExtra("title")
-            ? getIntent().getStringExtra("title")
-            : "Authenticate"
-        )
-        .setSubtitle(
-          getIntent().hasExtra("subtitle")
-            ? getIntent().getStringExtra("subtitle")
-            : null
-        )
-        .setDescription(
-          getIntent().hasExtra("description")
-            ? getIntent().getStringExtra("description")
-            : null
-        );
+    BiometricPrompt.PromptInfo.Builder builder = new BiometricPrompt.PromptInfo.Builder()
+      .setTitle(
+        getIntent().hasExtra("title")
+          ? getIntent().getStringExtra("title")
+          : "Authenticate"
+      )
+      .setSubtitle(
+        getIntent().hasExtra("subtitle")
+          ? getIntent().getStringExtra("subtitle")
+          : null
+      )
+      .setDescription(
+        getIntent().hasExtra("description")
+          ? getIntent().getStringExtra("description")
+          : null
+      );
 
     boolean useFallback = getIntent().getBooleanExtra("useFallback", false);
 
     if (useFallback) {
+      // TODO: Deprecated function, probably want to migrate to `setAllowedAuthenticators`
       builder.setDeviceCredentialAllowed(true);
     } else {
+      // Note that this option is incompatible with device credential authentication and must NOT be set if the latter is enabled via `setAllowedAuthenticators` or `setDeviceCredentialAllowed`.
+      // @see https://developer.android.com/reference/androidx/biometric/BiometricPrompt.PromptInfo.Builder#setNegativeButtonText(java.lang.CharSequence)
       builder.setNegativeButtonText(
         getIntent().hasExtra("negativeButtonText")
           ? getIntent().getStringExtra("negativeButtonText")
@@ -82,8 +79,10 @@ public class AuthActivity extends AppCompatActivity {
           @NonNull CharSequence errString
         ) {
           super.onAuthenticationError(errorCode, errString);
-
-          finishActivity(errString.toString(), errorCode);
+          int pluginErrorCode = AuthActivity.convertToPluginErrorCode(
+            errorCode
+          );
+          finishActivity("error", pluginErrorCode, errString.toString());
         }
 
         @Override
@@ -91,14 +90,18 @@ public class AuthActivity extends AppCompatActivity {
           @NonNull BiometricPrompt.AuthenticationResult result
         ) {
           super.onAuthenticationSucceeded(result);
-          finishActivity("success", 0);
+          finishActivity("success");
         }
 
         @Override
         public void onAuthenticationFailed() {
           super.onAuthenticationFailed();
           counter++;
-          if (counter == maxAttempts) finishActivity("failed");
+          if (counter == maxAttempts) finishActivity(
+            "failed",
+            10,
+            "Authentication failed."
+          );
         }
       }
     );
@@ -107,23 +110,52 @@ public class AuthActivity extends AppCompatActivity {
   }
 
   void finishActivity(String result) {
-    Intent intent = new Intent();
-    intent.putExtra("result", "failed");
-    intent.putExtra("errorDetails", "Authentication failed.");
-    setResult(RESULT_OK, intent);
-    finish();
+    finishActivity(result, null, null);
   }
 
-  void finishActivity(String result, int errorCode) {
+  void finishActivity(String result, Integer errorCode, String errorDetails) {
     Intent intent = new Intent();
-    if (errorCode != 0) {
-      intent.putExtra("result", "error");
-      intent.putExtra("errorDetails", result);
+    intent.putExtra("result", result);
+    if (errorCode != null) {
       intent.putExtra("errorCode", String.valueOf(errorCode));
-    } else {
-      intent.putExtra("result", result);
+    }
+    if (errorDetails != null) {
+      intent.putExtra("errorDetails", errorDetails);
     }
     setResult(RESULT_OK, intent);
     finish();
   }
+
+  /**
+   * Convert Auth Error Codes to plugin expected Biometric Auth Errors (in README.md)
+   * This way both iOS and Android return the same error codes for the same authentication failure reasons.
+   * !!IMPORTANT!!: Whenever this is modified, check if similar function in iOS Plugin.swift needs to be modified as well
+   * @see <a href="https://developer.android.com/reference/androidx/biometric/BiometricPrompt#constants">...</a>
+   * @return BiometricAuthError
+   */
+  public static int convertToPluginErrorCode(int errorCode) {
+    switch (errorCode) {
+      case BiometricPrompt.ERROR_HW_UNAVAILABLE:
+      case BiometricPrompt.ERROR_HW_NOT_PRESENT:
+        return 1;
+      case BiometricPrompt.ERROR_LOCKOUT_PERMANENT:
+        return 2;
+      case BiometricPrompt.ERROR_NO_BIOMETRICS:
+        return 3;
+      case BiometricPrompt.ERROR_LOCKOUT:
+        return 4;
+      // Authentication Failure (10) Handled by `onAuthenticationFailed`.
+      // App Cancel (11), Invalid Context (12), and Not Interactive (13) are not valid error codes for Android.
+      case BiometricPrompt.ERROR_NO_DEVICE_CREDENTIAL:
+        return 14;
+      case BiometricPrompt.ERROR_TIMEOUT:
+      case BiometricPrompt.ERROR_CANCELED:
+        return 15;
+      case BiometricPrompt.ERROR_USER_CANCELED:
+      case BiometricPrompt.ERROR_NEGATIVE_BUTTON:
+        return 16;
+      default:
+        return 0;
+    }
+  }
 }