flutter_secure_storage: Secure Key-Value Pairs

WHY IT EXISTS Apps often need to persist sensitive information like auth tokens or user credentials after closing. Storing this in plain text using a simple key-value store like SharedPreferences is a major security risk. flutter_secure_storage provides a simple, cross-platform API for storing this data securely, encrypted at rest.

THE MENTAL MODEL Think of flutter_secure_storage as a secure, persistent Map<String, String>. It has a familiar API (read, write, delete), but under the hood, it handles the complex, platform-specific work of encrypting data and storing it in the most secure location available on the device, like the iOS Keychain or Android's encrypted storage.

HOW IT WORKS The library acts as a bridge to native secure storage mechanisms. On iOS and macOS, it uses the battle-tested Keychain services. On Android, it implements a custom solution using RSA OAEP for key encryption and AES-GCM for data encryption, a strong, modern standard. For other platforms like Web, Windows, and Linux, it uses their respective secure storage solutions. The API is asynchronous because these operations involve disk I/O and cryptographic processing.

WHEN TO USE IT Use it for small, sensitive pieces of data that must persist between app sessions. Canonical examples include user authentication tokens (JWTs, OAuth tokens), API keys, and private keys for encryption. It's also the right choice when you need to add an optional layer of biometric protection before accessing a stored secret.

WHEN NOT TO USE IT Do not use it as a general-purpose database or for storing large amounts of data. The encryption and decryption overhead on every read/write makes it significantly slower than non-secure alternatives like SharedPreferences or a local database. It is not for storing general application state, user preferences, or cached data. On the web, it only works over HTTPS or on localhost.

ONE CANONICAL EXAMPLE A mobile app needs to store a user's JWT after they log in so they remain authenticated when they reopen the app. Instead of saving it to a plain text file, the developer uses flutter_secure_storage. They call await storage.write(key: 'jwt_token', value: userToken). When the app starts next, it calls await storage.read(key: 'jwt_token') to retrieve the token and authenticate API calls, ensuring the token was never stored in an unencrypted state on the device.