@tokamakdev/plugin-local-authentication 0.1.0-beta.45

package/README.md

@@ -0,0 +1,42 @@
+# @tokamakdev/plugin-local-authentication
+
+Device owner authentication for Tokamak applications.
+
+Add it to your project's dependencies:
+
+```sh
+npm install @tokamakdev/plugin-local-authentication
+```
+
+```ts
+import { localAuthentication } from "@tokamakdev/plugin-local-authentication";
+
+// "available" | "notEnrolled" | "unavailable"
+const status = await localAuthentication.status("biometricsOrPasscode");
+
+await localAuthentication.authenticate("biometricsOrPasscode", {
+  prompt: "Confirm it's you to link a new device",
+});
+```
+
+Both methods accept `biometricsOrPasscode` (Face ID, Touch ID or fingerprint,
+falling back to the device passcode, PIN, pattern or password) or `biometrics`.
+
+`status` reports whether the device can perform the authentication now.
+`notEnrolled` means no biometric or passcode is set up.
+
+`authenticate` resolves when the device owner authenticates. It rejects with
+`NotAllowedError` when the user cancels or fails, `InvalidStateError` when the
+authentication is not set up, and `NotSupportedError` when the device cannot
+perform it.
+
+`authenticate` checks the device owner when the app asks; it does not protect
+any data. To bind a stored value to authentication, use
+`@tokamakdev/plugin-secure-storage`.
+
+## Platforms
+
+- **iOS and macOS:** LocalAuthentication. On macOS, `biometricsOrPasscode`
+  accepts Touch ID or the account password.
+- **Android:** the platform `BiometricPrompt`.
+- **Web and Windows:** no implementation; calls throw `NotSupportedError`.

package/android/LocalAuthenticationPlugin.kt

