vault_storage 1.2.0

vault_storage: ^1.2.0 copied to clipboard

New Features #

• feat: Automatic file downloads on web platforms - getSecureFile() and getNormalFile() now automatically trigger downloads in web browsers while maintaining native platform behavior
• feat: Custom download filenames - Added optional downloadFileName parameter to file retrieval methods for custom web download names
• feat: Smart filename generation - Automatically generates appropriate filenames using stored file extensions (e.g., document.pdf, image.jpg)
• feat: MIME type detection - Automatic MIME type detection for 15+ common file formats ensures proper browser handling

Technical Improvements #

• feat: Modern web standards - Migrated from deprecated dart:html to modern package:web APIs for future WebAssembly (Wasm) compatibility
• feat: Enhanced metadata storage - File extensions are now stored in metadata for both secure and normal files
• feat: Conditional imports optimization - Updated to use dart.library.js_interop for better web/native platform detection

Documentation Updates #

• docs: Enhanced README with web download examples - Added comprehensive examples showing platform-specific behavior
• docs: Platform behavior comparison table - Clear documentation of differences between web and native platforms
• docs: MIME type support documentation - Listed all supported file types and their automatic MIME type mappings

🔄 Backward Compatibility #

• No breaking changes - All existing code continues to work without modifications
• Optional parameters - New features use optional parameters to maintain API compatibility
• Same return types - Methods still return Either<StorageError, Uint8List> as before

Web Platform Enhancements #

• Web downloads: Files automatically download when retrieved on web platforms
• Smart filenames: Uses original file extensions for meaningful download names
• MIME type support: PDF, images, documents, audio, video, and more
• Custom naming: Optional custom filenames for downloads

Dependencies #

• Added: web: ^1.1.1 for modern web API access

Bug Fixes #

• fix: Android compilation issues - Fixed Android build failures by migrating from unmaintained cryptography package to actively maintained cryptography_plus
• fix: AGP 8.x compatibility - Resolved Android Gradle Plugin 8.x compatibility issues that prevented compilation on newer Android projects

Dependency Updates #

• feat: Replace cryptography with cryptography_plus - Migrated from cryptography: ^2.7.0 to cryptography_plus: ^2.7.1 to ensure ongoing maintenance and Android compatibility
• feat: Upgrade flutter_secure_storage - Updated from ^9.2.4 to ^10.0.0-beta.4 for latest security improvements and bug fixes

Migration Notes #

• Automatic migration: No code changes required - the package handles the cryptography library migration internally
• Android compatibility: Projects that previously failed to compile on Android with AGP 8.x will now work correctly
• Breaking changes: None for end users - all public APIs remain the same

Documentation Improvements #

• docs: Fix incorrect parameter name in README.md - Corrected metadata: to fileMetadata: in getSecureFile method example
• docs: Fix version inconsistencies - Updated all version references from ^0.1.1 to ^1.0.0 to match current package version
• docs: Fix Riverpod integration example - Corrected error handling in main.dart to use try-catch instead of incorrect .fold() usage
• docs: Fix syntax errors - Removed duplicate closing braces and fixed code formatting issues

Technical Fixes #

• fix: Correct API usage examples - All code examples now use the correct method signatures and parameter names
• fix: Improve error handling patterns - Better distinction between functional error handling (Either) and exception-based error handling (try-catch)

Breaking Changes #

• BREAKING: Remove built-in Riverpod provider - The package no longer includes a built-in Riverpod provider to remain framework-agnostic
• BREAKING: Hide implementation details - Use VaultStorage.create() factory method instead
• feat: Framework-agnostic design - Users can now integrate with any state management solution or use the service directly

New Features #

• feat: Add VaultStorage.create() factory method - Clean API that returns IVaultStorage interface, hiding implementation details
• feat: Improved API design - Only the interface (IVaultStorage) is exposed to users, making the API cleaner and less confusing

Documentation Improvements #

• docs: Add comprehensive state management integration examples - Includes examples for Riverpod and direct usage
• docs: Update initialisation examples - Show how to initialise the service without Riverpod dependency
• docs: Clarify framework-agnostic approach - Emphasise that the package works with any state management solution
• docs: Update all examples to use factory method - Consistent API usage throughout documentation

