🛡️ MemGuard

Hybrid secure storage for Flutter with zero-leak memory protection and hardware-backed encryption.

MemGuard combines ultra-fast Rust FFI memory storage with hardware-backed platform security (Android KeyStore, iOS Keychain) to give you the best of both worlds: blazing performance for ephemeral data and military-grade protection for persistent secrets.

---

✨ Features

🚀 Dual Storage Modes

Memory Storage (Rust FFI)

• ⚡ Zero-copy direct access — no Dart VM overhead
• 🔥 Ephemeral by design — data vanishes on app close
• 🧠 Protected memory — explicit zeroing prevents leaks
• 🔐 Optional encryption — AES-256-GCM in Rust
• 🎯 Perfect for: Session tokens, API keys, temporary credentials

Device Secure Storage (Platform Channels)

• 🔒 Hardware-backed encryption — Android KeyStore (StrongBox/TEE)
• 💾 Persistent across restarts — survives app kills
• 🛡️ Zero platform channel leaks — only boolean flags transmitted
• 🗄️ Disk-backed with Rust cache — fast reads after first access
• 🎯 Perfect for: User credentials, refresh tokens, sensitive settings

🔐 Zero-Leak Architecture

┌─────────────────────────────────────────────────────────────┐
│                    YOUR DART CODE                           │
│         • Never touches sensitive data directly            │
│         • Only receives boolean status flags               │
└──────────────────┬──────────────────────────────────────────┘
                   │
                   ▼
         ┌─────────────────────┐
         │   MemGuard Plugin   │  ← You are here
         │   (Dart API Layer)  │
         └─────────┬───────────┘
                   │
         ┌─────────┴─────────┐
         ▼                   ▼
┌──────────────────┐  ┌────────────────────┐
│   Rust FFI       │  │  Platform Channel  │
│  (Memory Cache)  │  │  (Kotlin/Swift)    │
│                  │  │                    │
│ • Direct access  │  │ • KeyStore/Keychain│
│ • Zero-copy      │  │ • Encrypted files  │
│ • Protected mem  │  │ • No plaintext     │
└──────────────────┘  └────────────────────┘

Critical Design Decision:

• Memory mode: Data lives ONLY in Rust — Dart never sees plaintext
• Secure mode: Platform channels return true/false/null — Dart fetches from Rust cache
• Result: Zero attack surface in Dart VM and platform channels

---

🚀 Quick Start

Installation

dependencies:
  memguard: ^2.1.4

Basic Usage

import 'package:memguard/memguard.dart';

void main() {
  runApp(
    MemGuard(
      // Choose your storage mode
      storageType: StorageType.memory, // or StorageType.deviceSecure

      // Memory options (for memory mode)
      enableEncryptionMemory: true,
      autoCleanupMemory: true,
      cleanupIntervalMemory: Duration(minutes: 10),

      // Debug logging
      showLog: true,

      child: MyApp(),
    ),
  );
}

// Then use anywhere in your app:
class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: HomePage(),
    );
  }
}

class HomePage extends StatelessWidget {
  Future<void> saveToken() async {
    // Store securely
    await MemGuardStatic.store('auth_token', 'super_secret_jwt');

    // Retrieve
    final token = await MemGuardStatic.retrieve('auth_token');
    print('Token: $token');

    // Check existence
    final exists = await MemGuardStatic.contains('auth_token');

    // Delete
    await MemGuardStatic.delete('auth_token');
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('MemGuard Demo')),
      body: Center(
        child: ElevatedButton(
          onPressed: saveToken,
          child: Text('Test Secure Storage'),
        ),
      ),
    );
  }
}

---

📖 API Reference

Storage Operations

// Store data
await MemGuardStatic.store('key', 'value');

// Retrieve data
String? value = await MemGuardStatic.retrieve('key');

// Check if key exists
bool exists = await MemGuardStatic.contains('key');

// Delete key
await MemGuardStatic.delete('key');

// Get storage statistics
Map<String, dynamic> stats = await MemGuardStatic.getStats();

// Cleanup memory (memory mode only)
MemGuardStatic.cleanupMemory();

// Cleanup all storage
MemGuardStatic.cleanupAll();

Advanced: Zero-Copy Operations (Memory Mode Only)

For maximum performance, access data directly in Rust memory without copying to Dart:

// Perform cryptographic operations without copying to Dart
final signature = await MemGuardStatic.performSecureOperation<String>(
  'private_key',
  (dataPtr, length) {
    // Direct pointer access — zero copies!
    final bytes = dataPtr.asTypedList(length);

    // Perform operation (e.g., sign with private key)
    final signature = yourCryptoLib.sign(bytes, message);

    return signature;
    // Buffer automatically zeroed after this scope
  },
);

