Merge pull request #119 from MicroClub-USTHB/78-evfs-key-management

EVFS: key rotation, vault export/import, and Dart wrappers

Author: Adel-Ayoub

.github/workflows/ci.yml

@@ -41,7 +41,7 @@ jobs:
         with:
           channel: stable
       - uses: dtolnay/rust-toolchain@stable
-      - run: cargo install flutter_rust_bridge_codegen
+      - run: cargo install flutter_rust_bridge_codegen@2.11.1
       - run: flutter pub get
       - run: flutter_rust_bridge_codegen generate
       - run: dart run build_runner build --delete-conflicting-outputs
@@ -62,7 +62,7 @@ jobs:
       - uses: nttld/setup-ndk@v1
         with:
           ndk-version: r27c
-      - run: cargo install flutter_rust_bridge_codegen
+      - run: cargo install flutter_rust_bridge_codegen@2.11.1
       - run: flutter pub get
       - run: flutter_rust_bridge_codegen generate
       - run: dart run build_runner build --delete-conflicting-outputs
@@ -80,7 +80,7 @@ jobs:
       - uses: dtolnay/rust-toolchain@stable
         with:
           targets: aarch64-apple-ios,aarch64-apple-ios-sim
-      - run: cargo install flutter_rust_bridge_codegen
+      - run: cargo install flutter_rust_bridge_codegen@2.11.1
       - run: flutter pub get
       - run: flutter_rust_bridge_codegen generate
       - run: dart run build_runner build --delete-conflicting-outputs
@@ -97,7 +97,7 @@ jobs:
           channel: stable
       - uses: dtolnay/rust-toolchain@stable
       - run: sudo apt-get update && sudo apt-get install -y clang cmake ninja-build pkg-config libgtk-3-dev
-      - run: cargo install flutter_rust_bridge_codegen
+      - run: cargo install flutter_rust_bridge_codegen@2.11.1
       - run: flutter pub get
       - run: flutter_rust_bridge_codegen generate
       - run: dart run build_runner build --delete-conflicting-outputs

CHANGELOG.md

@@ -5,14 +5,35 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## Unreleased
+## v0.3.4 - 2026-04-04
 
 ### Added
 
-### Changed
+- Master key rotation via `vault_rotate_key()` — re-encrypts all vault data under a new key using atomic copy-to-new-vault + rename strategy. Crash recovery: stale `.rotating` file cleaned on `vault_open()`.
+- Vault export via `vault_export()` — produces a self-contained `.mvex` encrypted archive with BLAKE3 integrity trailer, ephemeral export key AEAD-wrapped with caller's wrapping key, and per-segment re-encryption.
+- Vault import via `vault_import()` — reads `.mvex` archive, creates new vault re-encrypted under a local master key. Validates header, unwraps export key, verifies per-segment BLAKE3 checksums and trailer integrity.
+- `ImportFailed`, `ExportFailed`, and `KeyRotationFailed` error variants in `CryptoError`.
+- Dart `VaultService.rotateKey()`, `VaultService.export()`, and `VaultService.importVault()` static methods.
+- 7 Dart integration tests for key management (rotation roundtrip, old key rejection, export-import roundtrip, wrong wrapping key, 1MB+ segment, multiple rotations, rotate-then-export-import).
+- 26 Rust tests for key management (10 rotation + 7 export + 9 import).
+- Example app Key Management section with Rotate Key, Export, and Import buttons.
+- CI workflow pinned `flutter_rust_bridge_codegen` to v2.11.1 to match runtime dependency.
+
+### Security
+
+- Old sub-keys zeroized immediately after rotation via `ZeroizeOnDrop`.
+- Export wrapping uses AAD `b"msec-export-key-wrap"` for domain separation.
+- Archive format authenticated: per-segment AAD (segment name) + BLAKE3 trailer covering all preceding bytes.
+- `vault_write` plaintext wrapped in `Zeroizing<Vec<u8>>` — guarantees zeroization on all exit paths including `encrypt_segment` failure.
+- Import hardened: `u64` to `usize` safe cast via `try_from` (32-bit overflow protection), OOM guard in `u64` arithmetic with `saturating_add`, `.lock` file cleanup in error paths, segment name validation (1-255 bytes), `segment_count` sanity bound (100K), unknown compression byte rejection.
+- Atomic rename before lock release in rotation (closes race window).
 
 ### Fixed
 
