Installation

Install#

flutter pub add magic_encryption
dart run magic:dowel plugin:install magic_encryption

The installer reads the package's install.yaml and injects EncryptionServiceProvider into the providers list of lib/config/app.dart. It publishes no config file: the provider reads the app.key that magic:install already wires from APP_KEY.

import 'package:magic_encryption/magic_encryption.dart';

The barrel is the only import; everything under src/ is private.

Requirements#

Create the Key#

dart run magic:dowel key:generate

The command writes APP_KEY=base64:<32 random bytes> to the project's .env, creating the file when it is missing. It replaces an APP_KEY line that is already there, and every value encrypted under the old key becomes unreadable. For that reason the installer does not run it: creating the key is your call. --show prints the line without touching .env.

Never commit APP_KEY. See App Key for the accepted formats.

Register the Provider#

plugin:install does this for you. To do it by hand, add the provider to lib/config/app.dart:

import 'package:magic/magic.dart';
import 'package:magic_encryption/magic_encryption.dart';

final Map<String, dynamic> appConfig = {
  'app': {
    'key': env('APP_KEY'),
    'providers': [
      (app) => EncryptionServiceProvider(app),
    ],
  },
};

The provider is not auto-registered. Without it nothing binds the encrypter and Crypt.encrypt fails. Device-key mode alone does not need it, only VaultServiceProvider.

Verify#

import 'package:magic_encryption/magic_encryption.dart';

void main() {
  final String secret = Crypt.encrypt('hello');
  print(secret); // base64(iv):base64(ciphertext)
  print(Crypt.decrypt(secret)); // hello
}

Run it after Magic.init has completed. The two lines print a payload of two base64 halves joined by a colon, then hello. A payload differs on every run, because each call draws a fresh IV.

Related Documentation#

• Crypt: encrypting and decrypting, and what fails.
• App Key: key formats and key:generate.
• Device Key: the key kept in Vault.
• Wire Format: the exact payload and its limits.
• Testing: testing code that calls Crypt.