@aparajita/capacitor-biometric-auth 1.0.7 → 2.0.2

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

@@ -0,0 +1,262 @@
+package com.aparajita.capacitor.biometricauth;
+
+import android.annotation.SuppressLint;
+import android.app.Activity;
+import android.content.Intent;
+import android.content.pm.PackageManager;
+import androidx.activity.result.ActivityResult;
+import androidx.biometric.BiometricManager;
+import androidx.biometric.BiometricPrompt;
+import com.getcapacitor.JSObject;
+import com.getcapacitor.Plugin;
+import com.getcapacitor.PluginCall;
+import com.getcapacitor.PluginMethod;
+import com.getcapacitor.annotation.ActivityCallback;
+import com.getcapacitor.annotation.CapacitorPlugin;
+import java.util.HashMap;
+
+@SuppressLint("RestrictedApi")
+@CapacitorPlugin(name = "BiometricAuth")
+public class BiometricAuth extends Plugin {
+
+  public static final String RESULT_TYPE = "type";
+  public static final String RESULT_ERROR_CODE = "errorCode";
+  public static final String RESULT_ERROR_MESSAGE = "errorMessage";
+  public static final String TITLE = "androidTitle";
+  public static final String SUBTITLE = "androidSubtitle";
+  public static final String REASON = "reason";
+  public static final String CANCEL_TITLE = "cancelTitle";
+  public static final String DEVICE_CREDENTIAL = "allowDeviceCredential";
+  public static final String MAX_ATTEMPTS = "androidMaxAttempts";
+  public static final int DEFAULT_MAX_ATTEMPTS = 3;
+  // Error code when biometry is not recognized
+  public static final String BIOMETRIC_FAILURE = "authenticationFailed";
+  // Maps biometry error numbers to string error codes
+  private static final HashMap<Integer, String> biometryErrorCodeMap;
+  private static final HashMap<BiometryType, String> biometryNameMap;
+  private static final String INVALID_CONTEXT_ERROR = "invalidContext";
+  public static String RESULT_EXTRA_PREFIX;
+
+  static {
+    biometryErrorCodeMap = new HashMap<>();
+    biometryErrorCodeMap.put(BiometricPrompt.ERROR_CANCELED, "systemCancel");
+    biometryErrorCodeMap.put(
+      BiometricPrompt.ERROR_HW_NOT_PRESENT,
+      "biometryNotAvailable"
+    );
+    biometryErrorCodeMap.put(
+      BiometricPrompt.ERROR_HW_UNAVAILABLE,
+      "biometryNotAvailable"
+    );
+    biometryErrorCodeMap.put(BiometricPrompt.ERROR_LOCKOUT, "biometryLockout");
+    biometryErrorCodeMap.put(
+      BiometricPrompt.ERROR_LOCKOUT_PERMANENT,
+      "biometryLockout"
+    );
+    biometryErrorCodeMap.put(
+      BiometricPrompt.ERROR_NEGATIVE_BUTTON,
+      "userCancel"
+    );
+    biometryErrorCodeMap.put(
+      BiometricPrompt.ERROR_NO_BIOMETRICS,
+      "biometryNotEnrolled"
+    );
+    biometryErrorCodeMap.put(
+      BiometricPrompt.ERROR_NO_DEVICE_CREDENTIAL,
+      "noDeviceCredential"
+    );
+    biometryErrorCodeMap.put(BiometricPrompt.ERROR_NO_SPACE, "systemCancel");
+    biometryErrorCodeMap.put(BiometricPrompt.ERROR_TIMEOUT, "systemCancel");
+    biometryErrorCodeMap.put(
+      BiometricPrompt.ERROR_UNABLE_TO_PROCESS,
+      "systemCancel"
+    );
+    biometryErrorCodeMap.put(BiometricPrompt.ERROR_USER_CANCELED, "userCancel");
+    biometryErrorCodeMap.put(BiometricPrompt.ERROR_VENDOR, "systemCancel");
+  }
+
+  static {
+    biometryNameMap = new HashMap<>();
+    biometryNameMap.put(BiometryType.NONE, "No Authentication");
+    biometryNameMap.put(BiometryType.FINGERPRINT, "Fingerprint Authentication");
+    biometryNameMap.put(BiometryType.FACE, "Face Authentication");
+    biometryNameMap.put(BiometryType.IRIS, "Iris Authentication");
+  }
+
+  private BiometryType biometryType;
+
+  /**
+   * Check the device's availability and type of biometric authentication.
+   */
+  @PluginMethod
+  public void checkBiometry(PluginCall call) {
+    BiometricManager manager = BiometricManager.from(getContext());
+
+    int result = manager.canAuthenticate();
+
+    JSObject ret = new JSObject();
+    ret.put("isAvailable", result == BiometricManager.BIOMETRIC_SUCCESS);
+    biometryType = getDeviceBiometryType();
+    ret.put("biometryType", biometryType.getType());
+
+    String reason = "";
+
+    switch (result) {
+      case BiometricManager.BIOMETRIC_SUCCESS:
+        break;
+      case BiometricManager.BIOMETRIC_ERROR_HW_UNAVAILABLE:
+        reason = "Biometry hardware is present, but currently unavailable.";
+        break;
+      case BiometricManager.BIOMETRIC_ERROR_NONE_ENROLLED:
+        reason = "The user does not have any biometrics enrolled.";
+        break;
+      case BiometricManager.BIOMETRIC_ERROR_NO_HARDWARE:
+        reason = "There is no biometric hardware on this device.";
+        break;
+    }
+
+    ret.put("reason", reason);
+    call.resolve(ret);
+  }
+
+  private BiometryType getDeviceBiometryType() {
+    PackageManager manager = getContext().getPackageManager();
+
+    if (manager.hasSystemFeature(PackageManager.FEATURE_FINGERPRINT)) {
+      return BiometryType.FINGERPRINT;
+    }
+
+    if (manager.hasSystemFeature(PackageManager.FEATURE_FACE)) {
+      return BiometryType.FACE;
+    }
+
+    if (manager.hasSystemFeature(PackageManager.FEATURE_IRIS)) {
+      return BiometryType.IRIS;
+    }
+
+    return BiometryType.NONE;
+  }
+
+  /**
+   * Prompt the user for biometric authentication.
+   */
+  @PluginMethod
+  public void authenticate(final PluginCall call) {
+    // The result of an intent is supposed to have the package name as a prefix
+    RESULT_EXTRA_PREFIX = getContext().getPackageName() + ".";
+
+    Intent intent = new Intent(getContext(), AuthActivity.class);
+
+    // Pass the options to the activity
+    intent.putExtra(
+      TITLE,
+      call.getString(TITLE, biometryNameMap.get(biometryType))
+    );
+    intent.putExtra(SUBTITLE, call.getString(SUBTITLE));
+    intent.putExtra(REASON, call.getString(REASON));
+    intent.putExtra(CANCEL_TITLE, call.getString(CANCEL_TITLE));
+    intent.putExtra(
+      DEVICE_CREDENTIAL,
+      call.getBoolean(DEVICE_CREDENTIAL, false)
+    );
+
+    // Just in case the developer does something dumb like using a number < 1...
+    Integer maxAttemptsConfig = call.getInt(MAX_ATTEMPTS, DEFAULT_MAX_ATTEMPTS);
+    int maxAttempts = Math.max(
+      maxAttemptsConfig == null ? 0 : maxAttemptsConfig,
+      1
+    );
+    intent.putExtra(MAX_ATTEMPTS, maxAttempts);
+
+    startActivityForResult(call, intent, "authenticateResult");
+  }
+
+  @ActivityCallback
+  protected void authenticateResult(PluginCall call, ActivityResult result) {
+    int resultCode = result.getResultCode();
+
+    // If the system canceled the activity, we might get RESULT_CANCELED in resultCode.
+    // In that case return that immediately, because there won't be any data.
+    if (resultCode == Activity.RESULT_CANCELED) {
+      call.reject(
+        "The system canceled authentication",
+        biometryErrorCodeMap.get(BiometricPrompt.ERROR_CANCELED)
+      );
+      return;
+    }
+
+    // Convert the string result type to an enum
+    Intent data = result.getData();
+    String resultTypeName = null;
+
+    if (data != null) {
+      resultTypeName =
+        data.getStringExtra(RESULT_EXTRA_PREFIX + BiometricAuth.RESULT_TYPE);
+    }
+
+    if (resultTypeName == null) {
+      call.reject(
+        "Missing data in the result of the activity",
+        INVALID_CONTEXT_ERROR
+      );
+      return;
+    }
+
+    BiometryResultType resultType;
+
+    try {
+      resultType = BiometryResultType.valueOf(resultTypeName);
+    } catch (IllegalArgumentException e) {
+      call.reject(
+        "Invalid data in the result of the activity",
+        INVALID_CONTEXT_ERROR
+      );
+      return;
+    }
+
+    int errorCode = data.getIntExtra(
+      RESULT_EXTRA_PREFIX + BiometricAuth.RESULT_ERROR_CODE,
+      0
+    );
+    String errorMessage = data.getStringExtra(
+      RESULT_EXTRA_PREFIX + BiometricAuth.RESULT_ERROR_MESSAGE
+    );
+
+    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.
+        if (errorCode == BiometricPrompt.ERROR_NEGATIVE_BUTTON) {
+          errorMessage = "Cancel button was pressed";
+        }
+
+        call.reject(errorMessage, biometryErrorCodeMap.get(errorCode));
+        break;
+    }
+  }
+
+  enum BiometryType {
+    NONE(0),
+    FINGERPRINT(3),
+    FACE(4),
+    IRIS(5);
+
+    private final int type;
+
+    BiometryType(int type) {
+      this.type = type;
+    }
+
+    public int getType() {
+      return this.type;
+    }
+  }
+}

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

