NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
pub.dev
pub.dev, #1855 most downloaded on pub.dev
Secure Storage: Encrypted data store optionally secured by biometric lock with support for iOS, Android, MacOS. Partial support for Linux, Windows and web (localStorage).
Latest stable
5.0.1
Last release 12 days ago
10 Nov 2026
Release timing varies
gaps range from 2 weeks to 12 months
Nearly every release is documented
notes for 38 of 42 stable releases
Nothing withdrawn
no release was ever pulled
7 years old
77 releases · first in 2019
Drag across the ruler to compare, or tap a release to open it.
BiometricStorageFile.dispose() forgets a store's initialization without touching its content, so the next getStorage applies a fresh StorageFileInitOp
BiometricStorageFile.dispose() forgets a store's initialization without
touching its content, so the next getStorage applies a fresh
StorageFileInitOptions. Until now the options for a name were resolved once
and then ignored for the lifetime of the process, so a store could not be
reconfigured at runtime — changing, say, an authentication validity duration
meant restarting the app. Thanks to @luckyrat, who identified the gap and
proposed an API for it in #138 (see also #75 and #137); this implements the
standalone dispose() rather than that PR's delete-coupled form, so
reconfiguring no longer costs you the stored value. Call delete() first if
you want both.
Returns true when there was an initialization to forget and false when
there was not, so disposing twice is safe. Android previously raised
NoSuchStorage on a repeat, the only backend where that was an error.
The method was reachable natively before this, and did not work: Linux had no
handler at all, so the call reached Dart as a MissingPluginException, and
iOS/macOS answered true from a no-op that never cleared the entry — so
re-initializing silently kept the original configuration while reporting
success at every step. Both are fixed, and the store's content is deliberately
left alone on every platform.
A disposed BiometricStorageFile now refuses read, write and delete
with a StateError — not dispose itself, which stays idempotent. The
backends do not agree on their own: Android and iOS/macOS resolve those calls
against a registry and fail once the entry is gone, while Linux, Windows and
web answer from the name alone and would carry on working. The guard sits in
Dart so the answer is the same everywhere, rather than being a mistake you
make on one platform and discover on another.
Breaking for platform implementations only. dispose is a new member on
the BiometricStorage platform interface, so a third-party implementation
that extends it must add one. No change for callers of the package.
Your coding agent can read these notes before it upgrades. Set up the MCP server →
Four conditions a caller has to tell apart, and until now could not. Thanks @olehmarch-bro for the implementation (#158).
Four conditions a caller has to tell apart, and until now could not. Thanks @olehmarch-bro for the implementation (#158).
AuthExceptionCode.lockout and .lockoutPermanent. A biometric lockout is
recoverable — by waiting, or by entering the device credential — but Android
reported both ERROR_LOCKOUT and ERROR_LOCKOUT_PERMANENT as
AuthExceptionCode.unknown, which is the code an app has no response to but
"something went wrong". This is the split 6.0.0-dev.4 promised when it
documented AuthExceptionCode as an open enum.
iOS/macOS report a biometric lockout as .lockoutPermanent too. The Keychain
gives no status of its own for it, so the plugin asks LocalAuthentication
(canEvaluatePolicy, synchronous and without UI) once a call has failed, and
then also sees a lockout that the failing attempt is what caused. Apple has a
single lockout state and it never clears by waiting, so it maps to the
permanent member; a store with darwinBiometricOnly: false never reports it,
since its items stay reachable through the passcode.
Breaking: android reports AuthExceptionCode.keyInvalidated from read()
when enrolled biometrics changed and took the store's key with them.
Previously the plugin deleted the dead key and file and read on, returning
null — the same answer as an empty store, so an app could not tell a secret
the user never set from one the OS had just destroyed. Those two want
different handling, and the second is the one worth telling the user about.
A caller that treats null as "nothing stored" now has an exception to catch
on that path. It arrives once per invalidation: the dead key and file are
removed before it is raised, so the read after it returns null like any
other read of an empty store.
write() is unchanged and still recovers silently: a write has lost nothing
it was not about to replace, and failing it would hand every caller an error
whose only sensible recovery is to write the same content again.
Certain when reported, and only reported where it is certain. Android raises
KeyPermanentlyInvalidatedException, which is unambiguous, for a store that
authenticates per use. A store with androidAuthenticationValidityDuration
holds a key bound to the device credential as well, which an enrollment
change does not invalidate.
Breaking: iOS/macOS translate the Keychain's errSecAuthFailed into
AuthException(AuthExceptionCode.authFailed) instead of leaving it as
PlatformException(SecurityError, …). This is what #128 asked for: matching
the English in -25293: The user name or passphrase you entered is not correct was the only way to recognise a failed authentication. Catch
AuthException where you caught a PlatformException for it.
authFailed, deliberately, and not keyInvalidated. The honest answer on
this platform is that the plugin does not know which it has: Apple reports a
user who looked away (#80), a device whose sensor it will not use (#101), and
an access control that can never be satisfied again (#128) as the same
errSecAuthFailed. Reporting all of it as invalidation would tell an app its
data was gone every time a prompt was failed — and an app that believes it
deletes a secret it could still have read. Ask the user to authenticate
again; that answer is right for all three.
android: a stored file that can no longer be decrypted — its keystore key is gone, as after a backup restored onto another device, or the file is corr
.unreadable,
instead of failing every read. Reading never creates a key.android: storage with authenticationRequired: false reads, writes and deletes on the plugin's worker thread instead of the main thread, where its keys
authenticationRequired: false reads, writes and
deletes on the plugin's worker thread instead of the main thread, where its
keystore calls dropped Flutter frames.androidAuthenticationValidityDuration also reads and
writes on the worker thread while its validity window is open.android: fix minifyReleaseWithR8 failing in every app that ships a release build. The plugin depended on kotlin-logging, which names every backend it
android: fix minifyReleaseWithR8 failing in every app that ships a release
build. The plugin depended on kotlin-logging, which names every backend it
can bind to, so R8 walked references to ch.qos.logback.* classes that were
genuinely absent and refused to complete:
Missing class ch.qos.logback.classic.Logger (referenced from: ...)
Execution failed for task ':app:minifyReleaseWithR8'
Minification runs in release and nowhere else, so nothing anyone does while
developing reaches it — flutter run, flutter test and an emulator check
all build debug or profile. The first thing to hit it is an attempt to ship
to Play, which is the worst possible moment. Present in 6.0.0-dev.4.
Fixed by removing the dependencies, so nothing needs suppressing. If you
added -dontwarn ch.qos.logback.** to your own proguard-rules.pro to get
6.0.0-dev.4 to build, you can drop it.
android: the plugin's logging now actually produces output. slf4j-api and
kotlin-logging are both facades and neither had a provider, so SLF4J
reported No SLF4J providers were found once and discarded every call after
that. Unless a consuming app happened to ship a binding of its own, this
package has logged nothing at all on Android. It now writes to
android.util.Log under the tag BiometricStorage, and both dependencies
are dropped.
Debug builds log everything. Release builds stay silent until asked:
adb shell setprop log.tag.BiometricStorage VERBOSE
android: BiometricStorageLogging lets an app choose the level and the
destination. level overrides the default above — set it to Log.VERBOSE to
keep verbose logging in a release build without depending on a device
property. sink hands every record to your own logging framework instead of
android.util.Log, with the Throwable passed separately rather than
flattened into the message, so you can report the real exception:
BiometricStorageLogging.sink =
BiometricStorageLogging.Sink { priority, tag, message, throwable ->
// forward to slf4j, Timber, a file appender, a crash reporter
}
Installing a sink turns every level on unless level says otherwise. Both
are optional and the default is unchanged. See the README for the full
slf4j example.
Exception codes on BiometricStorageException, the win32 storageFailure path reached by a real store failure, and the integration scaffold that runs th
Exception codes on BiometricStorageException, the win32 storageFailure
path reached by a real store failure, and the integration scaffold that
runs the plugin against real libsecret on CI.
Carries the unreleased 6.0.0-dev.3 fixes too, including the Linux read()
path that leaked a plaintext secret on every call.
BiometricStorageException carries a code. It previously held only a
message, so telling "you called getStorage twice" from "the credential store
failed" meant matching English text — and 6.0.0-dev.2 took the number of
places it is raised from one to six. BiometricStorageExceptionCode is
alreadyInitialized, storageFailure or unknown, and every site that
raises BiometricStorageException classifies itself, including the
AlreadyInitialized the method-channel platforms raise. Additive: the
positional constructor is unchanged and defaults to unknown, so existing
catch blocks keep working. Switch over it with a default — members may be
added in a minor release.
Note the boundary: storageFailure today reaches only Windows. A failing
keychain, keystore or libsecret still surfaces as a raw PlatformException
(SecurityError, Unexpected Error and Security Access Error among
others), because those are not translated. So a single cross-platform "the store failed" branch is
not yet writable; that is a later change.
AuthExceptionCode is documented as an open enum, matching the above. No
behaviour change — but it means the members that Android currently collapses
into unknown, lockout among them, can be split out in a minor release rather
than waiting for 7.0.
Six pre-existing bugs, all found while reviewing 6.0.0-dev.1 and none introduced by it.
Six pre-existing bugs, all found while reviewing 6.0.0-dev.1 and none introduced by it.
androidx.biometric refuses to start after
onSaveInstanceState — logging Unable to start authentication — and returns
without invoking any callback, so the pending Flutter result never completed.
The state is checked up front and reported as
AuthException(AuthExceptionCode.unknown) instead. Reachable whenever the app
is backgrounded, independently of the configuration-change bug below.Activity after a configuration
change. onReattachedToActivityForConfigChanges and
onDetachedFromActivityForConfigChanges were both empty, so after a rotation
every authenticated read or write handed BiometricPrompt a dead
FragmentActivity. ActivityAware documents that the old reference must be
cleared and the new binding adopted; now both happen.PlatformException.code — the field callers match on. The code is now
NotInitialized.init replied twice when an argument was missing or mistyped, so
the caller saw the error and then a success. The success reply now only
happens on the success path.canAuthenticate() reports an unrecognised LAError
as CanAuthenticateResponse.statusUnknown rather than unsupported, matching
Android. unsupported means "the plugin does not support this platform", so a
recoverable biometryLockout was telling callers to give up entirely. Callers
that treat statusUnknown as usable will now attempt authentication where
they previously did not.getStorage() for a name that is already
open no longer rebuilds the store. It used to replace it outright, which threw
away the cached LAContext — so any
darwinTouchIDAuthenticationForceReuseContextDuration in progress — and
quietly adopted whatever options the second call passed. The first call now
wins, as on Android. If you relied on re-initializing to change options, give
each set of options its own store name, or restart — there is no API to close
a store, so none can be reopened differently within a run. Passing different
options to a repeat call was never reported back to Dart, and now definitively
does nothing.forceInit now does what it documents on Windows, web, iOS and
macOS. It was implemented on Android only; the others accepted the flag and
dropped it. It throws BiometricStorageException on every platform — the
PlatformException(code: 'AlreadyInitialized') that the method-channel
platforms raise is translated, so one catch clause covers all of them.
Linux still ignores the flag: its init keeps no per-store state at all,
so implementing it there is a separate change.read() and delete() throw BiometricStorageException
when the credential store fails, instead of returning null and false.
Those values still mean "no value stored" and "there was nothing to delete" —
previously they doubled as the answer for a failing store, so a failure read
as data loss.canAuthenticate() names biometryLockout explicitly rather than
letting it fall through the unmapped-code path, and the nil-error branch
reports statusUnknown too rather than unsupported.iOS/macOS: StorageFileInitOptions.darwinKeychainAccessGroup to store items in a shared keychain access group (kSecAttrAccessGroup), so an app extensio
StorageFileInitOptions.darwinKeychainAccessGroup to store items
in a shared keychain access group (kSecAttrAccessGroup), so an app
extension can read them. Note that the access group is part of an item's
identity — existing items are not migrated automatically.Improve canAuthenticate to include InitOptions to decide for which authenticaiton type to check.
canAuthenticate to include InitOptions to decide for which authenticaiton type to check.Nothing published for this version
* upgrade dependency to web 1.0
enable building on jdk 17 and up https://github.com/authpass/biometric_storage/issues/117 thanks @connyduck
Split Split authenticationValidityDurationSeconds between android and iOS
darwinTouchIDAuthenticationForceReuseContextDuration: Basically the equivalent to androidAuthenticationValidityDurationdarwinTouchIDAuthenticationAllowableReuseDurationNothing published for this version
Nothing published for this version
Add option for iOS/MacOS to allow non-biometric authentication (darwinBiometricOnly) #101
darwinBiometricOnly) #101
3.2.Nothing published for this version
Android: (POTENTIALLY BREAKING): Completely removed deprecated old file backend based on androidx.security. This was deprecated since version 3.0.0 an…
promptInfo during read/write thanks @luckyratandroidx.security. This was deprecated since version 3.0.0 and users
should have been migrated on every read or write. (this is only internally, does not change
anything of the API).Build with flutter 3.13, fix macOS build
Build with flutter 3.13, fix macOS build
android: Upgrade AGP, fix building with AGP 8, upgrade all java depen…
android: Upgrade AGP, fix building with AGP 8, upgrade all java depen…
Android: Depend on slf4j-api.
Android: Depend on slf4j-api.
* Add topics to pubspec.yaml
iOS/MacOS: Reuse LAContext to make touchIDAuthenticationAllowableReuseDuration work. thanks @radvansky-tomas
touchIDAuthenticationAllowableReuseDuration work.
thanks @radvansky-tomasAndroid: Move File I/O and encryption to background thread. (Previously used UI Thread) https://github.com/authpass/biometric_storage/pull/64
Fix building on all platforms, add github actions to test building.
Android: Remove Moshi dependency altogether. #53
Nothing published for this version
Update to Moshi 1.13 for Kotlin 1.6.0 compatibility. #53
Fixed compile errors with Flutter >= 2.8.0 (Compatible with Flutter 2.5). #47 fix #42
Nothing published for this version
Android: Validate options on int When authenticationValidityDurationSeconds == -1, then androidBiometricOnly must be true
int
When authenticationValidityDurationSeconds == -1, then androidBiometricOnly must be trueauthenticationValidityDurationSeconds is > 0 only show authentication prompt when
necessary. (It will simply try to use the key, and show the auth prompt only when a
UserNotAuthenticatedException is thrown).Nothing published for this version
Please check below for breaking changes in the -rc releases.
-rc releases.Android: Fix a few bugs with authenticationValidityDurationSeconds == -1
authenticationValidityDurationSeconds == -1authenticationValidityDurationSeconds == -1delete if item was not found.unknown exception was thrown instead of userCanceled)androidBiometricOnly prior to Android R (30).AuthExceptionCode.canceledNothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Breaking Change: authenticationValidityDurationSeconds is now -1 by default, which was not supported before hand. If you need backward compatibility,…
Breaking Change: authenticationValidityDurationSeconds is now -1 by default, which was
not supported before hand. If you need backward compatibility, make sure to override this value
to the previous value of 10.
Breaking Change: No more support for Android v1 Plugin registration.
Breaking Change: No longer using androidx.security, but instead handle encryption directly. Temporarily there is a fallback to read old content. This requires either reencrypting everything, or old data will no longer be readable.
authenticationValidityDurationSeconds = -1.BIOMETRIC_WEAK is no longer used, only BIOMETRIC_STRONG.Don't ask for authentication for delete.
Nothing published for this version
Breaking Change: due to the introduction of iOS prompt info there is now a wrapper object PromptInfo which contains AndroidPromptInfo and IosPromptInf…
PromptInfo which contains AndroidPromptInfo and IosPromptInfo.Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
compatibility with kotlin 1.5.20
androidx.security:security-crypto from 1.1.0-alpha02 to 1.1.0-alpha03
Handle android BIOMETRIC_STATUS_UNKNOWN response on older devices (Android 9/API 28(?))
BIOMETRIC_STATUS_UNKNOWN response on older devices
(Android 9/API 28(?))* Null safety stable release.
* Null safety migration.
Upgrade to latest Android dependencies (gradle plugin, androidx.*, gradle plugin)
upgrade android moshi dependency.
Nothing published for this version
Support for web support: Warning: Unencrypted - stores into local storage on web!
Nothing published for this version
Nothing published for this version
* Fix windows plugin config.
Workaround to not load win32 when compiling for web.
Windows: Initial support for windows. only unauthenticated storage in Credential Manager.
One column per quarter.