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

package/README.md

@@ -0,0 +1,43 @@
+# @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, `NotSupportedError` when the device cannot
+perform it, and `NeedsUIError` while the app is off screen on iOS or Android,
+where the system cannot show its prompt.
+
+`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/AndroidManifest.xml

@@ -0,0 +1,3 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+  <uses-permission android:name="android.permission.USE_BIOMETRIC" />
+</manifest>

package/android/LocalAuthenticationPlugin.kt

@@ -0,0 +1,59 @@
+package com.tokamak.plugins.localauthentication
+
+import android.hardware.biometrics.BiometricManager
+import android.hardware.biometrics.BiometricManager.Authenticators
+import com.tokamak.runtime.TokamakHost
+import com.tokamak.runtime.TokamakPlugin
+import com.tokamak.runtime.TokamakPluginError
+import com.tokamak.runtime.TokamakPluginReply
+import com.tokamak.runtime.authenticateOwner
+import com.tokamak.runtime.optionalString
+import com.tokamak.runtime.requireObject
+import com.tokamak.runtime.requireOwnerAuthentication
+import com.tokamak.runtime.requireString
+import org.json.JSONObject
+
+class TokamakLocalAuthenticationPlugin(
+    private val host: TokamakHost,
+) : TokamakPlugin {
+    override val id = "local-authentication"
+
+    private val biometrics = host.context.getSystemService(BiometricManager::class.java)
+
+    override fun call(method: String, arguments: Any?, reply: TokamakPluginReply) {
+        when (method) {
+            "status" -> reply(Result.success(status(requireObject(arguments))))
+            "authenticate" -> authenticate(requireObject(arguments), reply)
+            else -> super.call(method, arguments, reply)
+        }
+    }
+
+    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 TokamakPluginError.typeError("prompt must be a non-empty string")
+        host.requireOwnerAuthentication(authenticators)
+        host.authenticateOwner(prompt, authenticators, null, reply) { reply(Result.success(null)) }
+    }
+
+    private fun authenticators(request: JSONObject): Int {
+        val wireName = request.optionalString("authentication")
+        return Authentication.entries.firstOrNull { it.wireName == wireName }?.authenticators
+            ?: throw TokamakPluginError.typeError("authentication must be \"biometricsOrPasscode\" or \"biometrics\"")
+    }
+
+    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),
+    }
+}

package/apple/Info.plist

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>NSFaceIDUsageDescription</key>
+	<string>This app uses Face ID to confirm your identity.</string>
+</dict>
+</plist>

package/apple/LocalAuthenticationPlugin.swift

@@ -0,0 +1,103 @@
+import Foundation
+import LocalAuthentication
+
+final class TokamakLocalAuthenticationPlugin: TokamakPlugin {
+  let id = "local-authentication"
+
+  private let host: TokamakHost
+
+  init(host: TokamakHost) {
+    self.host = host
+  }
+
+  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"
+    }
+  }
+
+  /// Shows the system prompt, which needs the app able to show UI, unless the
+  /// authentication fails without one.
+  private func authenticate(
+    _ policy: LAPolicy,
+    prompt: String,
+    reply: @escaping TokamakPluginReply
+  ) throws(TokamakPluginError) {
+    let context = LAContext()
+    var error: NSError?
+    guard context.canEvaluatePolicy(policy, error: &error) else {
+      throw Self.failure(error)
+    }
+    try host.requireUI()
+    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.100",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mantty/tokamak.git",
+    "directory": "plugins/local-authentication"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "peerDependencies": {
+    "@tokamakdev/plugin": "0.1.0-beta.100"
+  },
+  "files": [
+    "android",
+    "apple",
+    "src",
+    "tokamak-plugin.json",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.ts

@@ -0,0 +1,28 @@
+import { Plugin } 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 Plugin {
+  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,20 @@
+{
+  "schemaVersion": 1,
+  "id": "local-authentication",
+  "platforms": {
+    "macos": {
+      "class": "TokamakLocalAuthenticationPlugin",
+      "sources": ["apple/LocalAuthenticationPlugin.swift"]
+    },
+    "ios": {
+      "class": "TokamakLocalAuthenticationPlugin",
+      "sources": ["apple/LocalAuthenticationPlugin.swift"],
+      "plist": "apple/Info.plist"
+    },
+    "android": {
+      "class": "com.tokamak.plugins.localauthentication.TokamakLocalAuthenticationPlugin",
+      "sources": ["android/LocalAuthenticationPlugin.kt"],
+      "manifest": "android/AndroidManifest.xml"
+    }
+  }
+}