feat: add flet-local-auth extension

[mccre110]

Description

Adds the flet-local-auth extension with a LocalAuthentication service for on-device biometric and credential authentication on Android, iOS, macOS, and Windows via local_auth 3.0.2. Linux and Web are explicitly unsupported.

Also includes the Android host changes this extension needs:

• FlutterFragmentActivity and AppCompat LaunchTheme so biometric dialogs work on API 24–27
• a biometric cross-platform permission bundle for NSFaceIDUsageDescription on iOS and macOS
• NSFaceIDUsageDescription in the iOS and macOS dev clients

API:

• is_device_supported(), can_check_biometrics(), get_available_biometrics()
• authenticate() — raises LocalAuthException on failure (upstream local_auth parity)
• stop_authentication()
• Platform auth message types (AndroidAuthMessages, IOSAuthMessages, etc.) aligned with local_auth 3.x

Includes Python package, Flutter extension, client registration, CI, docs, example, and integration tests.

Related: closes #3192 (supersedes closed #3682). Retarget of closed #6759 onto main after release/flet-1.0 was removed.

Test code

import flet as ft
import flet_local_auth as auth


async def main(page: ft.Page):
    local_auth = auth.LocalAuthentication()
    print(await local_auth.is_device_supported())
    print(await local_auth.can_check_biometrics())
    print(await local_auth.get_available_biometrics())
    try:
        ok = await local_auth.authenticate("Unlock to continue")
        print("authenticated:", ok)
    except auth.LocalAuthException as e:
        print("failed:", e.code)


ft.run(main)

Integration tests:

sdk/python/packages/flet/integration_tests/extensions/local_auth/test_local_auth.py

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

Checklist

• I signed the CLA.
• I have performed a self-review of my own code.
• My code follows the style guidelines of this project.
• I have commented my code, particularly in hard-to-understand areas.
• My changes generate no new warnings.
• New and existing tests pass locally with my changes.
• I have made corresponding documentation changes, if applicable.
• I have added changelog entries for user-facing changes, if applicable.
• I have updated release guide pages and website/sidebars.yml for breaking changes, removals, and deprecations, if applicable.

Screenshots

Service invokes the OS biometric modal; no custom Flet UI.

Additional details

N/A

Summary by Sourcery

Add cross-platform local biometric and device-credential authentication to Flet through a new flet-local-auth extension.

New Features:

• Add the flet-local-auth extension, exposing on-device biometric and credential authentication for Android, iOS, macOS, and Windows.
• Provide capability checks, enrolled biometric discovery, authentication cancellation, configurable platform messages, and typed authentication errors.
• Add a local authentication example and integrate the extension into Flet clients and build examples.

Enhancements:

• Update Android app templates and host configuration to support biometric authentication on older Android versions.
• Add a cross-platform biometric permission bundle and required Apple Face ID usage descriptions.

Build:

• Register the new package in the Python and Flutter workspace dependencies and extension lists.

CI:

• Include flet-local-auth in CI package validation.

Documentation:

• Document LocalAuthentication, supported platforms, setup, usage, API types, and Android/macOS publishing requirements.
• List the new extension among built-in extensions.

Tests:

• Add Python integration and error-mapping tests plus Flutter enum-mapping tests for local authentication.

Chores:

• Add changelog entries for the local authentication extension and related platform support changes.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[sourcery-ai]

Hey - I've reviewed your changes and they look great!

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

[FeodorFitsner]

Thanks for putting this together! The API is clear, the wrapper follows upstream closely, and I appreciate the work on packaging, client registration, docs, and examples.

I found two things to fix before merging:

1. Android runtime theme: Only LaunchTheme inherits from AppCompat. FlutterFragmentActivity switches to NormalTheme during startup, which still uses a framework theme. That leaves the fingerprint dialog on Android 24–27 vulnerable to an AppCompat theme exception. Please update NormalTheme in both the client and build-template light/dark resources.

2. Example Face ID configuration: Please add permissions = ["biometric"] under [tool.flet] in the example’s pyproject.toml. Otherwise, packaging it for iOS omits the required NSFaceIDUsageDescription; the dev client’s plist entry doesn’t carry over.

The tests currently cover capability queries and enum mappings, but don’t exercise authentication. Could you add coverage for successful/unsuccessful results and exception translation, and share which platforms you’ve tested an actual authentication prompt on?

The overall approach looks sound—these are targeted fixes, with no redesign needed.

[mccre110]

Thanks for putting this together! The API is clear, the wrapper follows upstream closely, and I appreciate the work on packaging, client registration, docs, and examples.

I found two things to fix before merging:

1. Android runtime theme: Only LaunchTheme inherits from AppCompat. FlutterFragmentActivity switches to NormalTheme during startup, which still uses a framework theme. That leaves the fingerprint dialog on Android 24–27 vulnerable to an AppCompat theme exception. Please update NormalTheme in both the client and build-template light/dark resources.
2. Example Face ID configuration: Please add permissions = ["biometric"] under [tool.flet] in the example’s pyproject.toml. Otherwise, packaging it for iOS omits the required NSFaceIDUsageDescription; the dev client’s plist entry doesn’t carry over.

The tests currently cover capability queries and enum mappings, but don’t exercise authentication. Could you add coverage for successful/unsuccessful results and exception translation, and share which platforms you’ve tested an actual authentication prompt on?

The overall approach looks sound—these are targeted fixes, with no redesign needed.

Thanks for the review. I’ve pushed fixes for both merge blockers:

1. Android runtime theme — NormalTheme now inherits from AppCompat in the client and build-template
   light/dark resources, so the fingerprint dialog stays on an AppCompat theme after FlutterFragmentActivity
   swaps away from LaunchTheme.
2. Example Face ID config — the example pyproject.toml now has permissions = ["biometric"] under
   [tool.flet], so flet build writes NSFaceIDUsageDescription for iOS.
3. Extended unit tests to cover authenticate() success vs failure behavior and Exception translation.

Not covered:

• An integration or mocked authenticate() that returns True
• An integration authenticate() that raises LocalAuthException (cancel, noBiometricHardware, etc.)
• Translation of every error code, only the helper + one known code

Manual System Prompt Testing:

Windows 11

macOS 26

iOS 26

Android 15