@@ -1,7 +1,7 @@
 package com.aparajita.capacitor.biometricauth;
 
 public enum BiometryResultType {
-    SUCCESS,
-    FAILURE,
-    ERROR
+  SUCCESS,
+  FAILURE,
+  ERROR
 }

package/dist/esm/definitions.d.ts

@@ -1,9 +1,5 @@
-declare module '@capacitor/core' {
-    interface PluginRegistry {
-        WSBiometricAuth: WSBiometricAuthPlugin;
-    }
-}
-import { PluginResultError } from '@capacitor/core';
+import type { DecoratedNativePlugin } from '@aparajita/capacitor-native-decorator';
+import type { PluginListenerHandle, PluginResultError } from '@capacitor/core';
 export declare enum BiometryType {
     /**
      * No biometry is available
@@ -32,8 +28,8 @@ export declare enum BiometryType {
 }
 export interface AuthenticateOptions {
     /**
-     * The reason for requesting authentication. Displays in the authentication dialog presented to the user.
-     * If not supplied, a default message is displayed.
+     * The reason for requesting authentication. Displays in the authentication dialog
+     * presented to the user. If not supplied, a default message is displayed.
      */
     reason?: string;
     /**
@@ -53,27 +49,27 @@ export interface AuthenticateOptions {
      * Default: "Cancel"
      */
     cancelTitle?: string;
-    /***
+    /**
      * If true, allows for authentication using device unlock credentials. Default is false.
      *
      * iOS:
      * If biometry is available, enrolled, and not disabled, the system uses that first.
-     * After the first Touch ID failure or second Face ID failure, if iosFallbackTitle
+     * After the first Touch ID failure or second Face ID failure, if `iosFallbackTitle`
      * is not an empty string, a fallback button appears in the authentication dialog.
      * If the user taps the fallback button, the system prompts the user for the device
-     * passcode or the user’s password. If iosFallbackTitle is an empty string, no
+     * passcode or the user’s password. If `iosFallbackTitle` is an empty string, no
      * fallback button will appear.
      *
      * If biometry is not available, enrolled and enabled, and a passcode is set,
      * the system immediately prompts the user for the device passcode or user’s password.
-     * Authentication fails with the error code passcodeNotSet if the device passcode isn’t enabled.
+     * Authentication fails with the error code `passcodeNotSet` if the device passcode isn’t enabled.
      *
-     * If a passcode is not set on the device, a passcodeNotSet error is returned.
+     * If a passcode is not set on the device, a `passcodeNotSet` error is returned.
      *
      * The system disables passcode authentication after 6 unsuccessful attempts, with progressively
      * increasing delays between attempts.
      *
-     * The title of the fallback button may be customized by setting iosFallbackTitle to
+     * The title of the fallback button may be customized by setting `iosFallbackTitle` to
      * a non-empty string.
      *
      * Android:
@@ -88,12 +84,12 @@ export interface AuthenticateOptions {
      * — for example, because the system doesn’t recognize the presented finger,
      * or after several failed attempts to recognize the user’s face.
      *
-     * If allowDeviceCredential is false, tapping this button dismisses the
+     * If `allowDeviceCredential` is false, tapping this button dismisses the
      * authentication dialog and returns the error code userFallback. If undefined,
      * the localized systetm default title is used. Passing an empty string
      * hides the fallback button completely.
      *
-     * If allowDeviceCredential is true and this is undefined,
+     * If `allowDeviceCredential` is true and this is undefined,
      * the localized system default title is used.
      */
     iosFallbackTitle?: string;
@@ -107,12 +103,12 @@ export interface AuthenticateOptions {
     androidSubtitle?: string;
     /**
      * The maximum number of failed biometric verification attempts before
-     * returning BiometryError.authenticationFailed. The default is 3.
+     * returning `BiometryError.authenticationFailed`. The default is 3.
      */
     androidMaxAttempts?: number;
 }
 /**
- * If the authenticate() method throws an exception, the error object
+ * If the `authenticate()` method throws an exception, the error object
  * contains a .code property which will contain one of these strings,
  * indicating what the error was.
  *
@@ -158,42 +154,39 @@ export interface CheckBiometryResult {
     reason: string;
 }
 /**
- * The signature of the callback passed to addResumeListener().
+ * The signature of the callback passed to `addResumeListener()`.
  */
 export declare type ResumeListener = (info: CheckBiometryResult) => void;
-export interface WSBiometricAuthPlugin {
+export interface BiometricAuthPlugin extends DecoratedNativePlugin {
     /**
      * Check to see what biometry type (if any) is available.
-     * For testing on the web, a BiometryType name (case-sensitive)
-     * may be specified as an environment variable. For example:
-     *
-     * WS_BIOMETRY_TYPE=touchId
      */
-    checkBiometry(): Promise<CheckBiometryResult>;
+    checkBiometry: () => Promise<CheckBiometryResult>;
     /**
      * web only
      *
      * On the web, this method allows you to dynamically simulate
-     * different types of biometry. You may either pass a BiometryType enum
-     * or the string name of a BiometryType. If a string is passed and
-     * it isn't a valid
+     * different types of biometry. You may either pass a `BiometryType` enum
+     * or the string name of a `BiometryType`. If a string is passed and
+     * it isn't a valid value, nothing happens.
      */
-    setBiometryType(type: BiometryType | string | undefined): void;
+    setBiometryType: (type: BiometryType | string | undefined) => void;
     /**
      * Prompt the user for authentication. If authorization fails for any reason,
-     * the promise is rejected with a BiometryError.
+     * the promise is rejected with a `BiometryError`.
      *
      * @param {AuthenticateOptions} options
      * @returns {Promise<void>}
      * @rejects {BiometryError}
      */
-    authenticate(options?: AuthenticateOptions): Promise<void>;
+    authenticate: (options?: AuthenticateOptions) => Promise<void>;
     /**
      * Register a function that will be called when the app resumes.
-     * The function will be passed the result of checkBiometry().
+     * The function will be passed the result of `checkBiometry()`.
      *
      * @param {ResumeListener} listener
      * @returns {boolean} true if the listener is successfully added
      */
-    addResumeListener(listener: ResumeListener): void;
+    addResumeListener: (listener: ResumeListener) => Promise<PluginListenerHandle>;
 }
+export declare const kPluginName = "BiometricAuth";

package/dist/esm/definitions.js

@@ -26,7 +26,7 @@ export var BiometryType;
     BiometryType[BiometryType["irisAuthentication"] = 5] = "irisAuthentication";
 })(BiometryType || (BiometryType = {}));
 /**
- * If the authenticate() method throws an exception, the error object
+ * If the `authenticate()` method throws an exception, the error object
  * contains a .code property which will contain one of these strings,
  * indicating what the error was.
  *
@@ -54,4 +54,4 @@ export class BiometryError {
         this.code = BiometryErrorType[code];
     }
 }
-//# sourceMappingURL=definitions.js.map
+export const kPluginName = 'BiometricAuth';

package/dist/esm/index.d.ts

@@ -1,2 +1,5 @@
+import type { BiometricAuthPlugin } from './definitions';
+declare const biometricAuth: BiometricAuthPlugin;
 export * from './definitions';
-export * from './web';
+export { biometricAuth as BiometricAuth };
+export { getBiometryName } from './web';

package/dist/esm/index.js

@@ -1,3 +1,18 @@
+import { registerPlugin } from '@capacitor/core';
+import { kPluginName } from './definitions';
+import { name } from './package.json';
+import { BiometricAuth } from './web';
+console.log(`loaded ${name}`);
+// Because we are using @aparajita/capacitor-native-decorator,
+// we have one version of the TS code to rule them all, and there
+// is no need to lazy load. 😁
+const plugin = new BiometricAuth();
+// eslint-disable-next-line @typescript-eslint/naming-convention
+const biometricAuth = registerPlugin(kPluginName, {
+    web: plugin,
+    ios: plugin,
+    android: plugin
+});
 export * from './definitions';
-export * from './web';
-//# sourceMappingURL=index.js.map
+export { biometricAuth as BiometricAuth };
+export { getBiometryName } from './web';

package/dist/esm/package.json

@@ -0,0 +1,113 @@
+{
+    "name": "@aparajita/capacitor-biometric-auth",
+    "version": "2.0.1",
+    "description": "Provides access to the native biometric auth APIs for Capacitor apps",
+    "author": "Aparajita Fishman",
+    "license": "MIT",
+    "main": "dist/plugin.cjs.js",
+    "module": "dist/esm/index.js",
+    "types": "dist/esm/index.d.ts",
+    "unpkg": "dist/plugin.js",
+    "engines": {
+        "node": ">=16.15.1"
+    },
+    "files": [
+        "android/src/main/",
+        "android/build.gradle",
+        "dist/",
+        "ios/Plugin/",
+        "*.podspec",
+        "LICENSE"
+    ],
+    "scripts": {
+        "clean": "rimraf ./dist",
+        "build": "pnpm check && pnpm build.only",
+        "build.dev": "pnpm check && pnpm build.only.dev",
+        "build.only": "pnpm clean && tsc $SOURCE_MAP && pnpm rollup && make-ios-plugin && pnpm docgen",
+        "build.only.dev": "SOURCE_MAP=--sourceMap pnpm build.only",
+        "rollup": "rollup -c rollup.config.mjs",
+        "watch": "nodemon -w ./src -w tsconfig.json -w rollup.config.mjs --exec 'pnpm build --silent' -e ts",
+        "lint": "eslint . && pnpm typecheck",
+        "lint.fix": "eslint --fix . && pnpm typecheck",
+        "typecheck": "tsc --noEmit",
+        "lint.swift": "pnpm swiftlint",
+        "prettier": "prettier --check \"**/*.{css,html,ts,js,json,java}\"",
+        "prettier.fix": "pnpm prettier --write",
+        "swiftlint": "swiftly ios",
+        "swiftlint.fix": "swiftly --fix ios",
+        "check": "pnpm lint && pnpm prettier && pnpm swiftlint",
+        "check.fix": "pnpm lint.fix && pnpm prettier.fix && pnpm swiftlint.fix",
+        "docgen": "docgen --api BiometricAuthPlugin --output-readme README.md && docgen-format",
+        "verify": "pnpm verify:ios && pnpm verify:android && pnpm verify:web",
+        "verify:ios": "cd ios && pod install && xcodebuild -workspace Plugin.xcworkspace -scheme Plugin && cd ..",
+        "verify:android": "cd android && ./gradlew clean build test && cd ..",
+        "verify:web": "pnpm build",
+        "push": "git push --follow-tags origin main",
+        "release.check": "commit-and-tag-version $VERSION --dry-run",
+        "release": "commit-and-tag-version $VERSION && pnpm push && pnpm publish"
+    },
+    "keywords": [
+        "capacitor",
+        "plugin",
+        "native",
+        "biometry",
+        "biometric",
+        "auth",
+        "faceid",
+        "touchid"
+    ],
+    "capacitor": {
+        "ios": {
+            "src": "ios"
+        },
+        "android": {
+            "src": "android"
+        }
+    },
+    "swiftlint": "@ionic/swiftlint-config",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/aparajita/capacitor-biometric-auth"
+    },
+    "bugs": {
+        "url": "https://github.com/aparajita/capacitor-biometric-auth/issues"
+    },
+    "devDependencies": {
+        "@aparajita/capacitor-docgen": "github:aparajita/capacitor-docgen",
+        "@aparajita/capacitor-docgen-format": "github:aparajita/capacitor-docgen-format",
+        "@aparajita/eslint-config-base": "^1.1.2",
+        "@aparajita/prettier-config": "^1.0.0",
+        "@aparajita/swiftly": "^1.0.0",
+        "@capacitor/core": "^3.6.0",
+        "@ionic/swiftlint-config": "^1.1.2",
+        "@rollup/plugin-json": "^4.1.0",
+        "@types/node": "^18.0.0",
+        "@typescript-eslint/eslint-plugin": "^5.30.3",
+        "@typescript-eslint/parser": "^5.30.3",
+        "chalk": "^5.0.1",
+        "commit-and-tag-version": "^10.0.1",
+        "eslint": "^8.19.0",
+        "eslint-config-prettier": "^8.5.0",
+        "eslint-config-standard": "^17.0.0",
+        "eslint-import-resolver-typescript": "^3.1.4",
+        "eslint-plugin-import": "^2.26.0",
+        "eslint-plugin-n": "^15.2.3",
+        "eslint-plugin-prettier": "^4.2.1",
+        "eslint-plugin-promise": "^6.0.0",
+        "nodemon": "^2.0.18",
+        "prettier": "^2.7.1",
+        "prettier-plugin-java": "^1.6.2",
+        "rimraf": "^3.0.2",
+        "rollup": "^2.75.7",
+        "typescript": "~4.7.4"
+    },
+    "dependencies": {
+        "@aparajita/capacitor-native-decorator": "link:../capacitor-native-decorator",
+        "@capacitor/android": "^3.6.0",
+        "@capacitor/app": "^1.1.1",
+        "@capacitor/ios": "^3.6.0"
+    },
+    "peerDependencies": {
+        "@capacitor/core": "^3.6.0"
+    }
+}