@@ -0,0 +1,134 @@
+package com.tokamak.plugins.localauthentication
+
+import android.app.Activity
+import android.hardware.biometrics.BiometricManager
+import android.hardware.biometrics.BiometricManager.Authenticators
+import android.hardware.biometrics.BiometricPrompt
+import android.os.CancellationSignal
+import com.tokamak.runtime.TokamakPlugin
+import com.tokamak.runtime.TokamakPluginError
+import com.tokamak.runtime.TokamakPluginReply
+import org.json.JSONObject
+
+internal class TokamakLocalAuthenticationPlugin(
+    private val activity: Activity,
+) : TokamakPlugin {
+    override val id = "local-authentication"
+
+    private val biometrics = activity.getSystemService(BiometricManager::class.java)
+
+    override fun call(method: String, arguments: Any?, reply: TokamakPluginReply) {
+        when (method) {
+            "status" -> respond(reply) { reply(Result.success(status(request(arguments)))) }
+            "authenticate" -> respond(reply) { authenticate(request(arguments), reply) }
+            else -> super.call(method, arguments, reply)
+        }
+    }
+
+    private fun respond(reply: TokamakPluginReply, operation: () -> Unit) {
+        runCatching(operation).onFailure { reply(Result.failure(pluginError(it))) }
+    }
+
+    private fun status(request: JSONObject): String =
+        when (biometrics.canAuthenticate(authenticators(request))) {
+            BiometricManager.BIOMETRIC_SUCCESS -> "available"
+            BiometricManager.BIOMETRIC_ERROR_NONE_ENROLLED -> "notEnrolled"
+            else -> "unavailable"
+        }
+
+    private fun authenticate(request: JSONObject, reply: TokamakPluginReply) {
+        val authenticators = authenticators(request)
+        val prompt = request.requireString("prompt")
+        if (prompt.isEmpty()) throw typeError("prompt must be a non-empty string")
+        requireAvailable(authenticators)
+        val callback = PromptCallback(reply) { reply(Result.success(null)) }
+        val dialog =
+            BiometricPrompt.Builder(activity)
+                .setTitle(prompt)
+                .setAllowedAuthenticators(authenticators)
+        if ((authenticators and Authenticators.DEVICE_CREDENTIAL) == 0) {
+            dialog.setNegativeButton(
+                activity.getString(android.R.string.cancel),
+                activity.mainExecutor,
+            ) { _, _ ->
+                reply(Result.failure(TokamakPluginError("NotAllowedError", "Authentication was cancelled")))
+            }
+        }
+        dialog.build().authenticate(CancellationSignal(), activity.mainExecutor, callback)
+    }
+
+    private fun requireAvailable(authenticators: Int) {
+        when (biometrics.canAuthenticate(authenticators)) {
+            BiometricManager.BIOMETRIC_SUCCESS -> Unit
+            BiometricManager.BIOMETRIC_ERROR_NO_HARDWARE ->
+                throw TokamakPluginError.notSupported("This device cannot perform the requested authentication")
+            else -> throw notSetUp()
+        }
+    }
+
+    private fun authenticators(request: JSONObject): Int {
+        val wireName = request.optionalString("authentication")
+        return Authentication.entries.firstOrNull { it.wireName == wireName }?.authenticators
+            ?: throw typeError("authentication must be \"biometricsOrPasscode\" or \"biometrics\"")
+    }
+
+    private fun request(arguments: Any?): JSONObject =
+        arguments as? JSONObject ?: throw typeError("$id arguments must be an object")
+
+    private fun JSONObject.requireString(name: String): String =
+        optionalString(name) ?: throw typeError("$name must be a string")
+
+    private fun JSONObject.optionalString(name: String): String? =
+        when (val value = opt(name)) {
+            null, JSONObject.NULL -> null
+            is String -> value
+            else -> throw typeError("$name must be a string")
+        }
+
+    private enum class Authentication(val wireName: String, val authenticators: Int) {
+        BIOMETRICS_OR_PASSCODE(
+            "biometricsOrPasscode",
+            Authenticators.BIOMETRIC_STRONG or Authenticators.DEVICE_CREDENTIAL,
+        ),
+        BIOMETRICS("biometrics", Authenticators.BIOMETRIC_STRONG),
+    }
+
+    private companion object {
+        fun typeError(message: String) = TokamakPluginError("TypeError", message)
+
+        fun notSetUp() =
+            TokamakPluginError("InvalidStateError", "The requested authentication is not set up on this device")
+
+        fun pluginError(error: Throwable): TokamakPluginError =
+            error as? TokamakPluginError
+                ?: TokamakPluginError("OperationError", error.message ?: error.javaClass.name)
+    }
+}
+
+private class PromptCallback(
+    private val reply: TokamakPluginReply,
+    private val succeeded: () -> Unit,
+) : BiometricPrompt.AuthenticationCallback() {
+    override fun onAuthenticationSucceeded(result: BiometricPrompt.AuthenticationResult) = succeeded()
+
+    override fun onAuthenticationError(code: Int, message: CharSequence) =
+        reply(Result.failure(authenticationError(code, message)))
+}
+
+private fun authenticationError(code: Int, message: CharSequence) =
+    TokamakPluginError(
+        when (code) {
+            BiometricPrompt.BIOMETRIC_ERROR_CANCELED,
+            BiometricPrompt.BIOMETRIC_ERROR_USER_CANCELED,
+            BiometricPrompt.BIOMETRIC_ERROR_TIMEOUT,
+            BiometricPrompt.BIOMETRIC_ERROR_LOCKOUT,
+            BiometricPrompt.BIOMETRIC_ERROR_LOCKOUT_PERMANENT,
+            -> "NotAllowedError"
+            BiometricPrompt.BIOMETRIC_ERROR_NO_BIOMETRICS,
+            BiometricPrompt.BIOMETRIC_ERROR_NO_DEVICE_CREDENTIAL,
+            -> "InvalidStateError"
+            BiometricPrompt.BIOMETRIC_ERROR_HW_NOT_PRESENT -> "NotSupportedError"
+            else -> "OperationError"
+        },
+        message.toString(),
+    )

package/apple/LocalAuthenticationPlugin.swift

