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

$3

Add the plugin to your Cargo.toml:

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

$3

Install the JavaScript/TypeScript API:

`bash
npm install @choochmeque/tauri-plugin-biometry-api


or

yarn add @choochmeque/tauri-plugin-biometry-api

or

pnpm add @choochmeque/tauri-plugin-biometry-api
`

Setup

$3

Register the plugin in your Tauri app:

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

$3

Add NSFaceIDUsageDescription to your Info.plist:

`xml
NSFaceIDUsageDescription
This app uses Face ID to secure your data
`

$3

The plugin automatically handles the necessary permissions for Android.

$3

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

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

Usage

$3

`typescript
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);
}
`

$3

`typescript
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);
}
`

$3

`typescript
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

$3

`typescript
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
}
`

$3

#### checkStatus(): Promise

Checks if biometric authentication is available on the device.

#### authenticate(reason: string, options?: AuthOptions): Promise

Prompts the user for biometric authentication.

#### hasData(options: DataOptions): Promise

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

#### getData(options: GetDataOptions): Promise

Retrieves secure data after biometric authentication.

#### setData(options: SetDataOptions): Promise

Stores data with biometric protection.

#### removeData(options: RemoveDataOptions): Promise

Removes secure data.

Platform Differences

$3

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

$3

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

$3

- 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

$3

- 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.