littlefish_flutter_secure_storage

A Flutter implementation of the LittleFish SecureStorageClient abstraction, built on top of flutter_secure_storage.

This package provides a clean, domain-safe, and platform-aware way to store sensitive data (tokens, credentials, secrets) in secure storage, while remaining consistent with LittleFish’s core architecture and abstractions.

⸻

✨ Features • 🔐 Secure key–value storage using flutter_secure_storage • 🧱 Implements SecureStorageClient from littlefish_core • 🔑 Optional value-level encryption via ValueEncryptor • 📱 Platform-specific configuration: • Android: Encrypted SharedPreferences • iOS: Keychain accessibility levels • 🧭 Key namespacing via configurable prefixes • 🧪 Strongly typed settings with validation • 🧰 JSON convenience helpers (writeJson, readJson) • 🧨 Rich, domain-specific error handling

⸻

📦 Installation

Add the dependency to your pubspec.yaml:

dependencies: littlefish_flutter_secure_storage: path: ../littlefish_flutter_secure_storage

This package depends on: • flutter_secure_storage • littlefish_core

⸻

🧠 Architectural Intent

This package is an infrastructure-layer implementation of the domain abstraction:

SecureStorageClient

It is designed to: • Keep Flutter- and platform-specific concerns out of the domain • Allow swapping implementations without changing business logic • Support future secure storage backends or encryption strategies

⸻

⚙️ Configuration

FlutterSecureStorageSettings

const settings = FlutterSecureStorageSettings( keyPrefix: 'auth_', encrypt: true, encryptedSharedPreferences: true, iosAccessibility: KeychainAccessibility.first_unlock, );

Settings Breakdown

Setting Description keyPrefix Prefix applied to all keys (namespacing) encrypt Indicates whether values are expected to be encrypted encryptedSharedPreferences Android-only; must be true if encrypt is enabled iosAccessibility iOS Keychain accessibility level

A default configuration is provided:

FlutterSecureStorageSettings.defaults

⸻

🚀 Usage

Initialization

final secureStorage = LittlefishFlutterSecureStorage( encryptor: myEncryptor, // optional );

await secureStorage.initialize( settings: FlutterSecureStorageSettings.defaults, );

⚠️ If settings.encrypt == true but Android encrypted shared preferences are disabled, initialization will fail with a configuration exception.

⸻

Writing & Reading Values

await secureStorage.write( key: 'access_token', value: token, );

final token = await secureStorage.read( key: 'access_token', );

⸻

Deleting Values

await secureStorage.delete(key: 'access_token'); await secureStorage.deleteAll();

⸻

JSON Helpers

await secureStorage.writeJson( 'user', {'id': 1, 'name': 'Michael'}, );

final user = await secureStorage.readJson('user');

⸻

🔐 Value Encryption

This package does not enforce a specific encryption algorithm.

Instead, it supports value-level encryption via the ValueEncryptor abstraction:

abstract class ValueEncryptor { String encrypt(String plaintext); String decrypt(String ciphertext); }

Example

final secureStorage = LittlefishFlutterSecureStorage( encryptor: AesValueEncryptor(), );

If no encryptor is provided: • Values are stored as-is • Platform-level security (Keychain / EncryptedSharedPreferences) still applies

⸻

🧨 Error Handling

All operations are wrapped in domain-specific exceptions, including: • SecureStorageConfigurationException • SecureStorageWriteException • SecureStorageReadException • SecureStorageDeleteException

Each error includes: • A stable error code • A human-readable message • The original cause and stack trace

This makes the package safe to use in: • Analytics • Logging • User-facing error flows

⸻

🧱 What This Is (and Isn’t)

✅ Intended For • Auth tokens • API secrets • Credentials • Encryption keys

❌ Not Intended For • General app data • Caching • Large or structured datasets

⸻

🔄 Extensibility

This implementation fits cleanly into a broader ecosystem: • Swap in a different SecureStorageClient • Reuse the same ValueEncryptor • Add platform-specific policies without touching domain code

⸻

🧩 Related Packages • littlefish_core • flutter_secure_storage

⸻

📄 License

Internal LittleFish package – not intended for public distribution.

⸻

If you want, I can also: • Add usage examples with DI (get_it) • Review this for pub.dev readiness • Write a security & threat model section • Align the README tone with the rest of your LittleFish packages