docs: improve docs for CryptoService, VaultCryptoService and Keychain

catalyst_voices/packages/catalyst_voices_services/lib/src/crypto/crypto_service.dart

@@ -1,21 +1,68 @@
 import 'package:flutter/foundation.dart';
 
+/// An abstract interface that defines cryptographic operations such as
+/// key derivation, encryption, decryption, and key verification.
 abstract interface class CryptoService {
+  /// Derives a cryptographic key from a given seed, with an optional salt.
+  ///
+  /// The derived key is generated based on the provided [seed], which serves
+  /// as the primary input. Optionally, a [salt] can be used to further
+  /// randomize the key derivation process, increasing security.
+  ///
+  /// - [seed]: The main input data used for key derivation.
+  /// - [salt]: Optional salt value to randomize the derived key (can be null).
+  ///
+  /// Returns a [Future] that completes with the derived key as a [Uint8List].
   Future<Uint8List> deriveKey(
     Uint8List seed, {
     Uint8List? salt,
   });
 
+  /// Verifies if a given cryptographic key is correctly derived from a seed.
+  ///
+  /// This method checks whether the provided [key] matches the key that would
+  /// be derived from the given [seed]. This can be useful to verify integrity
+  /// or correctness of the key derivation process.
+  ///
+  /// - [seed]: The input data used for key derivation.
+  /// - [key]: The derived key that needs to be verified.
+  ///
+  /// Returns a [Future] that completes with `true` if the [key] is valid and
+  /// correctly derived from the [seed], or `false` otherwise.
   Future<bool> verifyKey(
     Uint8List seed, {
     required Uint8List key,
   });
 
+  /// Decrypts the provided [data] using the specified cryptographic [key],
+  /// usually build using [deriveKey].
+  ///
+  /// This method takes encrypted [data] and decrypts it using the provided
+  /// [key]. The decryption algorithm and the format of the data should be
+  /// defined by the implementing class.
+  ///
+  /// - [data]: The encrypted data to be decrypted.
+  /// - [key]: The key used for decryption.
+  ///
+  /// Returns a [Future] that completes with the decrypted data as a
+  /// [Uint8List].
   Future<Uint8List> decrypt(
     Uint8List data, {
     required Uint8List key,
   });
 
+  /// Encrypts the provided [data] using the specified cryptographic [key],
+  /// usually build using [deriveKey].
+  ///
+  /// This method takes plaintext [data] and encrypts it using the provided
+  /// [key]. The encryption algorithm and format of the output should be defined
+  /// by the implementing class.
+  ///
+  /// - [data]: The plaintext data to be encrypted.
+  /// - [key]: The key used for encryption.
+  ///
+  /// Returns a [Future] that completes with the encrypted data as a
+  /// [Uint8List].
   Future<Uint8List> encrypt(
     Uint8List data, {
     required Uint8List key,

catalyst_voices/packages/catalyst_voices_services/lib/src/crypto/vault_crypto_service.dart

@@ -3,12 +3,23 @@ import 'dart:math';
 
 import 'package:catalyst_voices_models/catalyst_voices_models.dart';
 import 'package:catalyst_voices_services/src/crypto/crypto_service.dart';
+import 'package:catalyst_voices_services/src/storage/vault/vault.dart';
 import 'package:cryptography/cryptography.dart';
 import 'package:flutter/foundation.dart';
 import 'package:logging/logging.dart';
 
 final _logger = Logger('VaultCryptoService');
 
+/// [CryptoService] implementation used by default in [Vault].
+///
+/// It uses Pbkdf2 for key derivation as well as
+/// AesGcm for encryption/decryption.
+///
+/// Only keys build by [VaultCryptoService.deriveKey] should be used
+/// for crypto operations are we're adding [VaultCryptoService] specific
+/// metadata to them.
+///
+/// Supports version for future changes.
 final class VaultCryptoService implements CryptoService {
   /// Salt length for key derivation.
   static const int _saltLength = 16;

catalyst_voices/packages/catalyst_voices_services/lib/src/keychain/keychain.dart

@@ -13,6 +13,9 @@ const _seedPhraseKey = 'keychain_seed_phrase';
 // TODO(dtscalac): in the future when key derivation algorithm spec
 // will become stable consider to store derived keys instead of deriving
 // them each time they are needed.
+
+// TODO(damian-molinski): because we have dummy lock factors vault unlocking
+// is dummy too. Any operation on vault require correct lock factor input.
 final class Keychain {
   final _logger = Logger('Keychain');