{"id":46576609,"url":"https://github.com/microclub-usthb/m-security","last_synced_at":"2026-04-05T05:00:52.090Z","repository":{"id":342633079,"uuid":"1155402769","full_name":"MicroClub-USTHB/M-Security","owner":"MicroClub-USTHB","description":"A native Rust security SDK for Flutter offering high-performance cryptography, streaming encryption with compression, an encrypted virtual file system (EVFS), and secure memory management via Flutter Rust Bridge.","archived":false,"fork":false,"pushed_at":"2026-04-01T18:07:37.000Z","size":1073,"stargazers_count":56,"open_issues_count":9,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-02T05:19:54.995Z","etag":null,"topics":["dart","rust","sdk","security"],"latest_commit_sha":null,"homepage":"https://pub.dev/packages/m_security","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MicroClub-USTHB.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-11T13:27:59.000Z","updated_at":"2026-03-28T17:37:27.000Z","dependencies_parsed_at":null,"dependency_job_id":"09119685-6ac1-4932-85e0-2c0982e4df28","html_url":"https://github.com/MicroClub-USTHB/M-Security","commit_stats":null,"previous_names":["microclub-usthb/m-security"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/MicroClub-USTHB/M-Security","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MicroClub-USTHB%2FM-Security","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MicroClub-USTHB%2FM-Security/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MicroClub-USTHB%2FM-Security/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MicroClub-USTHB%2FM-Security/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MicroClub-USTHB","download_url":"https://codeload.github.com/MicroClub-USTHB/M-Security/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MicroClub-USTHB%2FM-Security/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31424931,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T02:22:46.605Z","status":"ssl_error","status_checked_at":"2026-04-05T02:22:33.263Z","response_time":75,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dart","rust","sdk","security"],"created_at":"2026-03-07T10:03:09.762Z","updated_at":"2026-04-05T05:00:52.084Z","avatar_url":"https://github.com/MicroClub-USTHB.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"assets/m-security.png\" alt=\"M-Security Logo\" width=\"200\"\u003e\n\u003c/div\u003e\n\u003cbr /\u003e\n\n# M-Security\n\n[![pub package](https://img.shields.io/pub/v/m_security.svg)](https://pub.dev/packages/m_security)\n[![pub points](https://img.shields.io/pub/points/m_security.svg?color=2E8B57)](https://pub.dev/packages/m_security/score)\n[![pub downloads](https://img.shields.io/pub/dm/m_security.svg?color=blue)](https://pub.dev/packages/m_security/score)\n[![Platforms](https://img.shields.io/badge/Platforms-Android%20|%20iOS%20|%20macOS%20|%20Linux%20|%20Windows-blueviolet)](#platform-support)\n[![CI](https://github.com/MicroClub-USTHB/M-Security/actions/workflows/ci.yml/badge.svg)](https://github.com/MicroClub-USTHB/M-Security/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n\nA native Rust security SDK for Flutter, providing high-performance cryptographic services, streaming encryption with compression, an encrypted virtual file system (EVFS), and secure memory management. All operations run in Rust through [Flutter Rust Bridge](https://cjycode.com/flutter_rust_bridge/). No Dart-level crypto, no platform channels.\n\nBuilt and maintained by the **Dev Department** of [MicroClub](https://github.com/MicroClub-USTHB), the computer science club at USTHB (University of Science and Technology Houari Boumediene, Algiers).\n\n## Features\n\n| Category                 | Algorithm / Feature    | Highlights                                                  |\n| ------------------------ | ---------------------- | ----------------------------------------------------------- |\n| **AEAD Encryption**      | AES-256-GCM            | Industry-standard, hardware-accelerated on most CPUs        |\n|                          | ChaCha20-Poly1305      | Optimized for mobile (no AES hardware needed)               |\n| **Streaming Encryption** | AES-256-GCM / ChaCha20 | Chunk-based processing with progress callbacks              |\n| **Compression**          | Zstd, Brotli           | Configurable levels, integrated into streaming and EVFS     |\n| **Hashing**              | BLAKE3                 | Ultra-fast, one-shot and streaming                          |\n|                          | SHA-3-256 (Keccak)     | NIST-standard, one-shot and streaming                       |\n| **Password Hashing**     | Argon2id               | PHC winner, Mobile and Desktop presets                      |\n| **Key Derivation**       | HKDF-SHA256            | RFC 5869, extract-then-expand with domain separation        |\n| **Encrypted VFS (EVFS)** | `.vault` container     | Named segments, WAL recovery, shadow index, secure deletion |\n| **Key Management**       | Rotation, export/import | Atomic re-encryption, `.mvex` portable archives             |\n| **Zero-Copy I/O**        | mmap + DCO codec       | Memory-mapped vault reads, zero-copy Rust-to-Dart transfers |\n\n**Security by design:**\n\n- All key material lives in Rust behind opaque handles; raw keys never cross FFI\n- Automatic memory zeroization on drop (`ZeroizeOnDrop`)\n- Nonces generated internally via OS-level CSPRNG (`OsRng`)\n- AEAD tag verification prevents silent decryption of tampered data\n- `panic = \"abort\"` in release profile, preventing undefined behavior from panics crossing FFI\n- `clippy::unwrap_used = \"deny\"`, ensuring all operations return `Result\u003cT, CryptoError\u003e`\n- Release builds strip all symbols except FRB entry points (LTO + ELF version script)\n- `mlock()` pins mmap'd ciphertext pages to prevent swap-to-disk (unix)\n\n## Installation\n\nAdd to your `pubspec.yaml`:\n\n```yaml\ndependencies:\n  m_security: ^0.3.4\n```\n\nThen run:\n\n```bash\nflutter pub get\n```\n\n### Prerequisites\n\nM-Security compiles Rust code during the Flutter build. You need:\n\n- **Rust toolchain** (stable):\n\n  ```bash\n  curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh\n  ```\n\n- **Platform-specific tools:**\n\n  | Platform    | Requirements                                                  |\n  | ----------- | ------------------------------------------------------------- |\n  | Android     | Android NDK (r27c recommended)                                |\n  | iOS / macOS | Xcode with command line tools                                 |\n  | Linux       | `clang`, `cmake`, `ninja-build`, `pkg-config`, `libgtk-3-dev` |\n  | Windows     | Visual Studio Build Tools + LLVM                              |\n\nRust compilation is handled automatically by [Cargokit](https://github.com/nickhudson/cargokit) during `flutter build` / `flutter run`.\n\n## Getting Started\n\nInitialize the Rust library once at app startup:\n\n```dart\nimport 'package:m_security/m_security.dart';\n\nFuture\u003cvoid\u003e main() async {\n  WidgetsFlutterBinding.ensureInitialized();\n  await RustLib.init();\n  runApp(const MyApp());\n}\n```\n\n## Usage\n\nAll examples below use a single import:\n\n```dart\nimport 'package:m_security/m_security.dart';\n```\n\n### AES-256-GCM Encryption\n\n```dart\nfinal aes = AesGcmService();\nawait aes.initWithRandomKey();\n\n// Encrypt and decrypt raw bytes\nfinal encrypted = await aes.encrypt(plaintext);\nfinal decrypted = await aes.decrypt(encrypted);\n\n// Convenience: encrypt and decrypt UTF-8 strings\nfinal ciphertext = await aes.encryptString('sensitive data');\nfinal original = await aes.decryptString(ciphertext);\n```\n\n### ChaCha20-Poly1305 Encryption\n\n```dart\nfinal chacha = Chacha20Service();\nawait chacha.initWithRandomKey();\n\n// Basic encrypt and decrypt\nfinal encrypted = await chacha.encryptString('sensitive data');\nfinal original = await chacha.decryptString(encrypted);\n\n// With Associated Authenticated Data (AAD)\nfinal ct = await chacha.encryptString('payload', aad: 'metadata');\nfinal pt = await chacha.decryptString(ct, aad: 'metadata');\n```\n\nBoth ciphers output `nonce || ciphertext || tag`. Nonces (12 bytes) are auto-generated and authentication tags (16 bytes) are appended automatically.\n\n### Argon2id Password Hashing\n\n```dart\n// Hash a password (returns PHC-format string)\nfinal hash = await argon2IdHash(password: 'hunter2');\n\n// Verify a password against a hash\nawait argon2IdVerify(phcHash: hash, password: 'hunter2');\n\n// Explicit preset selection\nfinal hash = await argon2IdHash(\n  password: 'hunter2',\n  preset: Argon2Preset.desktop,  // 256 MiB, t=4, p=8\n);\n```\n\nThe default preset is selected at compile time: `Argon2Preset.mobile` (64 MiB, t=3, p=4) unless built with `-DIS_DESKTOP=true`.\n\n### HKDF-SHA256 Key Derivation\n\n```dart\n// Derive a key from input key material\nfinal key = MHKDF.derive(\n  ikm: masterKeyBytes,\n  salt: saltBytes,          // optional\n  info: Uint8List.fromList('encryption-key'.codeUnits),\n  outputLen: 32,\n);\n\n// Domain separation: same master key, different derived keys\nfinal encKey = MHKDF.derive(ikm: master, info: utf8.encode('enc'), outputLen: 32);\nfinal macKey = MHKDF.derive(ikm: master, info: utf8.encode('mac'), outputLen: 32);\n\n// Two-phase: extract PRK, then expand\nfinal prk = MHKDF.extract(ikm: masterKeyBytes, salt: saltBytes);\nfinal derived = await MHKDF.expand(prk: prk, info: infoBytes, outputLen: 32);\n```\n\nOutput length must be between 1 and 8160 bytes (RFC 5869 limit for SHA-256: 255 \\* 32).\n\n### Streaming Encryption\n\n```dart\nimport 'package:m_security/src/rust/api/streaming.dart';\n\n// Encrypt a file in chunks with progress\nfinal encrypted = await streamEncrypt(\n  plaintext: largeData,\n  algorithm: StreamAlgorithm.aes256Gcm,\n  compression: CompressionAlgorithm.zstd,\n  compressionLevel: 3,\n  onProgress: (progress) =\u003e print('${(progress * 100).toInt()}%'),\n);\n\n// Decrypt\nfinal decrypted = await streamDecrypt(\n  ciphertext: encrypted,\n  algorithm: StreamAlgorithm.aes256Gcm,\n  compression: CompressionAlgorithm.zstd,\n);\n```\n\n### Encrypted Virtual File System (EVFS)\n\n```dart\nimport 'package:m_security/m_security.dart';\n\n// Create a 10 MB vault with AES-256-GCM\nfinal handle = await VaultService.create(\n  path: '/path/to/my.vault',\n  key: key,\n  algorithm: 'aes-256-gcm',\n  capacityBytes: 10 * 1024 * 1024,\n);\n\n// Write a segment (with optional compression)\nawait VaultService.write(\n  handle: handle,\n  name: 'secret.txt',\n  data: utf8.encode('confidential'),\n  compression: CompressionConfig(algorithm: CompressionAlgorithm.zstd),\n);\n\n// Read it back (decompression is automatic)\nfinal data = await VaultService.read(handle: handle, name: 'secret.txt');\n\n// List segments, delete, close\nfinal segments = await VaultService.list(handle: handle);\nawait VaultService.delete(handle: handle, name: 'secret.txt');\nawait VaultService.close(handle: handle);\n```\n\n#### Key Management\n\n```dart\n// Rotate master key (re-encrypts all segments atomically)\nfinal newHandle = await VaultService.rotateKey(handle: handle, newKey: newKey);\n// Old handle is invalidated; use newHandle from here\n\n// Export vault to portable encrypted archive\nawait VaultService.export(\n  handle: handle,\n  wrappingKey: wrappingKey,\n  exportPath: '/path/to/backup.mvex',\n);\n\n// Import vault from archive (creates new vault with fresh key)\nfinal imported = await VaultService.importVault(\n  archivePath: '/path/to/backup.mvex',\n  wrappingKey: wrappingKey,\n  destPath: '/path/to/restored.vault',\n  newMasterKey: localKey,\n  algorithm: 'aes-256-gcm',\n  capacityBytes: 10 * 1024 * 1024,\n);\n```\n\n#### Vault Maintenance\n\n```dart\n// Health check (read-only, no I/O)\nfinal health = await VaultService.health(handle: handle);\nprint('Consistent: ${health.isConsistent}');\nprint('Fragmentation: ${(health.fragmentationRatio * 100).toStringAsFixed(1)}%');\n\n// Defragment — compact segments, coalesce free space (WAL-protected)\nfinal result = await VaultService.defragment(handle: handle);\nprint('Moved ${result.segmentsMoved} segments, reclaimed ${result.bytesReclaimed} bytes');\n\n// Resize vault capacity (grow or shrink)\nawait VaultService.resize(handle: handle, newCapacityBytes: 20 * 1024 * 1024);\n```\n\n### BLAKE3 \u0026 SHA-3-256 Hashing\n\nFor one-shot and streaming hashing, use the lower-level FFI API directly:\n\n```dart\nimport 'package:m_security/src/rust/api/hashing.dart';\n\n// One-shot hashing (32-byte output)\nfinal blake3Digest = await blake3Hash(data: inputBytes);\nfinal sha3Digest = await sha3Hash(data: inputBytes);\n\n// Streaming: process data in chunks\nfinal hasher = createBlake3();  // or createSha3()\nawait hasherUpdate(handle: hasher, data: chunk1);\nawait hasherUpdate(handle: hasher, data: chunk2);\nfinal digest = await hasherFinalize(handle: hasher);\n\n// Reset and reuse\nawait hasherReset(handle: hasher);\n```\n\n## Architecture\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"assets/architecture.svg\" alt=\"M-Security Architecture\" width=\"600\"\u003e\n\u003c/div\u003e\n\n**Key design decisions:**\n\n- **Opaque handles.** `CipherHandle` and `HasherHandle` are `#[frb(opaque)]`. Dart holds a pointer, never raw key bytes.\n- **Trait objects.** `Box\u003cdyn Encryption\u003e` and `Box\u003cdyn Hasher\u003e` with `Send + Sync + 'static` enable runtime algorithm selection.\n- **SecretBuffer.** All key material is wrapped in `SecretBuffer` which derives `ZeroizeOnDrop`. Memory is zeroed when handles are dropped.\n- **No panics across FFI.** `panic = \"abort\"` in release profile. All FFI functions return `Result\u003cT, CryptoError\u003e`.\n- **Format headers.** Encrypted data includes a `MSEC` magic header with version and algorithm identifiers for forward compatibility.\n\n## Rust API Reference\n\n### Encryption (`CipherHandle`)\n\n```\ncreate_aes256_gcm(key: Vec\u003cu8\u003e)              -\u003e Result\u003cCipherHandle\u003e\ncreate_chacha20_poly1305(key: Vec\u003cu8\u003e)       -\u003e Result\u003cCipherHandle\u003e\nencrypt(cipher, plaintext, aad)              -\u003e Result\u003cVec\u003cu8\u003e\u003e\ndecrypt(cipher, ciphertext, aad)             -\u003e Result\u003cVec\u003cu8\u003e\u003e\ngenerate_aes256_gcm_key()                    -\u003e Result\u003cVec\u003cu8\u003e\u003e\ngenerate_chacha20_poly1305_key()             -\u003e Result\u003cVec\u003cu8\u003e\u003e\nencryption_algorithm_id(cipher)              -\u003e String\n```\n\n### Hashing (`HasherHandle`)\n\n```\nblake3_hash(data)           -\u003e Vec\u003cu8\u003e          (one-shot, 32 bytes)\nsha3_hash(data)             -\u003e Vec\u003cu8\u003e          (one-shot, 32 bytes)\ncreate_blake3()             -\u003e HasherHandle      (streaming)\ncreate_sha3()               -\u003e HasherHandle      (streaming)\nhasher_update(handle, data) -\u003e Result\u003c()\u003e\nhasher_reset(handle)        -\u003e Result\u003c()\u003e\nhasher_finalize(handle)     -\u003e Result\u003cVec\u003cu8\u003e\u003e\nhasher_algorithm_id(handle) -\u003e Result\u003cString\u003e\n```\n\n### Password Hashing (Argon2id)\n\n```\nargon2id_hash(password, preset)                     -\u003e Result\u003cString\u003e  (PHC)\nargon2id_hash_with_salt(password, salt, preset)     -\u003e Result\u003cString\u003e  (PHC)\nargon2id_verify(phc_hash, password)                 -\u003e Result\u003c()\u003e\n```\n\nPresets: `Mobile` (64 MiB, t=3, p=4) | `Desktop` (256 MiB, t=4, p=8)\n\n### Key Derivation (HKDF-SHA256)\n\n```\nhkdf_derive(ikm, salt?, info, output_len)   -\u003e Result\u003cVec\u003cu8\u003e\u003e   (one-shot)\nhkdf_extract(ikm, salt?)                    -\u003e Result\u003cVec\u003cu8\u003e\u003e   (PRK)\nhkdf_expand(prk, info, output_len)          -\u003e Result\u003cVec\u003cu8\u003e\u003e\n```\n\n## Platform Support\n\n| Platform | Target                                             | Status    |\n| -------- | -------------------------------------------------- | --------- |\n| Android  | `aarch64-linux-android`, `armv7-linux-androideabi` | CI-tested |\n| iOS      | `aarch64-apple-ios`, `aarch64-apple-ios-sim`       | CI-tested |\n| macOS    | `aarch64-apple-darwin`, `x86_64-apple-darwin`      | Supported |\n| Linux    | `x86_64-unknown-linux-gnu`                         | CI-tested |\n| Windows  | `x86_64-pc-windows-msvc`                           | Supported |\n\n## Testing\n\n**Rust unit tests** (331 tests including EVFS streaming and defrag):\n\n```bash\ncd rust \u0026\u0026 cargo test\n```\n\n**Dart integration tests** (76 tests across all features, requires a running device/simulator):\n\n```bash\ncd example\nflutter test integration_test/\n```\n\n## Tech Stack\n\n| Component           | Version |\n| ------------------- | ------- |\n| Rust                | stable  |\n| Flutter Rust Bridge | 2.11.1  |\n| Dart SDK            | ^3.10.8 |\n| Flutter SDK         | \u003e=3.3.0 |\n\n**Rust crates:** `aes-gcm` 0.10, `chacha20poly1305` 0.10, `blake3` 1.8, `sha3` 0.10, `argon2` 0.5, `hkdf` 0.12, `zstd` 0.13, `brotli` 7.0, `zeroize` 1.8, `memmap2` 0.9\n\n## Roadmap\n\n| Feature                                  | Description                                                                         | Status  |\n| ---------------------------------------- | ----------------------------------------------------------------------------------- | ------- |\n| **Streaming encryption**                 | Process large files in chunks with progress callbacks                               | v0.3.0  |\n| **Compression pipeline**                 | Zstd/Brotli compression integrated into streaming and EVFS                          | v0.3.0  |\n| **Encrypted Virtual File System (EVFS)** | `.vault` container with named segments, WAL recovery, shadow index, secure deletion | v0.3.0  |\n| **EVFS v2: Defrag \u0026 resize**             | Online defragmentation, vault resizing, health diagnostics                          | v0.3.1  |\n| **EVFS v2: Streaming I/O**               | Constant-memory streaming reads/writes, per-chunk AEAD, progress callbacks          | v0.3.2  |\n| **Zero-copy FFI optimization**           | mmap vault reads, DCO codec, release profile hardening, symbol stripping            | v0.3.3  |\n| **EVFS v2: Key management**              | Key rotation, vault export/import (`.mvex` archives), Dart wrappers                 | v0.3.4  |\n| **Stealth storage**                      | Ephemeral secrets in Rust-managed memory with derived-path obfuscation              | Planned |\n| **Hardware key wrap**                    | Master key in Secure Enclave (iOS) / KeyStore (Android) with biometric unlock       | Planned |\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, coding standards, and PR workflow.\n\n## License\n\nMIT. See [LICENSE](LICENSE) for details.\n\nCopyright (c) 2025 [MicroClub-USTHB](https://github.com/MicroClub-USTHB)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicroclub-usthb%2Fm-security","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmicroclub-usthb%2Fm-security","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicroclub-usthb%2Fm-security/lists"}