@aparajita/capacitor-biometric-auth 5.2.0 → 6.0.0

package/README.md

@@ -6,7 +6,7 @@ This plugin for [Capacitor 5](https://capacitorjs.com) provides access to native
 
 👉 **NOTE:** This plugin only works with Capacitor 5. If you are upgrading from the Capacitor 2 version, note that the plugin name has changed to `BiometricAuth`.
 
-🛑 **BREAKING CHANGE:** If you are upgrading from a version prior to 3.0.0, please note that `androidMaxAttempts` is no longer supported. See the documentation for [`authenticate()`](#authenticate) for more information.
+🛑 **BREAKING CHANGE:** If you are upgrading from a version prior to 6.0.0, please note that [`authenticate()`](#authenticate) now throws an instance of `BiometryError`, and `BiometryError.code` is now typed as [`BiometryErrorType`](#biometryerrortype).
 
 ## Demos
 
@@ -24,29 +24,103 @@ pnpm add @aparajita/capacitor-biometric-auth
 
 Not using [pnpm](https://pnpm.js.org/)? You owe it to yourself to give it a try. It’s faster, better with monorepos, and uses _way, way_ less disk space than the alternatives.
 
+### iOS
+
+👉 **IMPORTANT!!** In order to use Face ID, you must add the `NSFaceIDUsageDescription` key to your `Info.plist` file. This is a string that describes why your app needs access to Face ID. If you don’t add this key, the system won’t allow your app to use Face ID.
+
+1. In Xcode, open your app’s `Info.plist` file.
+2. Hover your mouse over one of the existing keys, and click the `+` button that appears.
+3. In the popup that appears, type `Privacy - Face ID Usage Description` and press Enter.
+4. In the Value column, enter a string that describes why your app needs access to Face ID.
+5. Save your changes.
+
 ## Usage
 
 The API is extensively documented in the [TypeScript definitions file](src/definitions.ts). There is also (somewhat incomplete auto-generated) documentation [below](#api). For a complete example of how to use this plugin in practice, see the [demo app](https://github.com/aparajita/capacitor-biometric-auth-demo).
 
-> **NOTE:** Your Android app must use a base theme named "AppTheme".
+👉 **NOTE:** Your Android app must use a base theme named "AppTheme".
 
 ### Checking availability
 
-Before giving the user the option to use biometry (such as displaying a biometry icon), call [`checkBiometry`](#checkbiometry) and inspect the [`CheckBiometryResult`](#checkbiometryresult) to see what (if any) biometry is available on the device. Note that `isAvailable` may be `false` but `biometryType` may indicate the presence of biometry on the device. This occurs if the current user is not enrolled in biometry, or if biometry has been disabled for the current app. In such cases the `reason` and `code` will tell you why.
+Before giving the user the option to use biometry (such as displaying a biometry icon), call [`checkBiometry()`](#checkbiometry) and inspect the [`CheckBiometryResult`](#checkbiometryresult) to see what (if any) biometry is available on the device. Note the following:
 
-Because the availability of biometry can change while your app is in the background, it’s important to check availability when your app resumes. By calling [`addResumeListener`](#addresumelistener) you can register a callback that is passed a [`CheckBiometryResult`](#checkbiometryresult) when your app resumes.
+- `isAvailable` may be `false` but `biometryType` may indicate the presence of biometry on the device. This occurs if the current user is not enrolled in biometry, or if biometry has been disabled for the current app. In such cases the `reason` and `code` will tell you why.
+
+- `biometryTypes` may contain more than one type of biometry. This occurs on Android devices that support multiple types of biometry. In such cases the `biometryType` will indicate the primary (most secure) type of biometry, and the `biometryTypes` array will contain all of the biometry types supported by the device. Note that Android only guarantees that one of the types is actually available.
+
+Because the availability of biometry can change while your app is in the background, it’s important to check availability when your app resumes. By calling [`addResumeListener()`](#addresumelistener) you can register a callback that is passed a [`CheckBiometryResult`](#checkbiometryresult) when your app resumes.
+
+#### Example
+
+```typescript
+import { CheckBiometryResult } from './definitions'
+
+let appListener: PluginListenerHandle
+
+function updateBiometryInfo(info: CheckBiometryResult): void {
+  if (info.isAvailable) {
+    // Biometry is available, info.biometryType will tell you the primary type.
+  } else {
+    // Biometry is not available, info.reason and info.code will tell you why.
+  }
+}
+
+async function onComponentMounted(): Promise<void> {
+  updateBiometryInfo(await BiometricAuth.checkBiometry())
+
+  try {
+    appListener = await BiometricAuth.addResumeListener(updateBiometryInfo)
+  } catch (error) {
+    if (error instanceof Error) {
+      console.error(error.message)
+    }
+  }
+}
+
+async function onComponentUnmounted(): Promise<void> {
+  await appListener?.remove()
+}
+```
 
 ### Authenticating
 
-Once you have determined that biometry is available, to initiate biometric authentication call [`authenticate`](#authenticate). `authenticate` takes an [`AuthenticateOptions`](#authenticateoptions) object which you will want to use in order to control the behavior and appearance of the biometric prompt.
+To initiate biometric authentication call [`authenticate()`](#authenticate). `authenticate` takes an [`AuthenticateOptions`](#authenticateoptions) object which you will want to use in order to control the behavior and appearance of the biometric prompt.
 
-If authentication succeeds, the Promise resolves. If authentication fails, the Promise is rejected with a `BiometryError`, which has two properties:
+If authentication succeeds, the Promise resolves. If authentication fails, the Promise is rejected with an instance of [`BiometryError`](#biometryerror), which has two properties:
 
 | Property | Type                                                                                                    | Description                                       |
 | :------- | :------------------------------------------------------------------------------------------------------ | :------------------------------------------------ |
 | message  | string                                                                                                  | A description of the error suitable for debugging |
 | code     | [BiometryErrorType](https://github.com/aparajita/capacitor-biometric-auth/blob/main/src/definitions.ts) | What caused the error                             |
 
+#### Example
+
+```typescript
+import { BiometryError, BiometryErrorType } from './definitions'
+
+async function authenticate(): Promise<void> {
+  try {
+    await BiometricAuth.authenticate({
+      reason: 'Please authenticate',
+      cancelTitle: 'Cancel',
+      allowDeviceCredential: true,
+      iosFallbackTitle: 'Use passcode',
+      androidTitle: 'Biometric login',
+      androidSubtitle: 'Log in using biometric authentication',
+      androidConfirmationRequired: false,
+    })
+  } catch (error) {
+    // error is always an instance of BiometryError.
+    if (error instanceof BiometryError) {
+      if (error.code !== BiometryErrorType.userCancel) {
+        // Display the error.
+        await showAlert(error.message)
+      }
+    }
+  }
+}
+```
+
 ## Biometry support
 
 ### web
@@ -59,7 +133,7 @@ On iOS, Touch ID and Face ID are supported.
 
 ### Android
 
-On Android, fingerprint, face, and iris authentication are supported. Note that if a device supports more than one type of biometry, the plugin will only present the primary type, which is determined by the system.
+On Android, fingerprint, face, and iris authentication are supported. Note that if a device supports more than one type of biometry, the plugin will only present the primary (most secure) type, which is determined by the system.
 
 ## API
 
@@ -77,6 +151,8 @@ On Android, fingerprint, face, and iris authentication are supported. Note that
 <docgen-api>
 <!--Update the source file JSDoc comments and rerun docgen to update the docs below-->
 
+This is the public interface of the plugin.
+
 ### checkBiometry()
 
 ```typescript
@@ -123,7 +199,7 @@ Prompt the user for authentication. If authorization fails for any reason, the p
 addResumeListener(listener: ResumeListener) => Promise<PluginListenerHandle>
 ```
 
-Register a function that will be called when the app resumes. The function will be passed the result of `checkBiometry()`.
+Register a function that will be called when the app resumes. The function will be passed the result of `checkBiometry()`.<br><br>👉 **NOTE:** checkBiometry() must be called at least once before calling this method.
 
 | Param    | Type                                         |
 | :------- | :------------------------------------------- |
@@ -137,13 +213,13 @@ Register a function that will be called when the app resumes. The function will
 
 #### CheckBiometryResult
 
-| Prop          | Type                                               | Description                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| :------------ | :------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| isAvailable   | boolean                                            | True if the device has biometric authentication capability and the current user has enrolled in some form of biometry.                                                                                                                                                                                                                                                                                                                           |
-| biometryType  | <a href="#biometrytype">BiometryType</a>           | The primary type of biometry available on the device. If the device supports both fingerprint and face authentication, this will be <a href="#biometrytype">`BiometryType.touchId`</a>.                                                                                                                                                                                                                                                          |
-| biometryTypes | BiometryType[]                                     | All of the biometry types supported by the device (currently only Android devices support multiple biometry types). If no biometry is available, this will be an empty array. If multiple types are supported, Android only guarantees that one of them is actually available.                                                                                                                                                                   |
-| reason        | string                                             | If biometry is not available and the system gives a reason why, it will be returned here. Otherwise it's an empty string.                                                                                                                                                                                                                                                                                                                        |
-| code          | <a href="#biometryerrortype">BiometryErrorType</a> | If biometry is not available, the error code will be returned here. Otherwise it's an empty string. The error code will be one of the <a href="#biometryerrortype">`BiometryErrorType`</a> enum values, and is consistent across platforms. This allows you to check for specific errors in a platform- independent way, for example:<br><br>if (result.code === <a href="#biometryerrortype">BiometryErrorType.biometryNotEnrolled</a>) { ... } |
+| Prop          | Type                                               | Description                                                                                                                                                                                                                                                                    |
+| :------------ | :------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| isAvailable   | boolean                                            | True if the device has biometric authentication capability and the current user has enrolled in some form of biometry.                                                                                                                                                         |
+| biometryType  | <a href="#biometrytype">BiometryType</a>           | The primary type of biometry available on the device. If the device supports both fingerprint and face authentication, this will be <a href="#biometrytype">`BiometryType.touchId`</a>.                                                                                        |
+| biometryTypes | BiometryType[]                                     | All of the biometry types supported by the device (currently only Android devices support multiple biometry types). If no biometry is available, this will be an empty array. If multiple types are supported, Android only guarantees that one of them is actually available. |
+| reason        | string                                             | If biometry is not available and the system gives a reason why, it will be returned here. Otherwise it's an empty string.                                                                                                                                                      |
+| code          | <a href="#biometryerrortype">BiometryErrorType</a> | If biometry is not available, the error code will be returned here. Otherwise it's an empty string. The error code will be one of the <a href="#biometryerrortype">`BiometryErrorType`</a> enum values, and is consistent across platforms.                                    |
 
 #### AuthenticateOptions
 
@@ -155,7 +231,7 @@ Register a function that will be called when the app resumes. The function will
 | iosFallbackTitle            | string  | The system presents a fallback button when biometric authentication fails — for example, because the system doesn’t recognize the presented finger, or after several failed attempts to recognize the user’s face.<br><br>If `allowDeviceCredential` is false, tapping this button dismisses the authentication dialog and returns the error code userFallback. If undefined, the localized system default title is used. Passing an empty string hides the fallback button completely.<br><br>If `allowDeviceCredential` is true and this is undefined, the localized system default title is used.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | androidTitle                | string  | Title for the Android dialog. If not supplied, the system default is used.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | androidSubtitle             | string  | Subtitle for the Android dialog. If not supplied, the system default is used.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| androidConfirmationRequired | boolean | For information on this setting, see:<br><br>https://developer.android.com/reference/android/hardware/biometrics/BiometricPrompt.Builder#setConfirmationRequired(boolean)<br><br>If not set, defaults to true.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| androidConfirmationRequired | boolean | If not set, defaults to true.<br><br>For information on this setting, see https://developer.android.com/reference/android/hardware/biometrics/BiometricPrompt.Builder#setConfirmationRequired(boolean).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 
 #### PluginListenerHandle
 

package/android/src/main/java/com/aparajita/capacitor/biometricauth/BiometricAuthNative.java

@@ -96,6 +96,13 @@ public class BiometricAuthNative extends Plugin {
    */
   @PluginMethod
   public void checkBiometry(PluginCall call) {
+    call.resolve(checkDeviceBiometry());
+  }
+
+  /**
+   * Check the device's availability and type of biometric authentication.
+   */
+  private JSObject checkDeviceBiometry() {
     BiometricManager manager = BiometricManager.from(getContext());
     int biometryResult;
 
@@ -106,14 +113,14 @@ public class BiometricAuthNative extends Plugin {
       biometryResult = manager.canAuthenticate();
     }
 
-    JSObject ret = new JSObject();
-    ret.put(
+    JSObject result = new JSObject();
+    result.put(
       "isAvailable",
       biometryResult == BiometricManager.BIOMETRIC_SUCCESS
     );
 
     biometryTypes = getDeviceBiometryTypes();
-    ret.put("biometryType", biometryTypes.get(0).getType());
+    result.put("biometryType", biometryTypes.get(0).getType());
 
     JSArray returnTypes = new JSArray();
 
@@ -121,7 +128,7 @@ public class BiometricAuthNative extends Plugin {
       returnTypes.put(type.getType());
     }
 
-    ret.put("biometryTypes", returnTypes);
+    result.put("biometryTypes", returnTypes);
 
     String reason = "";
 
@@ -156,13 +163,13 @@ public class BiometricAuthNative extends Plugin {
       errorCode = "biometryNotAvailable";
     }
 
-    ret.put("reason", reason);
-    ret.put("code", errorCode);
-    call.resolve(ret);
+    result.put("reason", reason);
+    result.put("code", errorCode);
+    return result;
   }
 
   private ArrayList<BiometryType> getDeviceBiometryTypes() {
-    ArrayList<BiometryType> types = new ArrayList<BiometryType>();
+    ArrayList<BiometryType> types = new ArrayList<>();
     PackageManager manager = getContext().getPackageManager();
 
     if (manager.hasSystemFeature(PackageManager.FEATURE_FINGERPRINT)) {
@@ -188,7 +195,18 @@ public class BiometricAuthNative extends Plugin {
    * Prompt the user for biometric authentication.
    */
   @PluginMethod
-  public void authenticate(final PluginCall call) {
+  public void internalAuthenticate(final PluginCall call) {
+    // Make sure biometry is available
+    JSObject checkResult = checkDeviceBiometry();
+
+    if (Boolean.FALSE.equals(checkResult.getBoolean("isAvailable", false))) {
+      call.reject(
+        checkResult.getString("reason", ""),
+        checkResult.getString("code", "")
+      );
+      return;
+    }
+
     // The result of an intent is supposed to have the package name as a prefix
     RESULT_EXTRA_PREFIX = getContext().getPackageName() + ".";
 
@@ -279,23 +297,19 @@ public class BiometricAuthNative extends Plugin {
     );
 
     switch (resultType) {
-      case SUCCESS:
-        call.resolve();
-        break;
-      case FAILURE:
-        // Biometry was successfully presented but was not recognized
-        call.reject(errorMessage, BIOMETRIC_FAILURE);
-        break;
-      case ERROR:
-        // The user cancelled, the system cancelled, or some error occurred.
-        // If the user cancelled, errorMessage is the text of the "negative" button,
-        // which is not especially descriptive.
+      case SUCCESS -> call.resolve();
+      // Biometry was successfully presented but was not recognized
+      case FAILURE -> call.reject(errorMessage, BIOMETRIC_FAILURE);
+      // The user cancelled, the system cancelled, or some error occurred.
+      // If the user cancelled, errorMessage is the text of the "negative" button,
+      // which is not especially descriptive.
+      case ERROR -> {
         if (errorCode == BiometricPrompt.ERROR_NEGATIVE_BUTTON) {
           errorMessage = "Cancel button was pressed";
         }
 
         call.reject(errorMessage, biometryErrorCodeMap.get(errorCode));
-        break;
+      }
     }
   }
 

package/dist/esm/base.d.ts

@@ -4,6 +4,7 @@ import type { AuthenticateOptions, BiometricAuthPlugin, CheckBiometryResult, Res
 export declare abstract class BiometricAuthBase extends WebPlugin implements BiometricAuthPlugin {
     abstract setBiometryType(type: BiometryType | string | undefined): Promise<void>;
     abstract checkBiometry(): Promise<CheckBiometryResult>;
-    abstract authenticate(options?: AuthenticateOptions): Promise<void>;
+    authenticate(options?: AuthenticateOptions): Promise<void>;
+    protected abstract internalAuthenticate(options?: AuthenticateOptions): Promise<void>;
     addResumeListener(listener: ResumeListener): Promise<PluginListenerHandle> & PluginListenerHandle;
 }

package/dist/esm/base.js

@@ -1,7 +1,25 @@
 import { App } from '@capacitor/app';
-import { WebPlugin } from '@capacitor/core';
+import { CapacitorException, WebPlugin } from '@capacitor/core';
+import { BiometryError } from './definitions';
 // eslint-disable-next-line import/prefer-default-export
 export class BiometricAuthBase extends WebPlugin {
+    async authenticate(options) {
+        try {
+            await this.internalAuthenticate(options);
+        }
+        catch (error) {
+            // error will be an instance of CapacitorException on native platforms,
+            // an instance of BiometryError on the web.
+            if (error instanceof CapacitorException) {
+                throw new BiometryError(error.message, 
+                // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- error.data values are typed as any
+                error.data.code);
+            }
+            else {
+                throw error;
+            }
+        }
+    }
     addResumeListener(listener) {
         return App.addListener('appStateChange', ({ isActive }) => {
             if (isActive) {

package/dist/esm/definitions.d.ts

@@ -1,4 +1,4 @@
-import type { PluginListenerHandle, PluginResultError, WebPlugin } from '@capacitor/core';
+import type { PluginListenerHandle, WebPlugin } from '@capacitor/core';
 export declare enum BiometryType {
     /**
      * No biometry is available
@@ -101,17 +101,15 @@ export interface AuthenticateOptions {
      */
     androidSubtitle?: string;
     /**
-     * For information on this setting, see:
-     *
-     * https://developer.android.com/reference/android/hardware/biometrics/BiometricPrompt.Builder#setConfirmationRequired(boolean)
-     *
      * If not set, defaults to true.
+     *
+     * For information on this setting, see https://developer.android.com/reference/android/hardware/biometrics/BiometricPrompt.Builder#setConfirmationRequired(boolean).
      */
     androidConfirmationRequired?: boolean;
 }
 /**
- * If the `authenticate()` method throws an exception, the error object
- * contains a .code property which will contain one of these strings,
+ * If the `authenticate()` method throws an exception, the `BiometryError`
+ * instance contains a .code property which will contain one of these strings,
  * indicating what the error was.
  *
  * See https://developer.apple.com/documentation/localauthentication/laerror
@@ -132,12 +130,12 @@ export declare enum BiometryErrorType {
     biometryNotEnrolled = "biometryNotEnrolled",
     noDeviceCredential = "noDeviceCredential"
 }
-export interface ResultError extends PluginResultError {
-    code: string;
-}
-export declare class BiometryError implements ResultError {
+/**
+ * `authenticate()` throws instances of this class.
+ */
+export declare class BiometryError {
     message: string;
-    code: string;
+    code: BiometryErrorType;
     constructor(message: string, code: BiometryErrorType);
 }
 export interface CheckBiometryResult {
@@ -169,12 +167,7 @@ export interface CheckBiometryResult {
      * If biometry is not available, the error code will be returned here.
      * Otherwise it's an empty string. The error code will be one of the
      * `BiometryErrorType` enum values, and is consistent across
-     * platforms. This allows you to check for specific errors in a platform-
-     * independent way, for example:
-     *
-     * if (result.code === BiometryErrorType.biometryNotEnrolled) {
-     *   ...
-     * }
+     * platforms.
      */
     code: BiometryErrorType;
 }
@@ -182,6 +175,9 @@ export interface CheckBiometryResult {
  * The signature of the callback passed to `addResumeListener()`.
  */
 export type ResumeListener = (info: CheckBiometryResult) => void;
+/**
+ * This is the public interface of the plugin.
+ */
 export interface BiometricAuthPlugin extends WebPlugin {
     /**
      * Check to see what biometry type (if any) is available.
@@ -218,6 +214,9 @@ export interface BiometricAuthPlugin extends WebPlugin {
     /**
      * Register a function that will be called when the app resumes.
      * The function will be passed the result of `checkBiometry()`.
+     *
+     * 👉 **NOTE:** checkBiometry() must be called at least once
+     * before calling this method.
      */
     addResumeListener: (listener: ResumeListener) => Promise<PluginListenerHandle>;
 }

package/dist/esm/definitions.js

@@ -1,3 +1,4 @@
+// noinspection JSUnusedGlobalSymbols
 export var BiometryType;
 (function (BiometryType) {
     /**
@@ -26,8 +27,8 @@ export var BiometryType;
     BiometryType[BiometryType["irisAuthentication"] = 5] = "irisAuthentication";
 })(BiometryType || (BiometryType = {}));
 /**
- * If the `authenticate()` method throws an exception, the error object
- * contains a .code property which will contain one of these strings,
+ * If the `authenticate()` method throws an exception, the `BiometryError`
+ * instance contains a .code property which will contain one of these strings,
  * indicating what the error was.
  *
  * See https://developer.apple.com/documentation/localauthentication/laerror
@@ -49,6 +50,9 @@ export var BiometryErrorType;
     BiometryErrorType["biometryNotEnrolled"] = "biometryNotEnrolled";
     BiometryErrorType["noDeviceCredential"] = "noDeviceCredential";
 })(BiometryErrorType || (BiometryErrorType = {}));
+/**
+ * `authenticate()` throws instances of this class.
+ */
 export class BiometryError {
     constructor(message, code) {
         this.message = message;

package/dist/esm/native.d.ts

@@ -4,6 +4,6 @@ import { BiometryType } from './definitions';
 export declare class BiometricAuthNative extends BiometricAuthBase {
     constructor(capProxy: BiometricAuthPlugin);
     checkBiometry(): Promise<CheckBiometryResult>;
-    authenticate(options?: AuthenticateOptions): Promise<void>;
+    internalAuthenticate(options?: AuthenticateOptions): Promise<void>;
     setBiometryType(type: BiometryType | string | undefined): Promise<void>;
 }

package/dist/esm/native.js

@@ -4,11 +4,24 @@ import { BiometryErrorType, BiometryType } from './definitions';
 export class BiometricAuthNative extends BiometricAuthBase {
     constructor(capProxy) {
         super();
-        this.checkBiometry = capProxy.checkBiometry;
-        this.authenticate = capProxy.authenticate;
+        /*
+          In order to call native methods and maintain the ability to
+          call pure Javascript methods as well, we have to bind the native methods
+          to the proxy.
+    
+          capProxy is a proxy of an instance of this class, so it is safe
+          to cast it to this class.
+        */
+        // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+        const proxy = capProxy;
+        /* eslint-disable @typescript-eslint/unbound-method */
+        this.checkBiometry = proxy.checkBiometry;
+        this.internalAuthenticate = proxy.internalAuthenticate;
+        /* eslint-enable */
     }
+    // @native
     async checkBiometry() {
-        // Never used, satisfy the compiler
+        // Never used, but we have to satisfy the compiler.
         return Promise.resolve({
             isAvailable: true,
             biometryType: BiometryType.none,
@@ -17,12 +30,16 @@ export class BiometricAuthNative extends BiometricAuthBase {
             code: BiometryErrorType.none,
         });
     }
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars,@typescript-eslint/no-empty-function
-    async authenticate(options) { }
+    // @native
+    // On native platforms, this will present the native authentication UI.
+    async internalAuthenticate(
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    options) { }
+    // Web only, used for simulating biometric authentication.
     // eslint-disable-next-line @typescript-eslint/require-await
     async setBiometryType(
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     type) {
-        throw this.unimplemented('setBiometryType is web only');
+        throw this.unimplemented('setBiometryType() is web only');
     }
 }

package/dist/esm/web.d.ts

@@ -4,6 +4,6 @@ import { BiometryType } from './definitions';
 export declare class BiometricAuthWeb extends BiometricAuthBase {
     private biometryType;
     checkBiometry(): Promise<CheckBiometryResult>;
-    authenticate(options?: AuthenticateOptions): Promise<void>;
+    internalAuthenticate(options?: AuthenticateOptions): Promise<void>;
     setBiometryType(type: BiometryType | string | undefined): Promise<void>;
 }

package/dist/esm/web.js

@@ -7,6 +7,7 @@ export class BiometricAuthWeb extends BiometricAuthBase {
         super(...arguments);
         this.biometryType = BiometryType.none;
     }
+    // On the web, return the fake biometry set by setBiometryType().
     async checkBiometry() {
         return Promise.resolve({
             isAvailable: this.biometryType !== BiometryType.none,
@@ -16,20 +17,23 @@ export class BiometricAuthWeb extends BiometricAuthBase {
             code: BiometryErrorType.none,
         });
     }
-    async authenticate(options) {
-        return this.checkBiometry().then(({ isAvailable, biometryType }) => {
-            var _a;
-            if (isAvailable) {
-                if (
-                // eslint-disable-next-line no-alert
-                confirm((_a = options === null || options === void 0 ? void 0 : options.reason) !== null && _a !== void 0 ? _a : `Authenticate with ${getBiometryName(biometryType)}?`)) {
-                    return;
-                }
-                throw new BiometryError('User cancelled', BiometryErrorType.userCancel);
+    // On the web, fake authentication with a confirm dialog.
+    async internalAuthenticate(options) {
+        const { isAvailable, biometryType } = await this.checkBiometry();
+        if (isAvailable) {
+            if (
+            // eslint-disable-next-line no-alert
+            confirm(
+            // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- we want to use the default value if options?.reason is an empty string
+            (options === null || options === void 0 ? void 0 : options.reason) ||
+                `Authenticate with ${getBiometryName(biometryType)}?`)) {
+                return;
             }
-            throw new BiometryError('Biometry not available', BiometryErrorType.biometryNotAvailable);
-        });
+            throw new BiometryError('User cancelled', BiometryErrorType.userCancel);
+        }
+        throw new BiometryError('Biometry not available', BiometryErrorType.biometryNotAvailable);
     }
+    // Web only, used for simulating biometric authentication.
     async setBiometryType(type) {
         if (typeof type === 'undefined') {
             return Promise.resolve();

package/dist/plugin.cjs.js

@@ -3,6 +3,7 @@
 var core = require('@capacitor/core');
 var app = require('@capacitor/app');
 
+// noinspection JSUnusedGlobalSymbols
 exports.BiometryType = void 0;
 (function (BiometryType) {
     /**
@@ -31,8 +32,8 @@ exports.BiometryType = void 0;
     BiometryType[BiometryType["irisAuthentication"] = 5] = "irisAuthentication";
 })(exports.BiometryType || (exports.BiometryType = {}));
 /**
- * If the `authenticate()` method throws an exception, the error object
- * contains a .code property which will contain one of these strings,
+ * If the `authenticate()` method throws an exception, the `BiometryError`
+ * instance contains a .code property which will contain one of these strings,
  * indicating what the error was.
  *
  * See https://developer.apple.com/documentation/localauthentication/laerror
@@ -54,6 +55,9 @@ exports.BiometryErrorType = void 0;
     BiometryErrorType["biometryNotEnrolled"] = "biometryNotEnrolled";
     BiometryErrorType["noDeviceCredential"] = "noDeviceCredential";
 })(exports.BiometryErrorType || (exports.BiometryErrorType = {}));
+/**
+ * `authenticate()` throws instances of this class.
+ */
 class BiometryError {
     constructor(message, code) {
         this.message = message;
@@ -85,6 +89,23 @@ const proxy = core.registerPlugin('BiometricAuthNative', {
 
 // eslint-disable-next-line import/prefer-default-export
 class BiometricAuthBase extends core.WebPlugin {
+    async authenticate(options) {
+        try {
+            await this.internalAuthenticate(options);
+        }
+        catch (error) {
+            // error will be an instance of CapacitorException on native platforms,
+            // an instance of BiometryError on the web.
+            if (error instanceof core.CapacitorException) {
+                throw new BiometryError(error.message, 
+                // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- error.data values are typed as any
+                error.data.code);
+            }
+            else {
+                throw error;
+            }
+        }
+    }
     addResumeListener(listener) {
         return app.App.addListener('appStateChange', ({ isActive }) => {
             if (isActive) {
@@ -104,6 +125,7 @@ class BiometricAuthWeb extends BiometricAuthBase {
         super(...arguments);
         this.biometryType = exports.BiometryType.none;
     }
+    // On the web, return the fake biometry set by setBiometryType().
     async checkBiometry() {
         return Promise.resolve({
             isAvailable: this.biometryType !== exports.BiometryType.none,
@@ -113,20 +135,23 @@ class BiometricAuthWeb extends BiometricAuthBase {
             code: exports.BiometryErrorType.none,
         });
     }
-    async authenticate(options) {
-        return this.checkBiometry().then(({ isAvailable, biometryType }) => {
-            var _a;
-            if (isAvailable) {
-                if (
-                // eslint-disable-next-line no-alert
-                confirm((_a = options === null || options === void 0 ? void 0 : options.reason) !== null && _a !== void 0 ? _a : `Authenticate with ${getBiometryName(biometryType)}?`)) {
-                    return;
-                }
-                throw new BiometryError('User cancelled', exports.BiometryErrorType.userCancel);
+    // On the web, fake authentication with a confirm dialog.
+    async internalAuthenticate(options) {
+        const { isAvailable, biometryType } = await this.checkBiometry();
+        if (isAvailable) {
+            if (
+            // eslint-disable-next-line no-alert
+            confirm(
+            // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- we want to use the default value if options?.reason is an empty string
+            (options === null || options === void 0 ? void 0 : options.reason) ||
+                `Authenticate with ${getBiometryName(biometryType)}?`)) {
+                return;
             }
-            throw new BiometryError('Biometry not available', exports.BiometryErrorType.biometryNotAvailable);
-        });
+            throw new BiometryError('User cancelled', exports.BiometryErrorType.userCancel);
+        }
+        throw new BiometryError('Biometry not available', exports.BiometryErrorType.biometryNotAvailable);
     }
+    // Web only, used for simulating biometric authentication.
     async setBiometryType(type) {
         if (typeof type === 'undefined') {
             return Promise.resolve();
@@ -154,11 +179,24 @@ var web = /*#__PURE__*/Object.freeze({
 class BiometricAuthNative extends BiometricAuthBase {
     constructor(capProxy) {
         super();
-        this.checkBiometry = capProxy.checkBiometry;
-        this.authenticate = capProxy.authenticate;
+        /*
+          In order to call native methods and maintain the ability to
+          call pure Javascript methods as well, we have to bind the native methods
+          to the proxy.
+    
+          capProxy is a proxy of an instance of this class, so it is safe
+          to cast it to this class.
+        */
+        // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+        const proxy = capProxy;
+        /* eslint-disable @typescript-eslint/unbound-method */
+        this.checkBiometry = proxy.checkBiometry;
+        this.internalAuthenticate = proxy.internalAuthenticate;
+        /* eslint-enable */
     }
+    // @native
     async checkBiometry() {
-        // Never used, satisfy the compiler
+        // Never used, but we have to satisfy the compiler.
         return Promise.resolve({
             isAvailable: true,
             biometryType: exports.BiometryType.none,
@@ -167,13 +205,17 @@ class BiometricAuthNative extends BiometricAuthBase {
             code: exports.BiometryErrorType.none,
         });
     }
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars,@typescript-eslint/no-empty-function
-    async authenticate(options) { }
+    // @native
+    // On native platforms, this will present the native authentication UI.
+    async internalAuthenticate(
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    options) { }
+    // Web only, used for simulating biometric authentication.
     // eslint-disable-next-line @typescript-eslint/require-await
     async setBiometryType(
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     type) {
-        throw this.unimplemented('setBiometryType is web only');
+        throw this.unimplemented('setBiometryType() is web only');
     }
 }
 

package/dist/plugin.js

@@ -1,6 +1,7 @@
 var capacitorBiometricAuth = (function (exports, core, app) {
     'use strict';
 
+    // noinspection JSUnusedGlobalSymbols
     exports.BiometryType = void 0;
     (function (BiometryType) {
         /**
@@ -29,8 +30,8 @@ var capacitorBiometricAuth = (function (exports, core, app) {
         BiometryType[BiometryType["irisAuthentication"] = 5] = "irisAuthentication";
     })(exports.BiometryType || (exports.BiometryType = {}));
     /**
-     * If the `authenticate()` method throws an exception, the error object
-     * contains a .code property which will contain one of these strings,
+     * If the `authenticate()` method throws an exception, the `BiometryError`
+     * instance contains a .code property which will contain one of these strings,
      * indicating what the error was.
      *
      * See https://developer.apple.com/documentation/localauthentication/laerror
@@ -52,6 +53,9 @@ var capacitorBiometricAuth = (function (exports, core, app) {
         BiometryErrorType["biometryNotEnrolled"] = "biometryNotEnrolled";
         BiometryErrorType["noDeviceCredential"] = "noDeviceCredential";
     })(exports.BiometryErrorType || (exports.BiometryErrorType = {}));
+    /**
+     * `authenticate()` throws instances of this class.
+     */
     class BiometryError {
         constructor(message, code) {
             this.message = message;
@@ -83,6 +87,23 @@ var capacitorBiometricAuth = (function (exports, core, app) {
 
     // eslint-disable-next-line import/prefer-default-export
     class BiometricAuthBase extends core.WebPlugin {
+        async authenticate(options) {
+            try {
+                await this.internalAuthenticate(options);
+            }
+            catch (error) {
+                // error will be an instance of CapacitorException on native platforms,
+                // an instance of BiometryError on the web.
+                if (error instanceof core.CapacitorException) {
+                    throw new BiometryError(error.message, 
+                    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- error.data values are typed as any
+                    error.data.code);
+                }
+                else {
+                    throw error;
+                }
+            }
+        }
         addResumeListener(listener) {
             return app.App.addListener('appStateChange', ({ isActive }) => {
                 if (isActive) {
@@ -102,6 +123,7 @@ var capacitorBiometricAuth = (function (exports, core, app) {
             super(...arguments);
             this.biometryType = exports.BiometryType.none;
         }
+        // On the web, return the fake biometry set by setBiometryType().
         async checkBiometry() {
             return Promise.resolve({
                 isAvailable: this.biometryType !== exports.BiometryType.none,
@@ -111,20 +133,23 @@ var capacitorBiometricAuth = (function (exports, core, app) {
                 code: exports.BiometryErrorType.none,
             });
         }
-        async authenticate(options) {
-            return this.checkBiometry().then(({ isAvailable, biometryType }) => {
-                var _a;
-                if (isAvailable) {
-                    if (
-                    // eslint-disable-next-line no-alert
-                    confirm((_a = options === null || options === void 0 ? void 0 : options.reason) !== null && _a !== void 0 ? _a : `Authenticate with ${getBiometryName(biometryType)}?`)) {
-                        return;
-                    }
-                    throw new BiometryError('User cancelled', exports.BiometryErrorType.userCancel);
+        // On the web, fake authentication with a confirm dialog.
+        async internalAuthenticate(options) {
+            const { isAvailable, biometryType } = await this.checkBiometry();
+            if (isAvailable) {
+                if (
+                // eslint-disable-next-line no-alert
+                confirm(
+                // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- we want to use the default value if options?.reason is an empty string
+                (options === null || options === void 0 ? void 0 : options.reason) ||
+                    `Authenticate with ${getBiometryName(biometryType)}?`)) {
+                    return;
                 }
-                throw new BiometryError('Biometry not available', exports.BiometryErrorType.biometryNotAvailable);
-            });
+                throw new BiometryError('User cancelled', exports.BiometryErrorType.userCancel);
+            }
+            throw new BiometryError('Biometry not available', exports.BiometryErrorType.biometryNotAvailable);
         }
+        // Web only, used for simulating biometric authentication.
         async setBiometryType(type) {
             if (typeof type === 'undefined') {
                 return Promise.resolve();
@@ -152,11 +177,24 @@ var capacitorBiometricAuth = (function (exports, core, app) {
     class BiometricAuthNative extends BiometricAuthBase {
         constructor(capProxy) {
             super();
-            this.checkBiometry = capProxy.checkBiometry;
-            this.authenticate = capProxy.authenticate;
+            /*
+              In order to call native methods and maintain the ability to
+              call pure Javascript methods as well, we have to bind the native methods
+              to the proxy.
+        
+              capProxy is a proxy of an instance of this class, so it is safe
+              to cast it to this class.
+            */
+            // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+            const proxy = capProxy;
+            /* eslint-disable @typescript-eslint/unbound-method */
+            this.checkBiometry = proxy.checkBiometry;
+            this.internalAuthenticate = proxy.internalAuthenticate;
+            /* eslint-enable */
         }
+        // @native
         async checkBiometry() {
-            // Never used, satisfy the compiler
+            // Never used, but we have to satisfy the compiler.
             return Promise.resolve({
                 isAvailable: true,
                 biometryType: exports.BiometryType.none,
@@ -165,13 +203,17 @@ var capacitorBiometricAuth = (function (exports, core, app) {
                 code: exports.BiometryErrorType.none,
             });
         }
-        // eslint-disable-next-line @typescript-eslint/no-unused-vars,@typescript-eslint/no-empty-function
-        async authenticate(options) { }
+        // @native
+        // On native platforms, this will present the native authentication UI.
+        async internalAuthenticate(
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        options) { }
+        // Web only, used for simulating biometric authentication.
         // eslint-disable-next-line @typescript-eslint/require-await
         async setBiometryType(
         // eslint-disable-next-line @typescript-eslint/no-unused-vars
         type) {
-            throw this.unimplemented('setBiometryType is web only');
+            throw this.unimplemented('setBiometryType() is web only');
         }
     }
 

package/ios/Plugin/Plugin.m

@@ -3,5 +3,5 @@
 
 CAP_PLUGIN(BiometricAuthNative, "BiometricAuthNative",
   CAP_PLUGIN_METHOD(checkBiometry, CAPPluginReturnPromise);
-  CAP_PLUGIN_METHOD(authenticate, CAPPluginReturnPromise);
+  CAP_PLUGIN_METHOD(internalAuthenticate, CAPPluginReturnPromise);
 )

package/ios/Plugin/Plugin.swift

@@ -22,12 +22,32 @@ public class BiometricAuthNative: CAPPlugin {
     LAError.biometryNotEnrolled.rawValue: "biometryNotEnrolled"
   ]
 
-  var canEvaluatePolicy = true
+  struct CheckDeviceBiometryResult {
+    let isAvailable: Bool
+    let biometryType: LABiometryType.RawValue
+    let biometryTypes: JSArray
+    let reason: String
+    let code: String
+  }
 
   /**
-   * Check the device's availability and type of biometric authentication.
+   * Plugin call checkBiometry()
    */
   @objc func checkBiometry(_ call: CAPPluginCall) {
+    let checkResult = checkDeviceBiometry()
+    call.resolve([
+      "isAvailable": checkResult.isAvailable,
+      "biometryType": checkResult.biometryType,
+      "biometryTypes": checkResult.biometryTypes,
+      "reason": checkResult.reason,
+      "code": checkResult.code
+    ])
+  }
+
+  /**
+   * Check the device's availability and type of biometric authentication.
+   */
+  func checkDeviceBiometry() -> CheckDeviceBiometryResult {
     let context = LAContext()
     var error: NSError?
     var available = context.canEvaluatePolicy(.deviceOwnerAuthenticationWithBiometrics, error: &error)
@@ -42,7 +62,6 @@ public class BiometricAuthNative: CAPPlugin {
 
       if entry == nil {
         available = false
-        canEvaluatePolicy = false
         reason = kMissingFaceIDUsageEntry
         errorCode = biometryErrorCodeMap[LAError.biometryNotAvailable.rawValue] ?? ""
       }
@@ -61,13 +80,13 @@ public class BiometricAuthNative: CAPPlugin {
     var types = JSArray()
     types.append(context.biometryType.rawValue)
 
-    call.resolve([
-      "isAvailable": available,
-      "biometryType": context.biometryType.rawValue,
-      "biometryTypes": types,
-      "reason": reason,
-      "code": errorCode
-    ])
+    return CheckDeviceBiometryResult(
+      isAvailable: available,
+      biometryType: context.biometryType.rawValue,
+      biometryTypes: types,
+      reason: reason,
+      code: errorCode
+    )
   }
 
   /**
@@ -77,11 +96,13 @@ public class BiometricAuthNative: CAPPlugin {
    * @returns {Promise<void>}
    * @rejects {BiometricResultError}
    */
-  @objc func authenticate(_ call: CAPPluginCall) {
+  @objc func internalAuthenticate(_ call: CAPPluginCall) {
     // Make sure the app can evaluate policy, otherwise evaluatePolicy() will crash
-    guard canEvaluatePolicy else {
+    let checkResult = checkDeviceBiometry()
+
+    guard checkResult.isAvailable else {
       call.reject(
-        kMissingFaceIDUsageEntry,
+        checkResult.reason,
         biometryErrorCodeMap[LAError.biometryNotAvailable.rawValue]
       )
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aparajita/capacitor-biometric-auth",
-  "version": "5.2.0",
+  "version": "6.0.0",
   "description": "Provides access to the native biometric auth APIs for Capacitor apps",
   "author": "Aparajita Fishman",
   "license": "MIT",
@@ -9,7 +9,7 @@
   "types": "dist/esm/index.d.ts",
   "unpkg": "dist/plugin.js",
   "engines": {
-    "node": ">=16.15.1"
+    "node": ">=18"
   },
   "files": [
     "android/src/main/",
@@ -56,35 +56,35 @@
     "@aparajita/eslint-config-base": "^1.1.6",
     "@aparajita/prettier-config": "^2.0.0",
     "@aparajita/swiftly": "^1.0.4",
-    "@capacitor/cli": "^5.4.1",
-    "@commitlint/cli": "^17.7.2",
-    "@commitlint/config-conventional": "^17.7.0",
+    "@capacitor/cli": "^5.5.1",
+    "@commitlint/cli": "^18.4.1",
+    "@commitlint/config-conventional": "^18.4.0",
     "@ionic/swiftlint-config": "^1.1.2",
-    "@rollup/plugin-json": "^6.0.0",
-    "@types/node": "^20.8.0",
-    "@typescript-eslint/eslint-plugin": "^6.7.3",
-    "@typescript-eslint/parser": "^6.7.3",
-    "commit-and-tag-version": "^11.2.3",
-    "eslint": "^8.50.0",
+    "@rollup/plugin-json": "^6.0.1",
+    "@types/node": "^20.9.0",
+    "@typescript-eslint/eslint-plugin": "^6.11.0",
+    "@typescript-eslint/parser": "^6.11.0",
+    "commit-and-tag-version": "^12.0.0",
+    "eslint": "^8.53.0",
     "eslint-config-prettier": "^9.0.0",
     "eslint-config-standard": "^17.1.0",
     "eslint-import-resolver-typescript": "^3.6.1",
-    "eslint-plugin-import": "^2.28.1",
-    "eslint-plugin-n": "^16.1.0",
+    "eslint-plugin-import": "^2.29.0",
+    "eslint-plugin-n": "^16.3.1",
     "eslint-plugin-promise": "^6.1.1",
     "nodemon": "^3.0.1",
-    "prettier": "^3.0.3",
-    "prettier-plugin-java": "^2.3.1",
+    "prettier": "^3.1.0",
+    "prettier-plugin-java": "^2.4.0",
     "rimraf": "^5.0.5",
-    "rollup": "^3.29.4",
+    "rollup": "^4.4.0",
     "swiftlint": "^1.0.2",
     "typescript": "~5.2.2"
   },
   "dependencies": {
-    "@capacitor/android": "^5.4.1",
+    "@capacitor/android": "^5.5.1",
     "@capacitor/app": "^5.0.6",
-    "@capacitor/core": "^5.4.1",
-    "@capacitor/ios": "^5.4.1"
+    "@capacitor/core": "^5.5.1",
+    "@capacitor/ios": "^5.5.1"
   },
   "scripts": {
     "clean": "rimraf dist",