Migration Guide #

From built-in Riverpod provider: If you were using the built-in vaultStorageProvider, you can easily recreate it in your own project:

1. Add Riverpod dependencies to your pubspec.yaml
2. Create your own provider file following the examples in the README
3. Update your initialisation code to use your custom provider

From VaultStorageImpl(): Replace direct instantiation with the factory method:

// Before
final storage = VaultStorageImpl();

// After
final storage = VaultStorage.create();

This change makes the package more flexible, reduces its dependency footprint, and provides a cleaner API.

• refactor: Remove export of unused storage_keys constant from vault_storage.dart
• chore: Update build_runner dependency to version 2.5.4 in pubspec.yaml
• chore: Update _fe_analyzer_shared and analyzer versions in pubspec.lock
• test: Refactor error handling tests to use async/await for improved readability

Major Features #

• feat: Add support for normal file storage - Complete implementation with save, retrieve, and delete functionalities
• feat: Add JsonSafe utility - Safe JSON encoding and decoding with comprehensive error handling
• feat: Enhance storage functionality - New task execution system with improved error handling architecture

Core Improvements #

• feat: Add safe JSON encoding and decoding extensions - Improved error handling for JSON operations
• feat: Implement normal file storage - Full file storage capabilities with proper error handling
• feat: Improve error handling during storage initialisation - Detailed error display and better user feedback

Testing & Quality #

• test: Add comprehensive unit tests for VaultStorage service lifecycle - Complete lifecycle management testing
• test: Add TaskExecutor mock for testing - Enhanced testing capabilities for task execution logic
• test: Implement comprehensive StorageError class tests - Ensures proper error handling across the package
• test: Add tests for FileOperations and Encryption Helpers - Validates core functionality with thorough coverage
• test: Update VaultStorageImpl tests - Utilise new extensions for JSON operations
• refactor: Remove outdated test files - Streamlined test suite by removing vault_storage_impl_test.dart
• refactor: Consolidate storage keys tests - Improved test organisation

Documentation & Examples #

• docs: Add comprehensive use cases section - Healthcare, financial, enterprise, and consumer app examples
• docs: Add production use disclaimers - Important security and legal considerations for production apps
• docs: Add platform setup requirements - Detailed setup instructions for all supported platforms
• docs: Enhance troubleshooting section - Common issues and solutions for initialisation problems
• example: Improve error handling in example app - Better error display and recovery mechanisms

Security & Compliance #

• security: Add production use disclaimers - Clear security limitations and audit requirements
• platform: Add macOS entitlements documentation - Required keychain access setup for macOS apps

• refactor: Rename storageService to vaultStorage for consistency in README and tests
• chore: Update README for web compatibility and usage improvements
• docs: Clarify Riverpod dev version requirement and that generated files are included
• docs: Improve code examples and error handling documentation
• docs: Add comprehensive usage examples for both key-value and secure file storage

• fix: Update conditional imports for web compatibility in vault_storage_impl.dart, from dart.library.html to dart.library.js_interop

• Added web compatibility for vault_storage package.
• Enhanced storage capabilities:
  • Added secure file storage with new Hive box.
  • Updated BoxType enum to support secure file storage.
  • Implemented platform-specific file storage handling.
• Improved error handling:
  • Added disposal error handling to IVaultStorage interface.
  • Enhanced error handling throughout the package.
• Added example project with pubspec.yaml demonstrating package usage.
• Code improvements:
  • Better formatting and code consistency.
  • Cleaned up unused code in test files.
  • Refactored implementation for better maintainability.

• Initial release of the vault_storage package.
• Provides secure key-value and file storage using Hive and flutter_secure_storage.
• Features include:
  • Dual storage model for key-value pairs and file blobs.
  • AES-GCM encryption for all sensitive data.
  • Cryptographic operations offloaded to background isolates.
  • Type-safe error handling with fpdart.
  • Riverpod provider for easy dependency injection.