add a standalone dispose(), and make it work on every platform

[hpoul]

Adds BiometricStorageFile.dispose(), which forgets a store's initialization without touching its content, so the next getStorage applies a fresh StorageFileInitOptions.

Today the options for a name are resolved once and then ignored for the lifetime of the process, so a store cannot be reconfigured at runtime — changing an authentication validity duration means restarting the app.

Credit

@luckyrat identified this gap and proposed an API for it in #138, following #75 and the fork consolidation in #137. This implements the standalone dispose() rather than that PR's deleteAndDispose: the use case is reconfiguring, and coupling it to deletion made you destroy the stored secret in order to change a duration. delete() then dispose() composes if you want both.

Implemented fresh on current main rather than rebasing #138, which branched from ab59b2b (5.1.1-dev.2); lib/src/biometric_storage.dart has moved +329/-185 and example/lib/main.dart +134 since. #138 also changed no native code, and the method did not actually work on three of the five backends.

What was broken

dispose was already reachable natively. It did not work.

• Linux had no handler at all, so the call fell through to fl_method_not_implemented_response_new() and reached Dart as a MissingPluginException.
• iOS/macOS replied true from a no-op that never cleared stores, so the next init took its short circuit, discarded the freshly passed options and replied false — reporting success at every step while leaving the file on its original configuration. This silent one is why the load-bearing test asserts through forceInit rather than trusting a returned bool.
• Android threw NoSuchStorage on a repeat, the only backend where disposing twice was an error. It now reports whether there was anything to forget.
• win32 and web needed a fix that predates this API: _initialized was keyed by the bare name while BiometricStorageFile carries the prefixed one, so removing by the name dispose is handed would have matched nothing and quietly returned false forever. Both now key on the prefixed form.

The stored content is deliberately untouched on every platform — this reconfigures rather than erases, and a test pins that.

Two contract decisions worth knowing

A disposed handle is spent. read, write and delete throw a StateError; dispose itself does not, so disposing twice stays legal. Without this the platforms disagreed — Android and darwin fail against their registry, Linux/Windows/web carry on from the name alone — which is a mistake you make on one platform and find on another. The flag is set before the call is awaited, so a failed dispose still spends the handle; the race that closes is reachable, the failure it risks is not.

dispose is scoped to the name, not the handle. Every handle is a view onto one name-keyed initialization, so a spent handle still forgets an initialization created after it. Documented and tested, because short-circuiting a repeat dispose on the local flag would quietly make it handle-scoped and answer wrongly.

Verification

Executed on all five backends — the eleven integration tests are the same suite everywhere, so the counts below are all of them:

	what ran	mutation-proven
Android	emulator, 11/11 integration	yes — restoring the NoSuchStorage throw turned 2 red
iOS	simulator, 11/11 integration	yes — restoring the darwin no-op turned 2 red
macOS	real login keychain, 11/11 integration	— (shares BiometricStorageImpl.swift with iOS)
Linux	CI, real libsecret, 11/11 integration	by construction: no handler existed before
Windows	CI, real credential store, 19 unit (1 group skipped)	—

macOS had never run this suite before — it was signing-blocked, and a provisioning profile now exists. It writes to the real login keychain, so the run was checked against a before/after baseline: zero integration_* entries either side, confirming teardown cleans up. No keychain prompt appeared, which is the point of authenticationRequired: false. What it adds beyond iOS is narrow but real: the #if os(macOS) messenger branch in BiometricStoragePlugin.swift, and a real keychain rather than a sandboxed simulator one.

Two honest qualifications. The mutation runs predate the last two tests: the darwin and Android mutations were performed when the suite had 9 and 10 tests respectively, so they prove those fixes are caught, not that every current test is. And Windows never runs the integration suite — it runs biometric_storage_win32_test.dart, which reaches the same dispose paths through the plugin directly rather than through the method channel.

The dispose unit tests are skipped on a Windows host — they drive MethodChannelBiometricStorage, which is unreachable there because the registrant installs Win32BiometricStoragePlugin; biometric_storage_win32_test.dart covers dispose on that host.

flutter analyze --fatal-infos and flutter test clean in both packages.

Breaking

For platform implementations only: dispose is a new member on the BiometricStorage platform interface, so a third-party implementation extending it must add one. No change for callers of the package. Taken now deliberately, while 6.0.0 is still pre-release.

Closes #138.

[Copilot]

Pull request overview

Adds a new public API, BiometricStorageFile.dispose(), to forget a store’s runtime initialization (so the next getStorage can apply new StorageFileInitOptions) while deliberately leaving the stored secret intact. This fits the plugin’s cross-platform “single Dart surface, multiple backends” design by wiring the same dispose semantics through Dart, MethodChannel platforms, and the pure-Dart web/win32 implementations.

Changes:

• Add BiometricStorageFile.dispose() plus a Dart-side “spent handle” guard so disposed handles consistently reject read/write/delete across all platforms.
• Implement/repair native + platform-layer dispose handling (Linux handler added; Android + darwin fixed to actually forget initialization; win32/web fix name-keying so dispose can find entries).
• Add tests (integration + unit) pinning: re-init after dispose, idempotent dispose, content preserved, and disposed-handle behavior.

Reviewed changes

Copilot reviewed 12 out of 13 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
lib/src/biometric_storage.dart	Adds the platform-interface dispose method, MethodChannel implementation, and the BiometricStorageFile.dispose() API + disposed-handle guard.
linux/biometric_storage_plugin.cc	Implements a missing Linux dispose handler by removing the name from the initialization registry without deleting the secret.
android/src/main/kotlin/design/codeux/biometric_storage/BiometricStoragePlugin.kt	Makes Android dispose idempotent and returns a boolean indicating whether an initialization was forgotten.
darwin/biometric_storage/Sources/biometric_storage/BiometricStorageImpl.swift	Fixes darwin dispose from a no-op to actually removing the store entry, returning whether anything was removed.
lib/src/biometric_storage_win32.dart	Keys initialization tracking by prefixed name and implements dispose by forgetting that entry.
lib/src/biometric_storage_web.dart	Keys initialization tracking by prefixed name and implements dispose by forgetting that entry (leaving localStorage intact).
example/integration_test/storage_test.dart	Adds integration tests that prove dispose works (re-init, idempotency, content preserved, spent handle semantics).
test/biometric_storage_test.dart	Adds a MethodChannel-level unit test asserting the dispose call reaches the platform with the expected arguments (skipped on Windows).
test/biometric_storage_win32_test.dart	Adds win32-specific unit tests covering name-forgetting, content preservation, and spent-handle enforcement.
example/lib/main.dart	Adds a UI action to call dispose() and logs the result + expected post-dispose behavior.
CHANGELOG.md	Documents the new API, behavioral contracts, and platform fixes.
pubspec.yaml	Bumps version to 6.0.0-dev.5.
example/pubspec.lock	Updates the example’s locked version to 6.0.0-dev.5.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.