@molecule/app-biometrics

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

Biometric authentication interface for molecule.dev.

Provides a unified API for biometric authentication (FaceID, TouchID, Fingerprint) that works across different platforms.

Quick Start

import { checkAvailability, authenticate } from '@molecule/app-biometrics'

// On web this works with ZERO wiring: a WebAuthn-based provider is
// auto-registered on first use (secure context + user gesture required).
const availability = await checkAvailability()
if (availability.available) {
  const result = await authenticate({
    reason: 'Confirm it is you before revealing the recovery codes',
  })
  if (result.success) {
    // unlock the locally-guarded action — see @remarks: this is NOT server auth
  }
}

Type

native

Installation

npm install @molecule/app-biometrics @molecule/app-bond @molecule/app-logger

API

Interfaces

AuthenticateOptions

Biometric authentication prompt configuration (reason text, title, fallback, max attempts).

interface AuthenticateOptions {
  /**
   * Reason/prompt to show the user.
   */
  reason: string

  /**
   * Title for the biometric prompt (Android).
   */
  title?: string

  /**
   * Subtitle for the biometric prompt (Android).
   */
  subtitle?: string

  /**
   * Whether to allow device credentials as fallback.
   */
  allowDeviceCredential?: boolean

  /**
   * Text for the cancel button.
   */
  cancelTitle?: string

  /**
   * Text for the fallback button (iOS).
   */
  fallbackTitle?: string

  /**
   * Maximum number of attempts.
   */
  maxAttempts?: number
}

AuthenticateResult

Biometric authentication outcome (success flag, error code, error message).

interface AuthenticateResult {
  /**
   * Whether authentication succeeded.
   */
  success: boolean

  /**
   * Error code if failed.
   */
  errorCode?:
    | 'user_cancel'
    | 'user_fallback'
    | 'system_cancel'
    | 'lockout'
    | 'biometric_not_enrolled'
    | 'biometric_not_available'
    | 'unknown'

  /**
   * Error message if failed.
   */
  errorMessage?: string
}

BiometricAvailability

Biometric availability status.

interface BiometricAvailability {
  /**
   * Whether biometrics is available.
   */
  available: boolean

  /**
   * Available biometric type.
   */
  biometricType: BiometricType

  /**
   * Human-readable description.
   */
  description: string

  /**
   * Whether the device has enrolled biometrics.
   */
  hasEnrolled: boolean

  /**
   * Reason if not available.
   */
  reason?: 'no_hardware' | 'not_enrolled' | 'not_available' | 'permission_denied'
}

BiometricsProvider

Biometrics provider interface.

All biometrics providers must implement this interface.

interface BiometricsProvider {
  /**
   * Checks biometric availability on the device.
   * @returns The availability status including biometric type, enrollment, and failure reason.
   */
  checkAvailability(): Promise<BiometricAvailability>

  /**
   * Authenticates the user with biometrics.
   * @param options - Authentication prompt configuration (reason, title, fallback settings).
   * @returns The authentication result indicating success or error details.
   */
  authenticate(options: AuthenticateOptions): Promise<AuthenticateResult>

  /**
   * Checks if the device is secure (has PIN/password/biometric).
   * @returns Whether the device has a secure lock screen configured.
   */
  isDeviceSecure(): Promise<boolean>

  /**
   * Gets the primary biometric type available on the device.
   * @returns The biometric type: 'fingerprint', 'face', 'iris', or 'none'.
   */
  getBiometricType(): Promise<BiometricType>
}

CreateWebAuthnProviderOptions

Options for creating a WebAuthn-based biometrics provider.

interface CreateWebAuthnProviderOptions {
  /**
   * Optional translation function for i18n support.
   * When provided, error messages will be passed through this function.
   */
  t?: TranslateFn
}

Types

BiometricType

Available biometric types.

type BiometricType = 'fingerprint' | 'face' | 'iris' | 'none'

Functions

authenticate(options)

Authenticates the user with biometrics.

function authenticate(options: AuthenticateOptions): Promise<AuthenticateResult>

• options — Authentication prompt configuration (reason, title, fallback settings).

Returns: The authentication result indicating success or error details.

checkAvailability()

Checks biometric availability on the device.

function checkAvailability(): Promise<BiometricAvailability>

Returns: The availability status including biometric type, enrollment, and failure reason.

createWebAuthnProvider(options)

Creates a WebAuthn-based biometrics provider.

Uses the Web Authentication API for biometric authentication. Note: Full biometric auth requires server-side credential storage. This provides a simplified local authentication flow.

function createWebAuthnProvider(options?: CreateWebAuthnProviderOptions): BiometricsProvider

• options — Optional configuration including a translation function for i18n.

Returns: A BiometricsProvider that uses WebAuthn for platform-based biometric authentication.

getBiometricType()

Gets the primary biometric type available on the device.

function getBiometricType(): Promise<BiometricType>

Returns: The biometric type: 'fingerprint', 'face', 'iris', or 'none'.

getProvider()

Gets the current biometrics provider. Falls back to a WebAuthn-based provider if none is set.

function getProvider(): BiometricsProvider

Returns: The active BiometricsProvider instance.

hasProvider()

Checks if a biometrics provider has been registered.

function hasProvider(): boolean

Returns: Whether a BiometricsProvider has been bonded.

isDeviceSecure()

Checks if the device has a secure lock screen (PIN, password, or biometric).

function isDeviceSecure(): Promise<boolean>

Returns: Whether the device is secure.

setProvider(provider)

Sets the biometrics provider implementation.

function setProvider(provider: BiometricsProvider): void

• provider — The provider implementation.

Injection Notes

Requirements

Peer dependencies:

• @molecule/app-bond ^1.0.1
• @molecule/app-logger ^1.0.1

Runtime Dependencies

• @molecule/app-bond
• @molecule/app-logger

A successful {@link authenticate} is a CLIENT-side gate, NOT server authentication. FaceID / TouchID / fingerprint unlocking the device proves nothing to your API — the server still requires a valid session/token on every request. Use biometrics to locally re-confirm a sensitive action or unlock a stored value; NEVER treat a biometric "success" as authorization for a backend call, and never send biometricPassed=true to the server and trust it. (WebAuthn via {@link createWebAuthnProvider} is different — it's a real cryptographic assertion your server verifies.)

• Gate on {@link checkAvailability} / {@link isDeviceSecure} first, and always offer a password fallback — many devices have no enrolled biometrics.
• A WebAuthn provider is auto-registered on first use when none is set — great on web (needs a secure context and a user gesture), but on React Native or other non-browser runtimes the auto-registered provider cannot work (navigator.credentials does not exist): there is currently NO prebuilt native bond, so on native you must implement BiometricsProvider over the platform biometric API and call setProvider() BEFORE any call auto-bonds the web one.
• Check availability from a user-initiated flow; browsers reject WebAuthn calls that are not tied to user activation.

Translations

Translation strings are provided by @molecule/app-locales-biometrics.