philiprehberger_secure_store
v0.4.0189 downloadsMIT
Unified secure storage with built-in encryption and pluggable backends
$
dart pub add philiprehberger_secure_storeREADME
philiprehberger_secure_store
Unified secure storage with built-in encryption and pluggable backends
Requirements
- Dart >= 3.5
Installation
Add to your pubspec.yaml:
dependencies:
philiprehberger_secure_store: ^0.4.0
Then run:
dart pub get
Usage
import 'package:philiprehberger_secure_store/secure_store.dart';
final store = SecureStore(encryptionKey: 'my-secret-key');
await store.write('token', 'eyJhbGciOiJIUzI1...');
final token = await store.read('token');
JSON Storage
await store.writeJson('user', {'name': 'Alice', 'role': 'admin'});
final user = await store.readJson('user');
print(user!['name']); // Alice
Typed Values
await store.writeBool('dark_mode', true);
await store.writeInt('login_count', 42);
final darkMode = await store.readBool('dark_mode'); // true
final count = await store.readInt('login_count'); // 42
File Backend (Persistent)
For non-web platforms, import the file backend separately:
import 'package:philiprehberger_secure_store/secure_store.dart';
import 'package:philiprehberger_secure_store/file_backend.dart';
final store = SecureStore(
encryptionKey: 'my-key',
backend: FileBackend('/path/to/storage.json'),
);
await store.write('token', 'secret');
// Data persists across restarts
Custom Backend
Implement StorageBackend for any storage system:
class MyDatabaseBackend implements StorageBackend {
@override
Future<String?> read(String key) async { /* ... */ }
@override
Future<void> write(String key, String value) async { /* ... */ }
// ... implement all methods
}
final store = SecureStore(
encryptionKey: 'key',
backend: MyDatabaseBackend(),
);
Batch Operations
await store.writeMultiple({'token': 'abc', 'refresh': 'xyz', 'user': 'alice'});
final results = await store.readMultiple(['token', 'refresh']);
// {'token': 'abc', 'refresh': 'xyz'}
Expiration / TTL
await store.writeWithExpiry('session', 'token123', Duration(hours: 1));
await store.isExpired('session'); // false
// Clean up all expired entries
final removed = await store.cleanExpired();
Key Management
await store.containsKey('token'); // true
await store.allKeys(); // ['token', 'user', ...]
await store.delete('token');
await store.clear(); // remove everything
// Strict access — throws if key missing
final value = await store.readOrThrow('token');
// Quick key count
final count = await store.keyCount;
Key Rotation
Re-encrypt all stored values under a new encryption key:
await store.rotateKey('new-secret-key');
// All existing values are now encrypted with the new key
Namespaces
Isolate groups of keys with a namespace prefix:
final settings = store.namespace('settings');
final cache = store.namespace('cache');
await settings.write('theme', 'dark');
await cache.write('data', 'value');
// Each namespace is isolated
final keys = await settings.allKeys(); // ['theme']
await cache.clear(); // only clears cache keys
Conditional Delete
// Remove all keys matching a pattern
final removed = await store.deleteWhere((key) => key.startsWith('temp_'));
Backup & Restore
// Export raw encrypted data
final data = await store.backup();
// Restore from backup (clears store first)
await store.restore(data);
// JSON-based export/import
final jsonStr = await store.export();
await store.import(jsonStr);
API
SecureStore
| Method | Description |
|---|---|
SecureStore(encryptionKey:, backend:) | Create with encryption key and optional backend |
.write(key, value) | Store an encrypted string |
.read(key) | Read and decrypt a string (null if missing) |
.writeJson(key, value) | Store an encrypted JSON object |
.readJson(key) | Read and decrypt a JSON object |
.writeBool(key, value) | Store an encrypted boolean |
.readBool(key) | Read a boolean |
.writeInt(key, value) | Store an encrypted integer |
.readInt(key) | Read an integer |
.delete(key) | Delete a key |
.containsKey(key) | Check if a key exists |
.allKeys() | List all stored keys |
.clear() | Delete all data |
.readOrThrow(key) | Read or throw KeyNotFoundError |
.writeMultiple(pairs) | Write multiple key-value pairs |
.readMultiple(keys) | Read multiple keys at once |
.writeWithExpiry(key, value, ttl) | Store with time-to-live |
.isExpired(key) | Check if an item has expired |
.cleanExpired() | Remove all expired items |
.rotateKey(newKey) | Re-encrypt all values with a new key |
.backup() | Export raw encrypted key-value pairs |
.restore(data) | Clear and restore from raw encrypted data |
.export() | Export store as a JSON string |
.import(json) | Clear and import from a JSON string |
.keyCount | Get the number of stored keys |
.deleteWhere(test) | Delete keys matching a predicate |
.namespace(prefix) | Get a namespaced view of the store |
Backends
| Backend | Description |
|---|---|
MemoryBackend | In-memory (default, for testing) |
FileBackend(path) | JSON file on disk |
NamespacedStore | Scoped view with prefixed keys |
StorageBackend | Abstract interface for custom backends |
Development
dart pub get
dart analyze --fatal-infos
dart test
Support
If you find this project useful: