Tauri Plugin Biometry

A Tauri plugin for biometric authentication (Touch ID, Face ID, Windows Hello, fingerprint, etc.) with support for macOS, Windows, iOS, and Android.

Features

• 🔐 Biometric authentication (Touch ID, Face ID, Windows Hello, fingerprint)
• 📱 Full support for iOS and Android
• 🖥️ Desktop support for macOS (Touch ID) and Windows (Windows Hello)
• 🔑 Secure data storage with biometric protection (Android/iOS/macOS/Windows)
• 🎛️ Fallback to device passcode/password
• 🛡️ Native security best practices
• ⚡ Proper error handling with detailed error codes

Installation

Rust

Add the plugin to your Cargo.toml:

[dependencies]
tauri-plugin-biometry = "0.2"

JavaScript/TypeScript

Install the JavaScript/TypeScript API:

npm install @choochmeque/tauri-plugin-biometry-api
# or
yarn add @choochmeque/tauri-plugin-biometry-api
# or
pnpm add @choochmeque/tauri-plugin-biometry-api

Setup

Rust Setup

Register the plugin in your Tauri app:

fn main() {
    tauri::Builder::default()
        .plugin(tauri_plugin_biometry::init())
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

iOS Setup

Add NSFaceIDUsageDescription to your Info.plist:

<key>NSFaceIDUsageDescription</key>
<string>This app uses Face ID to secure your data</string>

Android Setup

The plugin automatically handles the necessary permissions for Android.

Permissions

Configure the plugin permissions in your capabilities/default.json:

{
  "permissions": {
    ["biometry:default"]
  }
}

Usage

Check Biometry Status

import { checkStatus } from '@choochmeque/tauri-plugin-biometry-api';

const status = await checkStatus();
console.log('Biometry available:', status.isAvailable);
console.log('Biometry type:', status.biometryType); // 0: None, 1: TouchID, 2: FaceID, 3: Iris, 4: Auto (Windows Hello)

if (status.error) {
  console.error('Error:', status.error);
  console.error('Error code:', status.errorCode);
}

Authenticate

import { authenticate } from '@choochmeque/tauri-plugin-biometry-api';

try {
  await authenticate('Please authenticate to continue', {
    allowDeviceCredential: true,
    cancelTitle: 'Cancel',
    fallbackTitle: 'Use Passcode',
    title: 'Authentication Required',
    subtitle: 'Access your secure data',
    confirmationRequired: false
  });
  console.log('Authentication successful');
} catch (error) {
  console.error('Authentication failed:', error);
}

Store Secure Data

import { setData, getData, hasData, removeData } from '@choochmeque/tauri-plugin-biometry-api';

// Store data with biometric protection
await setData({
  domain: 'com.myapp',
  name: 'api_key',
  data: 'secret-api-key-123'
});

// Check if data exists
const exists = await hasData({
  domain: 'com.myapp',
  name: 'api_key'
});

// Retrieve data (will prompt for biometric authentication)
if (exists) {
  const response = await getData({
    domain: 'com.myapp',
    name: 'api_key',
    reason: 'Access your API key'
  });
  console.log('Retrieved data:', response.data);
}

// Remove data
await removeData({
  domain: 'com.myapp',
  name: 'api_key'
});

API Reference

Types

enum BiometryType {
  None = 0,
  TouchID = 1,
  FaceID = 2,
  Iris = 3,
  Auto = 4  // Windows Hello (auto-detects available biometry)
}

interface Status {
  isAvailable: boolean;
  biometryType: BiometryType;
  error?: string;
  errorCode?: string;
}

interface AuthOptions {
  allowDeviceCredential?: boolean;  // Allow fallback to device passcode
  cancelTitle?: string;              // iOS/Android: Cancel button text
  fallbackTitle?: string;            // iOS only: Fallback button text
  title?: string;                    // Android only: Dialog title
  subtitle?: string;                 // Android only: Dialog subtitle
  confirmationRequired?: boolean;    // Android only: Require explicit confirmation
}

Functions

checkStatus(): Promise<Status>

Checks if biometric authentication is available on the device.

authenticate(reason: string, options?: AuthOptions): Promise<void>

Prompts the user for biometric authentication.

hasData(options: DataOptions): Promise<boolean>

Checks if secure data exists for the given domain and name.

getData(options: GetDataOptions): Promise<DataResponse>

Retrieves secure data after biometric authentication.

setData(options: SetDataOptions): Promise<void>

Stores data with biometric protection.

removeData(options: RemoveDataOptions): Promise<void>

Removes secure data.

Platform Differences

iOS

• Supports Touch ID and Face ID
• Requires NSFaceIDUsageDescription in Info.plist for Face ID
• Fallback button can be customized with fallbackTitle

Android

• Supports fingerprint, face, and iris recognition
• Dialog appearance can be customized with title and subtitle
• Supports confirmationRequired for additional security

macOS

• Supports Touch ID
• Full keychain integration for secure data storage
• Same API as iOS for consistency
• Requires user authentication for data access
• Important: The app must be properly code-signed to use keychain data storage. Without proper signing, data storage operations may fail with errors

Windows

• Supports Windows Hello (fingerprint, face, PIN)
• Full secure data storage using Windows Hello credentials
• Data is encrypted using AES-256 with Windows Hello protected keys
• Note: setData will prompt for Windows Hello authentication when storing data
• Automatically focuses Windows Hello dialog
• Returns BiometryType.Auto as it uses Windows Hello's automatic selection

Error Codes

Common error codes returned by the plugin:

• userCancel - User cancelled the authentication
• authenticationFailed - Authentication failed (wrong biometric)
• biometryNotAvailable - Biometry is not available on device
• biometryNotEnrolled - No biometric data is enrolled
• biometryLockout - Too many failed attempts, biometry is locked
• systemCancel - System cancelled the operation (device busy)
• appCancel - Application cancelled the operation
• invalidContext - Invalid authentication context
• notInteractive - Non-interactive authentication not allowed
• passcodeNotSet - Device passcode not set
• userFallback - User chose to use fallback authentication
• itemNotFound - Keychain item not found (macOS/iOS)
• authenticationRequired - Authentication required but UI interaction not allowed
• keychainError - Generic keychain operation error
• internalError - Internal plugin error
• notSupported - Operation not supported on this platform

Security Considerations

• All secure data is stored in the system keychain (macOS/iOS), Android Keystore, or Windows Credential Manager
• Data is encrypted and can only be accessed after successful biometric authentication
• The plugin follows platform-specific security best practices
• Windows uses AES-256 encryption with keys derived from Windows Hello credentials
• macOS Code Signing: Your app must be properly code-signed to use keychain storage on macOS. Development builds may work with ad-hoc signing, but production apps require valid Developer ID or App Store signing
• Consider implementing additional application-level encryption for highly sensitive data

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License.

Acknowledgments

Built with Tauri - Build smaller, faster and more secure desktop applications with a web frontend.