Security: Vault

The Vault facade provides a simple interface for reading and writing sensitive data to the platform's native secure storage, with a fake implementation for testing.

• Introduction
• Storing Items
• Retrieving Items
• Removing Items
• Testing

Introduction

The Vault facade provides a simple interface for securely storing sensitive data on the device. It uses the platform's native secure storage mechanisms:

• iOS: Keychain
• Android: EncryptedSharedPreferences
• macOS: Keychain
• Windows: Windows Credential Locker

Storing Items

To store a value in the vault:

await Vault.put('api_token', 'super-secret-token');

Retrieving Items

To retrieve a value:

final token = await Vault.get('api_token');

if (token != null) {
  // Use token...
}

Removing Items

To remove a specific item:

await Vault.delete('api_token');

To wipe all data from the vault (use with caution):

await Vault.flush();

Testing

Replace the real vault service with a FakeVaultService using Vault.fake(). The fake stores values in memory so tests run without platform channels.

import 'package:magic/testing.dart';

void main() {
  tearDown(() => Vault.unfake());

  test('stores and reads a token', () async {
    final fake = Vault.fake({'existing': 'seed'});

    await Vault.put('token', 'abc123');

    fake.assertWritten('token');
    fake.assertContains('token');
    expect(await Vault.get('token'), 'abc123');
  });

  test('delete removes the key', () async {
    final fake = Vault.fake({'token': 'abc123'});

    await Vault.delete('token');

    fake.assertDeleted('token');
    fake.assertMissing('token');
  });
}

Pass an optional map of initial values to Vault.fake() to pre-seed the store.

FakeVaultService Assertions

Call Vault.unfake() in tearDown() to restore the real vault binding after each test.