package/dist/esm/web.d.ts

@@ -1,12 +1,14 @@
 import { WebPlugin } from '@capacitor/core';
-import { CheckBiometryResult, AuthenticateOptions, BiometryType, WSBiometricAuthPlugin, ResumeListener } from './definitions';
-export declare class WSBiometricAuthWeb extends WebPlugin implements WSBiometricAuthPlugin {
+import type { PluginListenerHandle } from '@capacitor/core';
+import type { AuthenticateOptions, BiometricAuthPlugin, CheckBiometryResult, ResumeListener } from './definitions';
+import { BiometryType } from './definitions';
+export declare class BiometricAuth extends WebPlugin implements BiometricAuthPlugin {
     private biometryType;
-    constructor();
+    getRegisteredPluginName(): string;
     setBiometryType(type: BiometryType | string | undefined): void;
     checkBiometry(): Promise<CheckBiometryResult>;
     authenticate(options?: AuthenticateOptions): Promise<void>;
-    addResumeListener(listener: ResumeListener): void;
+    addResumeListener(listener: ResumeListener): Promise<PluginListenerHandle> & PluginListenerHandle;
 }
 /**
  * Return a human-readable name for a BiometryType.
@@ -15,5 +17,3 @@ export declare class WSBiometricAuthWeb extends WebPlugin implements WSBiometric
  * @returns {string}
  */
 export declare function getBiometryName(type: BiometryType): string;
-declare const WSBiometricAuth: WSBiometricAuthWeb;
-export { WSBiometricAuth };