magic_encryption
AES-256-CBC for a Magic app. The Crypt facade encrypts a String with the configured app.key (encrypt, decrypt, synchronous) or with a per-device key kept in Vault (encryptWithDeviceKey, decryptWithDeviceKey, async). EncryptionServiceProvider binds the cipher; key:generate writes APP_KEY. The payload is base64(iv):base64(ciphertext), carries no MAC and is not Laravel's format.
This skill covers magic_encryption only. The Magic framework itself (container, facades, Vault, config) is the magic-framework skill.
Install
flutter pub add magic_encryption
dart run magic:dowel plugin:install magic_encryption
dart run magic:dowel key:generate
Requires Dart >=3.13, Flutter >=3.47 and magic ^1.0.0. The installer registers EncryptionServiceProvider in lib/config/app.dart and publishes no config, because magic:install already wires 'key': env('APP_KEY'). It never runs key:generate. Import only the barrel: package:magic_encryption/magic_encryption.dart.
Crypt rules
- Register
EncryptionServiceProviderinprovidersbefore callingCrypt.encryptorCrypt.decrypt: it is not auto-registered, and the facade resolves theencrypterbinding it creates inboot(). CallCryptafterMagic.initcompletes. - Never call
Crypt.encrypt(''). An empty string throwsRangeError, because there is no block to pad. Guard the call. Crypttakes and returns aString. Encode aMaporListwithjsonEncodebefore andjsonDecodeafter.- Catch
MagicDecryptExceptionfromdecryptand answer the party that sent the payload with one generic error. Different failures shown to a sender are what a padding oracle is built from. - A missing or wrong-size
app.keydoes not fail boot. The firstCryptcall throws anException. A raw key is 32 bytes of UTF-8 (32 characters for ASCII); abase64:key decodes to 32 bytes. - Treat
Cryptas confidentiality at rest and nothing more. There is no MAC, so a payload that decrypts is not proven untampered, and CBC is malleable. Verify a token, an amount or an identity on the server that issued it. - A payload from the wrong key almost always throws
MagicDecryptException, but about one in 256 unpads cleanly and returns garbage text. Do not use a decrypt that did not throw as a key check.
Key rules
- Create
APP_KEYwithdart run magic:dowel key:generate: it writesAPP_KEY=base64:<32 random bytes>to.env.--showprints it and leaves.envalone. Never commit it. key:generatereplaces any existingAPP_KEY, and every value encrypted under the old key becomes unreadable. Never run it on an app with stored ciphertext. The payload has no key id, so there is no rotation: migrate by decrypting withMagicEncrypter.fromAppKey(oldKey)and encrypting again withCrypt.encrypt.- Device-key mode needs core's
VaultServiceProviderand needs noapp.key. The key is 32 random alphanumeric characters stored inVaultasmagic:device_encryption_key, created on first use and cached in a static field. generateDeviceKey()andclearDeviceKey()orphan everything encrypted under the old device key. The key is lost with the install's secure storage, so keep only data you can recreate.- A
Crypt.encryptpayload and a device-key payload do not open each other's: keep a value with the mode that wrote it.
Wire format
AES-256 in CBC mode, PKCS7 padding, key bytes either the UTF-8 bytes of a raw string (32 bytes, 32 characters for ASCII) or the 32 decoded bytes of a base64: key, a random 16-byte IV per call, UTF-8 plaintext, payload base64(iv):base64(ciphertext). It is the format Magic 0.0.41 and earlier wrote, so it never changes. It is not Laravel's JSON-with-HMAC payload: neither side reads the other's. MagicEncrypter.encrypt has an iv: parameter for tests only.
Recipes
Encrypt and decrypt with the app key:
import 'package:magic_encryption/magic_encryption.dart';
String? open(String payload) {
try {
return Crypt.decrypt(payload);
} on MagicDecryptException {
return null; // Log it; do not tell the sender why.
}
}
String seal(String value) => Crypt.encrypt(value);
Keep a token on the device only:
import 'package:magic_encryption/magic_encryption.dart';
Future<String> store(String token) => Crypt.encryptWithDeviceKey(token);
Future<String> load(String stored) => Crypt.decryptWithDeviceKey(stored);
Testing
No mocking library is needed. In setUp() call MagicApp.reset() and Magic.flush(), then bind a cipher with Magic.singleton('encrypter', () => MagicEncrypter('0123456789abcdef0123456789abcdef')) for config-key mode, or Vault.fake() for device-key mode. Crypt caches the device encrypter in a static field that Magic.flush() does not reset, so call await Crypt.clearDeviceKey() in tearDown(). Do not assert that a wrong-key payload throws, since about one in 256 does not; assert it never yields the plaintext. Pin the IV with encrypt(value, iv: Uint8List(16)) to assert an exact payload.