Use cases:

• Cryptographic signing without key exposure
• Hash computation on sensitive data
• Encryption/decryption with in-memory keys
• Any operation where data must never touch Dart heap

---

🎯 Storage Mode Comparison

Feature	Memory Storage	Device Secure Storage
Speed	⚡ Instant (Rust FFI)	🐇 Fast (disk + cache)
Persistence	❌ Ephemeral	✅ Survives restarts
Encryption	Optional (Rust AES)	✅ Hardware-backed
Auto-cleanup	✅ Configurable	❌ Manual only
Zero-copy	✅ Yes	❌ No
Best for	Session data	Long-term secrets

When to Use Memory Storage

MemGuard(
  storageType: StorageType.memory,
  enableEncryptionMemory: true,
  autoCleanupMemory: true,
  cleanupIntervalMemory: Duration(minutes: 5),
  child: MyApp(),
)

✅ Perfect for:

• Session tokens (expire on app close)
• Temporary API keys
• In-flight credentials
• Crypto operations (use performSecureOperation)
• Any data that shouldn't persist

When to Use Device Secure Storage

MemGuard(
  storageType: StorageType.deviceSecure,
  child: MyApp(),
)

✅ Perfect for:

• User login credentials
• OAuth refresh tokens
• Biometric authentication keys
• App settings with sensitive data
• Anything that must survive app restart

---

🔧 Configuration Options

Memory Storage Configuration

MemGuard(
  storageType: StorageType.memory,

  // Enable AES-256-GCM encryption in Rust
  enableEncryptionMemory: true,

  // Auto-cleanup on app background/close
  autoCleanupMemory: true,

  // How often to run cleanup (if auto enabled)
  cleanupIntervalMemory: Duration(minutes: 10),

  // Enable debug logging
  showLog: true,

  child: MyApp(),
)

Device Secure Storage Configuration

MemGuard(
  storageType: StorageType.deviceSecure,

  // Enable Rust cache for faster reads (recommended)
  enableEncryptionMemory: true,

  // Enable debug logging
  showLog: true,

  child: MyApp(),
)

---

🛡️ Security Features

What MemGuard Protects Against

✅ Memory Dumps — Sensitive data never stored in Dart VM heap
✅ Platform Channel Interception — Only boolean flags transmitted
✅ Heap Inspection — Rust memory is protected and zeroed
✅ Data Tampering — GCM authentication tags verify integrity
✅ Key Extraction — Hardware-backed keys never leave secure enclave
✅ Root Access (partial) — Keys resist extraction even on rooted devices

Attack Resistance

// ❌ BAD: Traditional secure storage
await secureStorage.write('token', 'secret'); // Plaintext in Dart heap!

// ✅ GOOD: MemGuard memory storage
await MemGuardStatic.store('token', 'secret'); // Only in Rust protected memory

// ✅ BETTER: MemGuard device secure
MemGuard(storageType: StorageType.deviceSecure, ...); // Hardware encryption + Rust cache

What MemGuard Does NOT Protect Against

❌ Physical device seizure by sophisticated attackers
❌ Compromised OS/kernel (malware with root/system privileges)
❌ User-authorized access (screen recording, accessibility services)
❌ State-level adversaries with hardware forensics tools

Threat Model: MemGuard is designed for production app security against common attack vectors (malware, memory dumps, network interception). It is NOT a substitute for end-to-end encryption or protection against nation-state actors.

---

📊 Storage Statistics

final stats = await MemGuardStatic.getStats();
print(stats);

// Memory Storage Output:
// {
//   "items_count": 5,
//   "total_size_bytes": 2048,
//   "encrypted_items": 5,
//   "platform": "android",
//   "rust_version": "1.70.0",
//   "storage_type": "memory"
// }

// Device Secure Storage Output:
// {
//   "storage_type": "hardware_backed_keystore",
//   "encryption_type": "aes_256_gcm",
//   "key_strength": "256_bit",
//   "rust_initialized": true,
//   "items_count": 3,
//   "total_size_bytes": 4096,
//   "directory_path": "/data/user/0/com.app/files/memguard_secure",
//   "timestamp": 1701234567890
// }

---

🎨 Convenience Extensions

String Extension

// Store string directly
await "my_secret_value".storeAs('api_key');

// Works with any storage type
await "refresh_token_xyz".storeAs('refresh_token');

Context Extension

class MyWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    // Access MemGuard core directly
    final core = context.memguard;

    // Check initialization status
    print('Storage type: ${core.currentStorageType}');
    print('Rust ready: ${core.isRustInitialized}');

    return Container();
  }
}