+- `unwrap()` in `archive.rs` replaced with `map_err()` for clippy compliance.
+- `from_bytes` errors remapped to `ImportFailed` at import call sites.
+- Example app lint: replaced `src/` imports with public `m_security.dart` re-exports.
+
 ## [v0.3.3](https://github.com/MicroClub-USTHB/M-Security/releases/tag/v0.3.3) - 2026-03-28
 
 ### Added

README.md

@@ -29,6 +29,7 @@ Built and maintained by the **Dev Department** of [MicroClub](https://github.com
 | **Password Hashing**     | Argon2id               | PHC winner, Mobile and Desktop presets                      |
 | **Key Derivation**       | HKDF-SHA256            | RFC 5869, extract-then-expand with domain separation        |
 | **Encrypted VFS (EVFS)** | `.vault` container     | Named segments, WAL recovery, shadow index, secure deletion |
+| **Key Management**       | Rotation, export/import | Atomic re-encryption, `.mvex` portable archives             |
 | **Zero-Copy I/O**        | mmap + DCO codec       | Memory-mapped vault reads, zero-copy Rust-to-Dart transfers |
 
 **Security by design:**
@@ -48,7 +49,7 @@ Add to your `pubspec.yaml`:
 
 ```yaml
 dependencies:
-  m_security: ^0.3.3
+  m_security: ^0.3.4
 ```
 
 Then run:
@@ -224,6 +225,31 @@ await VaultService.delete(handle: handle, name: 'secret.txt');
 await VaultService.close(handle: handle);
 ```
 
+#### Key Management
+
+```dart
+// Rotate master key (re-encrypts all segments atomically)
+final newHandle = await VaultService.rotateKey(handle: handle, newKey: newKey);
+// Old handle is invalidated; use newHandle from here
+
+// Export vault to portable encrypted archive
+await VaultService.export(
+  handle: handle,
+  wrappingKey: wrappingKey,
+  exportPath: '/path/to/backup.mvex',
+);
+
+// Import vault from archive (creates new vault with fresh key)
+final imported = await VaultService.importVault(
+  archivePath: '/path/to/backup.mvex',
+  wrappingKey: wrappingKey,
+  destPath: '/path/to/restored.vault',
+  newMasterKey: localKey,
+  algorithm: 'aes-256-gcm',
+  capacityBytes: 10 * 1024 * 1024,
+);
+```
+
 #### Vault Maintenance
 
 ```dart
@@ -366,7 +392,7 @@ flutter test integration_test/
 | **EVFS v2: Defrag & resize**             | Online defragmentation, vault resizing, health diagnostics                          | v0.3.1  |
 | **EVFS v2: Streaming I/O**               | Constant-memory streaming reads/writes, per-chunk AEAD, progress callbacks          | v0.3.2  |
 | **Zero-copy FFI optimization**           | mmap vault reads, DCO codec, release profile hardening, symbol stripping            | v0.3.3  |
-| **EVFS v2: Key rotation**                | Re-encrypt vault with new master key                                                | Planned |
+| **EVFS v2: Key management**              | Key rotation, vault export/import (`.mvex` archives), Dart wrappers                 | v0.3.4  |
 | **Stealth storage**                      | Ephemeral secrets in Rust-managed memory with derived-path obfuscation              | Planned |
 | **Hardware key wrap**                    | Master key in Secure Enclave (iOS) / KeyStore (Android) with biometric unlock       | Planned |