Add comment about LocalSecret

bindings/dart/lib/local_secret.dart

@@ -1,14 +1,31 @@
 part of 'ouisync.dart';
 
-// Used for opening a reository.
+// `LocalSecret` is used to encrypt and decrypt "global" read and write keys
+// stored inside repositories which are consequently used to encrypt, decrypt
+// and sign repository data.
+//
+// There may be two `LocalSecrets`, one for decrypting the global read and one
+// decrypting the global write keys. Note the that decrypting the global write
+// key will enable repository reading as well because the global read key is
+// derived from the global write key.
+//
+// When opening a repository with a `LocalSecret` the library will attempt to
+// gain the highest possible access. That is, it will use the local secret to
+// decrypt the global write key first and, if that fails, it'll attempt to
+// decrypt the global read key.
+//
+// `LocalSecret` can be either a `LocalPassword` or a `LocalSecretKey`. In case
+// a `LocalPassword` is provided to the library, it is internally converted to
+// `LocalSecretKey` using a KDF and a `PasswordSalt`.  Ouisync uses two
+// `PasswordSalt`s one for the "read" and one for the "write" local secret keys
+// and they are stored inside each repository database individually.
 sealed class LocalSecret {
   Object? encode();
 
   @override
   String toString();
 }
 
-// Used for creating a reository and changing its local secret.
 sealed class SetLocalSecret {
   Object? encode();
 
@@ -18,6 +35,7 @@ sealed class SetLocalSecret {
   String toString();
 }
 
+// A user provided password used to encrypt individual repository databases
 class LocalPassword implements LocalSecret, SetLocalSecret {
   final String string;
 
@@ -48,6 +66,8 @@ class LocalPassword implements LocalSecret, SetLocalSecret {
   int get hashCode => string.hashCode;
 }
 
+// Key generated by Argon2 KDF from a `LocalPassword` and a `PasswordSalt`. The
+// salt is stored in the per-repository database.
 class LocalSecretKey implements LocalSecret {
   // 256-bit as used by the Rust ChaCha20 implementation Ouisync is using.
   static const sizeInBytes = 32;