Crate day_part_biometrics

Expand description

day-part-biometrics: the platform’s own “prove it is you” prompt, as one Rust API. No UI of its own; any Rust code can depend on this crate, ask what the device can do, and put the system’s authentication dialog in front of the person.

use day_part_biometrics::{Prompt, availability, Availability};

if availability() == Availability::Available {
    day_part_biometrics::authenticate(Prompt::new("Unlock your notes"), |outcome| match outcome {
        Ok(verified) => println!("verified by {:?}", verified.method),
        Err(e) => println!("not verified: {e}"),
    });
}

Platform selection is #[cfg(target_os)]: iOS and macOS use LocalAuthentication, Android the platform BiometricPrompt (API 28 and later), Windows the Windows Hello consent verifier, and HarmonyOS the User Authentication Kit’s dialog. Desktop Linux and the web have no API an application may use for this, so support reports Unsupported there and every prompt fails with BiometricError::Unsupported.

§What a successful prompt proves

A Verified answer means the OS showed its dialog and the person passed it: a biometric match, or the device credential (passcode, PIN, pattern, account password) when the prompt allows one. The answer is a fact about the moment, not a key: nothing is unlocked by it except what the app chooses to do next. Where the platform can bind a stored secret to the same check, that binding is day-part-keychain’s Protection::UserPresence, which uses this crate’s prompt on the platforms that need one (Windows Hello and HarmonyOS; Apple and Android bind inside their keychain and keystore).

§One prompt at a time

Every platform shows one authentication dialog at a time. A second authenticate while one is on screen fails at once with BiometricError::Busy rather than queuing behind the first. cancel dismisses the prompt on screen; its caller then hears BiometricError::SystemCancelled.

§Threads

Completions run where the platform delivers them (a LocalAuthentication reply queue, an Android executor, a WinRT thread-pool thread, the HarmonyOS JS thread), which is why the callback is Send. authenticate_future is the door back to the UI thread: awaited under day::task, the code after the .await writes signals directly. A callback user captures a Setter instead. Nothing here posts to a main loop, so the crate works in a plain main and under cargo test (docs/async.md rule 3).

Structs§

Prompt: What a person is asked to do, and how the dialog may let them do it.
Verified: A passed prompt.

Enums§

Availability: Whether a prompt can succeed right now, and if not, why.
BiometricError: Why a prompt did not pass.
Biometry: The kind of biometric sensor the device offers for app prompts.
Method: How the person passed the prompt.
Support

Functions§

authenticate: Show the system’s authentication dialog and report how it ended, exactly once, on the platform’s thread. Fails at once, through the same callback, when the prompt is unusable, a prompt is already on screen, or this platform has none.
authenticate_future: authenticate as a future. Dropping it before the answer arrives keeps the dialog on screen (the person still has to settle it) but discards the answer; call cancel to dismiss it.
availability: Whether a prompt can succeed right now, asked of the platform.
biometry: The kind of sensor the device offers. Biometry::None where there is none or the platform reports Unsupported.
cancel: Dismiss the prompt on screen, if any. Its caller hears BiometricError::SystemCancelled.
is_prompting: Whether a prompt from this crate is on screen.
support: What this target’s implementation promises: Native where the platform has a prompt an app may show, Unsupported where it has none (desktop Linux, the web). This is API presence, not a live hardware probe; availability is the probe.