[WIP] fix(android): isolate storage instances per shared preferences name (fix: #1023)

[mateusz-pietras]

Fix Android namespace isolation for sharedPreferencesName

Fixes #1023

Problem

Multiple FlutterSecureStorage instances with different sharedPreferences Name values shared a single cached FlutterSecureStorage instance, causing deleteAll() and other operations to affect data across namespaces.

Solution

Enforce namespace isolation at the plugin layer by routing each MethodChannel call to a dedicated FlutterSecureStorage instance per sharedPreferencesName. This ensures operations on namespace B never affect namespace A.

Implementation:

• Plugin maintains a Map<String, FlutterSecureStorage> keyed by sharedPreferencesName
• getOrCreateStorage() retrieves or creates the correct instance per namespace
• All operations (read, write, delete, deleteAll, etc.) use the namespace-specific instance

Testing

✅ Added Android-only integration test that:

• Writes the same key to two namespaces (namespace_a, namespace_b)
• Calls deleteAll() on namespace_b
• Asserts the key in namespace_a remains intact

Breaking Changes

None

Notes

• SHARED_PREFERENCES_CONFIG_NAME remains global (stores migration/cipher metadata only). This poses a threat of possible encryption-related issues when two or more storages use different algorithms.
• Actual stored values are fully isolated per sharedPreferencesName
• Matches iOS/macOS behavior where each operation uses namespace-specific parameters

[mateusz-pietras]

Opened for initial code review as it directly solves the mentioned issue #1023, however, I will be working on introducing the same type of namespace/storage isolation for the SHARED_PREFERENCES_CONFIG_NAME. Meanwhile I would appreciate any suggestions regarding the presented code and the config isolation.

[mateusz-pietras]

Important compatibility note (Android)

On some existing installs, upgrading to this fix can make previously-stored values “disappear” even when the app passes the same sharedPreferencesName.

Why this can happen

Issue #1023 is caused by the Android plugin reusing a single FlutterSecureStorage instance across namespaces and caching the first-initialized SharedPreferences. In practice, this could cause values written for namespace B to be physically persisted into namespace A’s SharedPreferences file (or the default FlutterSecureStorage prefs), depending on initialization order and app lifecycle.

After this PR, reads/writes are correctly bound to the requested namespace. If legacy data was accidentally stored under a different prefs file due to the bug, the upgraded version will not find it in the “correct” namespace anymore (because it never lived there).

In other words: this PR fixes the bug, but it also removes accidental cross-namespace behavior some apps may have relied on unknowingly. Apps that previously experienced namespace mixing might observe missing values after upgrade.

Suggested solution (introduce a new field; deprecate sharedPreferencesName)

To provide a clean, deterministic upgrade path while keeping strong isolation semantics, I suggest introducing a new Android option that becomes the canonical “namespace identifier”, and deprecating the existing sharedPreferencesName field.

Proposed API direction

• New field (name TBD), e.g. storageNamespace / namespace / storageId
• Deprecated field: sharedPreferencesName

Proposed behavior

• The plugin will treat the new field as the source of truth for all Android namespacing:

  • The data SharedPreferences file name
  • Any config/marker preference stores used for algorithm/migration metadata

• For backwards compatibility during the deprecation window:

  • If the new field is not provided, the plugin falls back to the deprecated sharedPreferencesName (current behavior).
  • If both are provided, the new field wins (and the old one is ignored, with a log/warn).

Migration expectations

This does not magically recover data that was physically written to the wrong prefs file due to the legacy bug (because that location was non-deterministic). However, introducing the new field provides:

• a clearer contract going forward (“this is the stable namespace identifier”),
• and a controlled breaking-change path where apps can move to the new field and avoid relying on low-level implementation details (SharedPreferences file naming).

Deprecation plan

• Mark sharedPreferencesName as deprecated in docs (and API annotations where possible).
• Document the upgrade path: “replace sharedPreferencesName with <newField>”.
• Keep the fallback behavior for at least one major/minor cycle before removing sharedPreferencesName.

[westracer]

SHARED_PREFERENCES_CONFIG_NAME remains global (stores migration/cipher metadata only). This poses a threat of possible encryption-related issues when two or more storages use different algorithms

This is actually a big problem that needs to be solved as well, and not just a "note". It's especially relevant since there's now a migration mechanism in v10 from AES/CBC to another cipher. If you have 2 storages with different algorithms/keys, they will conflict because they are using the same key alias in KeyStore, and all data will be lost as a result. Different keys should be used for different storages

[mateusz-pietras]

SHARED_PREFERENCES_CONFIG_NAME remains global (stores migration/cipher metadata only). This poses a threat of possible encryption-related issues when two or more storages use different algorithms

This is actually a big problem that needs to be solved as well, and not just a "note". It's especially relevant since there's now a migration mechanism in v10 from AES/CBC to another cipher. If you have 2 storages with different algorithms/keys, they will conflict because they are using the same key alias in KeyStore, and all data will be lost as a result. Different keys should be used for different storages

Yes, that is true. I introduced a NamespacedConfigSource concept in the most recent commit, that allows to use separate algorithms per namespaced storage. That should solve the issue.

[westracer]

Yes, that is true. I introduced a NamespacedConfigSource concept in the most recent commit, that allows to use separate algorithms per namespaced storage. That should solve the issue.

That doesn't solve the issue fully because the key alias is the same for all algorithms/storages, which means the same key is used for all instances:

context.getPackageName() + ".FlutterSecureStoragePluginKey"

but obviously, keys should be separated as well for different algorithms/storages; otherwise, they will conflict with each other. Correct me if I'm wrong

[juliansteenbakker]

Hi all, sorry for the delay. I think a valid issue is raised here. I think the best solution would indeed be to migrate to storageNamespace, which will set all names to the given identifier, giving full seperation across the codebase. However, i'm keen on breaking changes so i want to make it as easy as possible for the user to migrate to this.

The best would be to introduce this change in v11, as v11 will remove the older encryption methods, as well as the migration tool. This way we could also alter SHARED_PREFERENCES_CONFIG_NAME, with a new migration tool if needed so users don't lose data.