Constants

KeychainErrorCode

Why a call failed: twenty codes, the same on iOS and Android. A constant object and a type of the same name: KeychainErrorCode.KeyInvalidated is the string KEY_INVALIDATED.

Import
import { KeychainErrorCode } from '@apexnative/keychain';

The code of a KeychainError. Each constant is its string, so error.code === KeychainErrorCode.KeyInvalidated and error.code === 'KEY_INVALIDATED' are the same check, and a switch over the constants is checked by TypeScript.

Usage

import { KeychainError, KeychainErrorCode } from '@apexnative/keychain';

function message(error: KeychainError): string | null {
  switch (error.code) {
    case KeychainErrorCode.UserCanceled:
    case KeychainErrorCode.SystemCanceled:
      return null;
    case KeychainErrorCode.Lockout:
      return 'Too many attempts. Try again in a moment.';
    case KeychainErrorCode.KeyInvalidated:
      return 'Face ID changed on this device. Sign in again.';
    default:
      return 'Something went wrong.';
  }
}

Signature

const KeychainErrorCode: {
  readonly UserCanceled: 'USER_CANCELED';
  readonly UserFallback: 'USER_FALLBACK';
  // … one member for each code below
  readonly Unknown: 'UNKNOWN';
};

type KeychainErrorCode = (typeof KeychainErrorCode)[keyof typeof KeychainErrorCode];

Type'USER_CANCELED' | 'USER_FALLBACK' | … | 'UNKNOWN'PlatformsiOSAndroid

Codes

The prompt

Constant	String	When
`UserCanceled`	`USER_CANCELED`	The user canceled the prompt. On Android 16, also a prompt that was open when the app went to the background: Android reports it as the user's cancel
`UserFallback`	`USER_FALLBACK`	iOS: the user tapped the fallback button of a prompt for biometrics alone (`biometryAny`, `biometryCurrentSet`). `prompt.fallback: ''` hides the button
`SystemCanceled`	`SYSTEM_CANCELED`	The system closed the prompt: the app went to the background, a call came in
`AuthFailed`	`AUTH_FAILED`	iOS: the face or the finger wasn't recognized
`Lockout`	`LOCKOUT`	Too many failed attempts: the biometrics is locked for a while
`LockoutPermanent`	`LOCKOUT_PERMANENT`	Android: the biometrics is locked until the user enters the passcode

The device

Constant	String	When
`BiometryNotEnrolled`	`BIOMETRY_NOT_ENROLLED`	A write that needs enrolled biometrics, on a device without
`BiometryNotAvailable`	`BIOMETRY_NOT_AVAILABLE`	A write that needs biometrics, on a device without a sensor, or with one that is unavailable
`PasscodeNotSet`	`PASSCODE_NOT_SET`	A write that needs a passcode, PIN or pattern, on a device without
`HardwareUnavailable`	`HARDWARE_UNAVAILABLE`	Android: `strongboxRequired` on a device without StrongBox
`Unsupported`	`UNSUPPORTED`	The option needs a newer OS (the passcode or `authValidity` before Android 11), the platform has no keychain (the web), or the native module isn't in the app (Expo Go)

The item

Constant	String	When
`KeyInvalidated`	`KEY_INVALIDATED`	The enrolled biometrics changed since a `biometryCurrentSet*` item was written: the item was removed. Sign the user in again
`DataCorrupted`	`DATA_CORRUPTED`	The stored value can't be decrypted or decoded, and not because the key was invalidated

Not now

Constant	String	When
`InteractionNotAllowed`	`INTERACTION_NOT_ALLOWED`	The device is locked, and the item is `whenUnlocked*` or `whenPasscodeSetThisDeviceOnly`; on iOS also a prompt asked for in the background
`AuthRequired`	`AUTH_REQUIRED`	A synchronous read of an item that needs a prompt
`NoActivity`	`NO_ACTIVITY`	Android: no activity to show the prompt in

The app's setup

Constant	String	When
`MissingEntitlement`	`MISSING_ENTITLEMENT`	iOS: an `accessGroup` the app has no entitlement for
`MissingUsageDescription`	`MISSING_USAGE_DESCRIPTION`	iOS: `NSFaceIDUsageDescription` is missing from Info.plist, on a device with Face ID; for a biometric item's write and read, and for `canUseAccessControl`
`InvalidArgument`	`INVALID_ARGUMENT`	A key, a value or options that aren't valid; bytes read as text that aren't UTF-8; on iOS, a key held by another library's item

Anything else

Constant	String	When
`Unknown`	`UNKNOWN`	A failure the package has no code for; `nativeCode` and `nativeDomain` say more

Usage​

Signature​

Codes​

The prompt​

The device​

The item​

Not now​

The app's setup​

Anything else​

See also​