Cordova System Unlock Plugin

A Cordova plugin for managing secrets protected by iOS/Android biometrics and
passcode. This is a fork of the excellent
cordova-plugin-fingerprint-aio,
adding support for multiple named secrets, more options for configuring the
unlocking behavior of secrets, and exporting additional JS functions for
checking whether a stored secret already exists, and deleting secrets.

Please consult SystemUnlock.js for more details of the
available functions and options.

Requirements

This plugin will not work on OS versions prior to:

- iOS version 14.5
- Android 9 (API level 28)

On Android, unlocking with the system password/PIN/pattern is only supported on
Android 11 and later. All supported versions of iOS support fallback to the
system passcode.

Under construction!

This fork has been developed to support the
Tokenized Mobile Authenticator App, and is not
recommended over the original
cordova-plugin-fingerprint-aio
unless your exact needs happen to match ours. Currently the only stored secret
configurations that are fully implemented and tested are these:

- {scope: 'activeSystemLock', lockBehavior: 'lockWithDevice'}: A secret which
is accessible to the app whenever the device is unlocked, and gets deleted if
the user turns off the system password/PIN/pattern. The secret never leaves
the device it’s created on (not saved to system backups, and never
transferred, restored, or synced to other devices). On Android the secret will
occasionally require full biometic/passcode unlock (every two weeks by
default).
- {scope: 'activeSystemLock', lockBehavior: 'lockAfterUse'}: A secret which
has to be unlocked by the user every time it’s used, either using biometrics
or the system password/PIN/pattern (if supported – see above), and gets
deleted if the user turns off the system password/PIN/pattern. The secret
never leaves the device it’s created on (not saved to system backups, and
never transferred, restored, or synced to other devices).
- (iOS only) {scope: 'sync', lockBehavior: 'lockAfterUse'}: A secret which is
saved in iCloud Keychain (synced to all devices, end-to-end encrypted). For
this to work, iCloud must be signed in on the device (which can be checked:
await window.SystemUnlock.isiCloudLoggedIn()), and the “Passwords and
Keychain” feature must be turned on in iCloud settings, which can not be
checked programmatically (you must prompt the user to check). If it isn’t
turned on, the secret will be saved locally (and also in the system backup, if
enabled), but won’t be synced to other devices. Setting lockAfterUse causes
the plugin to challenge the user to unlock with Face ID, Touch ID, or the
system passcode every time the secret is accessed.

Acknowledgements

Many thanks to Niklas Merz and the other contributors to
cordova-plugin-fingerprint-aio.

License

The project is MIT licensed: MIT.