Guardo

Powerful Flutter biometric authentication with automatic lock screen

Seamlessly add biometric authentication to your Flutter apps with automatic lockout handling, customizable lock screens, and smart fallback to device credentials.

Table of Contents

• Key Features
  • Smart Authentication
  • Auto-Lock & Security
  • Customizable UI
  • Developer Experience
• Installation
• Quick Start
• Usage
  • Basic Configuration
  • Unified API
  • Custom Lock Screen
• Actions
• Deprecated Methods
• Localization
• Error Handling
• Common Use Cases
• API Reference
  • GuardoConfig
  • Context Extensions
• Troubleshooting
• Platform Support
• Contributing
• License

Key Features

Smart Authentication

• Biometric authentication - Support for Face ID, Touch ID, Fingerprint, and Iris scanning
• Automatic fallback - Seamlessly switches to PIN/Pattern/Password when biometrics fail or are locked out
• Smart detection - Automatically bypasses authentication UI when no auth methods are configured on device
• Lockout handling - Intelligent handling of temporary and permanent biometric lockouts with user-friendly messages

Auto-Lock & Security

• Auto-lock timer - Automatically locks app after configurable period of inactivity
• App lifecycle management - Locks when app goes to background, unlocks on return with authentication
• Manual lock control - Programmatically lock/unlock app based on your security requirements
• Session persistence - Maintains authentication state across app launches with sticky authentication

Customizable UI

• Custom lock screens - Build completely custom lock screens or use the provided default design
• Theme support - Automatically adapts to system light/dark theme settings
• Localization - Built-in support for English, Spanish, and Arabic with easy custom language addition
• RTL support - Full right-to-left language support with automatic UI mirroring

Developer Experience

• Simple API - Single widget wrapper for entire app authentication
• Clean namespace - All methods organized under context.guardo.* for better code organization
• Flexible control - Enable/disable authentication dynamically based on user preferences or app state
• Debug mode - Easily disable authentication during development with a single flag

Installation

dependencies:
  guardo: ^1.0.0

Platform Setup

<uses-permission android:name="android.permission.USE_BIOMETRIC" />

import io.flutter.embedding.android.FlutterFragmentActivity

class MainActivity: FlutterFragmentActivity() {
    // ...
}

<key>NSFaceIDUsageDescription</key>
<string>This app uses Face ID for secure authentication</string>

Quick Start

Wrap your app with Guardo - that's it!

import 'package:flutter/material.dart';
import 'package:guardo/guardo.dart';

void main() => runApp(
  Guardo(
    child: MaterialApp(
      home: MyHomePage(),
    ),
  ),
);

Usage

Basic Configuration

Guardo(
  enabled: true, // Enable/disable authentication
  config: GuardoConfig(
    localizedReason: 'Please authenticate to access the app',
    biometricOnly: true,
    lockTimeout: Duration(minutes: 5), // Auto-lock after inactivity
  ),
  child: YourApp(),
)

Unified API

All Guardo methods are organized under context.guardo.*:

// Check authentication status
if (context.guardo.isAuthenticated) {
  // User is authenticated
}

// Perform secure action
await context.guardo.action(
  onSuccess: () => deleteAccount(),
  onFailure: (error) => showError(error),
  reason: 'Authenticate to delete account',
);

// Manual lock/unlock
await context.guardo.lockApp();
await context.guardo.unlockApp();

// Check device capabilities
final hasAuth = await context.guardo.hasAuthenticationMethods();

Custom Lock Screen

Guardo(
  lockScreen: (context, onUnlock) {
    return Scaffold(
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            Icon(Icons.lock, size: 100),
            Text('App Locked'),
            ElevatedButton(
              onPressed: onUnlock,
              child: Text('Unlock'),
            ),
          ],
        ),
      ),
    );
  },
  child: YourApp(),
)

Actions

Actions are secure operations that require authentication before execution. The unified action() method intelligently handles both synchronous and asynchronous operations, automatically prompting for biometric authentication when needed.

How Actions Work

• Authentication first - Prompts user for biometric/PIN authentication before executing
• Automatic type detection - Detects if your operation is sync or async automatically
• Error handling - Built-in failure callbacks for graceful error management
• Return values - Supports operations that return values with type safety

// Synchronous action - blocks until completion
await context.guardo.action(
  onSuccess: () => performAction(),
  reason: 'Please authenticate',
);

// Asynchronous action - handles async operations seamlessly
await context.guardo.action(
  onSuccess: () async => await uploadData(),
  reason: 'Authenticate to upload',
);

// Action with return value - get results from secure operations
final result = await context.guardo.action<String>(
  onSuccess: () async => await fetchSecretKey(),
  onFailure: (error) => 'default_key',
  reason: 'Access encryption key',
);

Deprecated Methods

These methods are still available for backward compatibility but will be removed in a future version. Use the new context.guardo.* API instead.

Localization

Built-in Languages

• English (en)
• Spanish (es)
• Arabic (ar)

Setup

MaterialApp(
  localizationsDelegates: const [
    GuardoLocalizations.delegate,
    GlobalMaterialLocalizations.delegate,
    GlobalWidgetsLocalizations.delegate,
  ],
  supportedLocales: const [
    Locale('en'), Locale('es'), Locale('ar'),
  ],
  home: Guardo(child: MyApp()),
)

Custom Languages

Create a custom localization:

class GuardoLocalizationsKo extends GuardoLocalizations {
  @override
  String get authenticateToUnlock => '잠금을 해제하려면 인증해 주세요';
  // ... implement other required strings
}

Error Handling

try {
  await context.guardo.action(
    onSuccess: () => sensitiveOperation(),
  );
} on BiometricLockoutException {
  // Handle temporary lockout
  showMessage('Too many attempts. Try again later.');
} on BiometricUnavailableException {
  // Handle unavailable biometrics
  showMessage('Biometrics not available');
}

Common Use Cases

Banking App

// Secure transaction
await context.guardo.action(
  onSuccess: () async => await transferMoney(amount),
  reason: 'Authenticate to transfer funds',
);

Note-Taking App

// Lock on app background
Guardo(
  config: GuardoConfig(
    lockTimeout: Duration(seconds: 30),
  ),
  child: NotesApp(),
)

Healthcare App

// View sensitive data
final medicalRecords = await context.guardo.action<List<Record>>(
  onSuccess: () async => await fetchMedicalRecords(),
  onFailure: (e) => [],
  reason: 'Authenticate to view medical records',
);

API Reference

GuardoConfig

Context Extensions

All methods available via context.guardo.*:

Troubleshooting

App not locking?

Ensure Guardo wraps your entire MaterialApp:

Guardo(
  config: GuardoConfig(lockTimeout: Duration(minutes: 5)),
  child: MaterialApp(...), // Correct
)

Biometrics not working?

Check device capabilities first:

if (await context.guardo.hasAuthenticationMethods()) {
  // Safe to use authentication
}

Debug mode?

Disable authentication during development:

Guardo(
  enabled: !kDebugMode, // Disabled in debug mode
  child: YourApp(),
)

Platform Support

Contributing

We welcome contributions! See our Contributing Guidelines for details.

# Clone the repository
git clone https://github.com/fathialamre/guardo.git

# Run example app
cd example
flutter run

License

MIT License - see the LICENSE file for details.