---

🔄 Lifecycle Management

MemGuard automatically handles app lifecycle events:

// Memory Storage: Auto-cleanup on background
MemGuard(
  storageType: StorageType.memory,
  autoCleanupMemory: true, // ← Cleans on app pause/background
  child: MyApp(),
)

// Lifecycle events handled:
// • AppLifecycleState.paused → cleanupMemory()
// • AppLifecycleState.inactive → cleanupMemory()
// • AppLifecycleState.detached → cleanupAll()

Manual cleanup:

// Clean memory only (memory mode)
MemGuardStatic.cleanupMemory();

// Clean everything (all modes)
MemGuardStatic.cleanupAll();

---

🐛 Error Handling

try {
  await MemGuardStatic.store('key', 'value');
} catch (e) {
  if (e is StateError) {
    // MemGuard not initialized
    print('Initialize MemGuard first!');
  } else if (e is UnsupportedError) {
    // Feature not available (e.g., zero-copy on device secure)
    print('Operation not supported for this storage type');
  } else if (e is ArgumentError) {
    // Storage type mismatch
    print('Wrong storage type specified');
  } else {
    // Other errors (platform exceptions, etc.)
    print('Storage error: $e');
  }
}

Common errors:

• StateError: MemGuard is not initialized — Wrap your app in MemGuard widget
• UnsupportedError: Secure buffer operations only available for memory storage — Use StorageType.memory for zero-copy
• ArgumentError: Requested storage type does not match — Don't mix storage types in same session

---

📱 Platform Support

Platform	Memory Storage	Device Secure	Status
Android	✅ Full	✅ Full	Tested ✅
iOS	⚠️ Untested	⚠️ Untested	Needs Testing
Windows	⚠️ Untested	⚠️ Untested	Needs Testing
macOS	⚠️ Untested	⚠️ Untested	Needs Testing
Linux	✅ Full	❌ Not Available	Tested ✅

Android Requirements

• Minimum: API 23 (Android 6.0 Marshmallow)
• Recommended: API 28+ (Android 9.0 Pie) for StrongBox support

🐧 Linux Compatibility

✅ Supported

• Ubuntu 20.04+ ✅ (22.04 tested)
• Debian 11+ ✅
• Fedora 34+ ✅
• Arch Linux ✅
• Manjaro ✅
• Pop!_OS 20.04+ ✅
• Linux Mint 20+ ✅
• Elementary OS 6+ ✅

Requires glibc 2.31+ and 64-bit (x86_64).

---

🏗️ Architecture

MemGuard is built on top of MemGuard Core — the native Rust + Kotlin foundation that powers the zero-leak security model.

Stack:

• Dart Layer (this plugin): High-level Flutter API
• Rust FFI: Protected memory allocation and cryptography
• Kotlin Platform: Android KeyStore integration and encrypted file I/O
• Native Libraries: Compiled .so binaries for ARM/x86

See the MemGuard Core README for low-level implementation details.

---

🧪 Testing

// Example test
void main() {
  test('Memory storage lifecycle', () async {
    MemGuardStatic.initMemoryStorage(
      enableEncryptionMemory: true,
      autoCleanupMemory: false,
      cleanupIntervalMemory: Duration(minutes: 10),
    );

    await MemGuardStatic.store('test_key', 'test_value');

    final value = await MemGuardStatic.retrieve('test_key');
    expect(value, 'test_value');

    await MemGuardStatic.delete('test_key');

    final deleted = await MemGuardStatic.retrieve('test_key');
    expect(deleted, isNull);
  });
}

---

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Areas for Contribution

• iOS/macOS platform implementation
• Windows/Linux platform implementation
• Additional encryption algorithms
• Performance benchmarks
• Integration tests
• Documentation improvements

---

🙏 Acknowledgments

Built with:

• Rust FFI for memory-safe protected storage
• Android KeyStore for hardware-backed encryption
• flutter_fastlog for high-performance logging
• MemGuard Core for the native foundation

---

⚠️ Security Notice

MemGuard implements defense-in-depth secure storage with zero-leak architecture. However, no client-side storage is absolutely secure. Always:

• ✅ Validate critical operations server-side
• ✅ Use certificate pinning for network requests
• ✅ Implement request signing for API calls
• ✅ Rotate sensitive credentials regularly
• ✅ Enable biometric authentication when available

For high-security applications, combine MemGuard with additional layers of protection (HSM, remote attestation, etc.).

---

📚 Related Projects

• MemGuard Core - Native Rust + Kotlin foundation

---

💬 Support

• 🐛 Issue Tracker
• 💬 Discussions