@@ -0,0 +1,90 @@
+import Foundation
+import LocalAuthentication
+
+final class TokamakLocalAuthenticationPlugin: TokamakPlugin {
+  let id = "local-authentication"
+
+  func call(
+    method: String,
+    arguments: Any,
+    reply: @escaping TokamakPluginReply
+  ) {
+    let arguments = arguments as? [String: Any] ?? [:]
+    do throws(TokamakPluginError) {
+      switch method {
+      case "status":
+        reply(.success(status(try policy(arguments))))
+      case "authenticate":
+        try authenticate(policy(arguments), prompt: prompt(arguments), reply: reply)
+      default:
+        throw .notSupported("\(id).\(method) is not supported")
+      }
+    } catch {
+      reply(.failure(error))
+    }
+  }
+
+  private func status(_ policy: LAPolicy) -> String {
+    var error: NSError?
+    if LAContext().canEvaluatePolicy(policy, error: &error) {
+      return "available"
+    }
+    switch (error as? LAError)?.code {
+    case .biometryNotEnrolled, .passcodeNotSet:
+      return "notEnrolled"
+    default:
+      return "unavailable"
+    }
+  }
+
+  private func authenticate(
+    _ policy: LAPolicy,
+    prompt: String,
+    reply: @escaping TokamakPluginReply
+  ) {
+    let context = LAContext()
+    if policy == .deviceOwnerAuthenticationWithBiometrics {
+      // Hides the passcode fallback button, which this policy cannot use.
+      context.localizedFallbackTitle = ""
+    }
+    context.evaluatePolicy(policy, localizedReason: prompt) { success, error in
+      // A deallocated context cancels its evaluation.
+      withExtendedLifetime(context) {
+        reply(success ? .success(nil) : .failure(Self.failure(error)))
+      }
+    }
+  }
+
+  private static func failure(_ error: Error?) -> TokamakPluginError {
+    let message = error?.localizedDescription ?? "Authentication failed"
+    switch (error as? LAError)?.code {
+    case .biometryNotEnrolled, .passcodeNotSet:
+      return TokamakPluginError(name: "InvalidStateError", message: message)
+    case .biometryNotAvailable:
+      return .notSupported(message)
+    default:
+      return TokamakPluginError(name: "NotAllowedError", message: message)
+    }
+  }
+
+  private func policy(_ arguments: [String: Any]) throws(TokamakPluginError) -> LAPolicy {
+    switch arguments["authentication"] as? String {
+    case "biometricsOrPasscode":
+      return .deviceOwnerAuthentication
+    case "biometrics":
+      return .deviceOwnerAuthenticationWithBiometrics
+    default:
+      throw TokamakPluginError(
+        name: "TypeError",
+        message: "authentication must be biometricsOrPasscode or biometrics"
+      )
+    }
+  }
+
+  private func prompt(_ arguments: [String: Any]) throws(TokamakPluginError) -> String {
+    guard let prompt = arguments["prompt"] as? String, !prompt.isEmpty else {
+      throw TokamakPluginError(name: "TypeError", message: "prompt must be a non-empty string")
+    }
+    return prompt
+  }
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@tokamakdev/plugin-local-authentication",
+  "version": "0.1.0-beta.45",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mantty/tokamak.git",
+    "directory": "plugins/local-authentication"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@tokamakdev/plugin": "0.1.0-beta.45"
+  },
+  "files": [
+    "android",
+    "apple",
+    "src",
+    "tokamak-plugin.json",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.ts

@@ -0,0 +1,28 @@
+import { FrontendPlugin } from "@tokamakdev/plugin";
+
+/** The authentication the device owner performs. */
+export type Authentication = "biometricsOrPasscode" | "biometrics";
+
+/** Whether the device can perform an authentication now. */
+export type Status = "available" | "notEnrolled" | "unavailable";
+
+export interface AuthenticateOptions {
+  /** The reason shown in the system authentication prompt. */
+  readonly prompt: string;
+}
+
+class LocalAuthentication extends FrontendPlugin {
+  constructor() {
+    super("local-authentication");
+  }
+
+  status(authentication: Authentication): Promise<Status> {
+    return this.call("status", { authentication });
+  }
+
+  authenticate(authentication: Authentication, options: AuthenticateOptions): Promise<void> {
+    return this.call("authenticate", { authentication, prompt: options.prompt });
+  }
+}
+
+export const localAuthentication = new LocalAuthentication();

package/tokamak-plugin.json

@@ -0,0 +1,33 @@
+{
+  "schemaVersion": 1,
+  "id": "local-authentication",
+  "kind": "frontend",
+  "platforms": {
+    "macos": {
+      "class": "TokamakLocalAuthenticationPlugin",
+      "sources": ["apple/LocalAuthenticationPlugin.swift"],
+      "frameworks": ["LocalAuthentication"]
+    },
+    "ios": {
+      "class": "TokamakLocalAuthenticationPlugin",
+      "sources": ["apple/LocalAuthenticationPlugin.swift"],
+      "frameworks": ["LocalAuthentication"],
+      "plist": {
+        "NSFaceIDUsageDescription": "This app uses Face ID to confirm your identity."
+      }
+    },
+    "ios-simulator": {
+      "class": "TokamakLocalAuthenticationPlugin",
+      "sources": ["apple/LocalAuthenticationPlugin.swift"],
+      "frameworks": ["LocalAuthentication"],
+      "plist": {
+        "NSFaceIDUsageDescription": "This app uses Face ID to confirm your identity."
+      }
+    },
+    "android": {
+      "class": "com.tokamak.plugins.localauthentication.TokamakLocalAuthenticationPlugin",
+      "sources": ["android/LocalAuthenticationPlugin.kt"],
+      "permissions": ["android.permission.USE_BIOMETRIC"]
+    }
+  }
+}