feat: Track new/replaced ratchets in the results

CHANGELOG.md

@@ -65,4 +65,9 @@ This version is a complete rework of omemo_dart!
 - Replace exceptions with errors inside a result type
 - Ratchets and trust data is now loaded and cached on demand
 - Accessing the trust manager must happen via `withTrustManager`
-- Overriding the base implementations is replaced by providing callback functions
+- Overriding the base implementations is replaced by providing callback functions
+
+## 0.5.1
+
+- Remove `added` and `replaced` from the data passed to the `CommitRatchetsCallback`
+- Added a list of newly added and replaced ratchets to the encryption and decryption results. This is useful for displaying messages like "Contact added a new device"

lib/src/omemo/decryption_result.dart

@@ -3,7 +3,13 @@ import 'package:omemo_dart/src/errors.dart';
 
 @immutable
 class DecryptionResult {
-  const DecryptionResult(this.payload, this.usedOpkId, this.error);
+  const DecryptionResult(
+    this.payload,
+    this.usedOpkId,
+    this.newRatchets,
+    this.replacedRatchets,
+    this.error,
+  );
 
   /// The decrypted payload or null, if it was an empty OMEMO message.
   final String? payload;
@@ -12,6 +18,13 @@ class DecryptionResult {
   /// replacing the OPK after a message catch-up.
   final int? usedOpkId;
 
+  /// Mapping of JIDs to a list of device ids for which we created a new ratchet session.
+  final Map<String, List<int>> newRatchets;
+
+  /// Similar to [newRatchets], but the ratchets listed in [replacedRatchets] where also existent before
+  /// and replaced with the new ratchet.
+  final Map<String, List<int>> replacedRatchets;
+
   /// The error that occurred during decryption or null, if no error occurred.
   final OmemoError? error;
 }

lib/src/omemo/encryption_result.dart

@@ -8,6 +8,8 @@ class EncryptionResult {
     this.ciphertext,
     this.encryptedKeys,
     this.deviceEncryptionErrors,
+    this.newRatchets,
+    this.replacedRatchets,
     this.canSend,
   );
 
@@ -21,6 +23,13 @@ class EncryptionResult {
   /// Mapping of a JID to
   final Map<String, List<EncryptToJidError>> deviceEncryptionErrors;
 
+  /// Mapping of JIDs to a list of device ids for which we created a new ratchet session.
+  final Map<String, List<int>> newRatchets;
+
+  /// Similar to [newRatchets], but the ratchets listed in [replacedRatchets] where also existent before
+  /// and replaced with the new ratchet.
+  final Map<String, List<int>> replacedRatchets;
+
   /// A flag indicating that the message could be sent like that, i.e. we were able
   /// to encrypt to at-least one device per recipient.
   final bool canSend;

lib/src/omemo/omemo.dart

@@ -356,6 +356,8 @@ class OmemoManager {
       return DecryptionResult(
         null,
         null,
+        const {},
+        const {},
         NotEncryptedForDeviceError(),
       );
     }
@@ -365,6 +367,8 @@ class OmemoManager {
       return DecryptionResult(
         null,
         null,
+        const {},
+        const {},
         MalformedEncryptedKeyError(),
       );
     }
@@ -373,7 +377,8 @@ class OmemoManager {
     final ratchetKey =
         RatchetMapKey(stanza.bareSenderJid, stanza.senderDeviceId);
     var processAsKex = key.kex;
-    if (key.kex && _ratchetMap.containsKey(ratchetKey)) {
+    final ratchetAlreadyExists = _ratchetMap.containsKey(ratchetKey);
+    if (key.kex && ratchetAlreadyExists) {
       final ratchet = _ratchetMap[ratchetKey]!;
       final kexMessage = OMEMOKeyExchange.fromBuffer(key.data);
       final ratchetEk = await ratchet.kex.ek.getBytes();
@@ -403,6 +408,8 @@ class OmemoManager {
         return DecryptionResult(
           null,
           null,
+          const {},
+          const {},
           UnknownSignedPrekeyError(),
         );
       }
@@ -443,7 +450,13 @@ class OmemoManager {
         final error = keyAndHmac.get<OmemoError>();
         _log.warning('Failed to decrypt symmetric key: $error');
 
-        return DecryptionResult(null, null, error);
+        return DecryptionResult(
+          null,
+          null,
+          const {},
+          const {},
+          error,
+        );
       }
 
       Result<OmemoError, String?> result;
@@ -459,6 +472,8 @@ class OmemoManager {
           return DecryptionResult(
             null,
             null,
+            const {},
+            const {},
             error,
           );
         }
@@ -487,8 +502,6 @@ class OmemoManager {
           stanza.bareSenderJid,
           stanza.senderDeviceId,
           ratchet,
-          true,
-          false,
         ),
       ]);
 
@@ -512,9 +525,14 @@ class OmemoManager {
         _ratchetMap.containsKey(ratchetKey),
       );
 
+      final newlyCreatedDevice = {
+        stanza.bareSenderJid: [stanza.senderDeviceId],
+      };
       return DecryptionResult(
         result.get<String?>(),
         kexMessage.pkId,
+        ratchetAlreadyExists ? {} : newlyCreatedDevice,
+        ratchetAlreadyExists ? newlyCreatedDevice : {},
         null,
       );
     } else {
@@ -526,11 +544,13 @@ class OmemoManager {
             .contains(stanza.senderDeviceId)) {
           _deviceList[stanza.bareSenderJid]!.add(stanza.senderDeviceId);
         }
-        await _sendOmemoHeartbeat(stanza.bareSenderJid);
+        final emptyResult = await _sendOmemoHeartbeat(stanza.bareSenderJid);
 
         return DecryptionResult(
           null,
           null,
+          emptyResult.newRatchets,
+          emptyResult.replacedRatchets,
           NoSessionWithDeviceError(),
         );
       }
@@ -553,7 +573,13 @@ class OmemoManager {
       if (keyAndHmac.isType<OmemoError>()) {
         final error = keyAndHmac.get<OmemoError>();
         _log.warning('Failed to decrypt symmetric key: $error');
-        return DecryptionResult(null, null, error);
+        return DecryptionResult(
+          null,
+          null,
+          const {},
+          const {},
+          error,
+        );
       }
 
       Result<OmemoError, String?> result;
@@ -568,6 +594,8 @@ class OmemoManager {
           return DecryptionResult(
             null,
             null,
+            const {},
+            const {},
             error,
           );
         }
@@ -589,8 +617,6 @@ class OmemoManager {
           stanza.bareSenderJid,
           stanza.senderDeviceId,
           ratchet,
-          false,
-          false,
         ),
       ]);
 
@@ -600,6 +626,8 @@ class OmemoManager {
       return DecryptionResult(
         result.get<String?>(),
         null,
+        const {},
+        const {},
         null,
       );
     }
@@ -642,6 +670,8 @@ class OmemoManager {
     );
     final encryptionErrors = <String, List<EncryptToJidError>>{};
     final addedRatchetKeys = List<RatchetMapKey>.empty(growable: true);
+    final newRatchets = <String, List<int>>{};
+    final replacedRatchets = <String, List<int>>{};
     final kex = <RatchetMapKey, OMEMOKeyExchange>{};
     for (final jid in stanza.recipientJids) {
       final newBundles = await _fetchNewOmemoBundles(jid);
@@ -683,6 +713,11 @@ class OmemoManager {
         );
 
         // Track the ratchet
+        if (_ratchetMap.containsKey(ratchetKey)) {
+          replacedRatchets.appendOrCreate(ratchetKey.jid, ratchetKey.deviceId);
+        } else {
+          newRatchets.appendOrCreate(ratchetKey.jid, ratchetKey.deviceId);
+        }
         _ratchetMap[ratchetKey] = newRatchet;
         addedRatchetKeys.add(ratchetKey);
 
@@ -708,8 +743,6 @@ class OmemoManager {
             key.jid,
             key.deviceId,
             _ratchetMap[key]!,
-            true,
-            false,
           );
         }).toList(),
       );
@@ -819,6 +852,8 @@ class OmemoManager {
       ciphertext,
       encryptedKeys,
       encryptionErrors,
+      newRatchets,
+      replacedRatchets,
       successfulEncryptions.values.every((n) => n > 0),
     );
   }
@@ -832,7 +867,7 @@ class OmemoManager {
   }
 
   /// Like [sendOmemoHeartbeat], but does not acquire the lock for [jid].
-  Future<void> _sendOmemoHeartbeat(String jid) async {
+  Future<EncryptionResult> _sendOmemoHeartbeat(String jid) async {
     final result = await _onOutgoingStanzaImpl(
       OmemoOutgoingStanza(
         [jid],
@@ -840,6 +875,7 @@ class OmemoManager {
       ),
     );
     await sendEmptyOmemoMessageImpl(result, jid);
+    return result;
   }
 
   /// Removes all ratchets associated with [jid].
@@ -915,8 +951,6 @@ class OmemoManager {
           jid,
           device,
           ratchet,
-          false,
-          false,
         ),
       ]);
     }

lib/src/omemo/ratchet_data.dart

@@ -5,8 +5,6 @@ class OmemoRatchetData {
     this.jid,
     this.id,
     this.ratchet,
-    this.added,
-    this.replaced,
   );
 
   /// The JID we have the ratchet with.
@@ -17,10 +15,4 @@ class OmemoRatchetData {
 
   /// The actual double ratchet to commit.
   final OmemoDoubleRatchet ratchet;
-
-  /// Indicates whether the ratchet has just been created (true) or just modified (false).
-  final bool added;
-
-  /// Indicates whether the ratchet has been replaced (true) or not.
-  final bool replaced;
 }

pubspec.yaml

@@ -1,6 +1,6 @@
 name: omemo_dart
 description: An XMPP library independent OMEMO library
-version: 0.5.0
+version: 0.5.1
 homepage: https://github.com/PapaTutuWawa/omemo_dart
 publish_to: https://git.polynom.me/api/packages/PapaTutuWawa/pub
 

test/omemo_test.dart

@@ -1880,7 +1880,12 @@ void main() {
     );
     expect(aliceResult2.error, isNull);
     expect(aliceResult2.payload, isNull);
-    expect(aliceManager.getRatchet(RatchetMapKey(bobJid, bobDevice.id))!.acknowledged, isTrue);
+    expect(
+      aliceManager
+          .getRatchet(RatchetMapKey(bobJid, bobDevice.id))!
+          .acknowledged,
+      isTrue,
+    );
 
     // Now Alice sends something to Bob
     final aliceResult3 = await aliceManager.onOutgoingStanza(
@@ -1903,4 +1908,118 @@ void main() {
     expect(bobResult.error, isNull);
     expect(bobResult.payload, 'Hello Bob');
   });
+
+  test('Test correct new and replaced lists', () async {
+    const aliceJid = 'alice@server1';
+    const bobJid = 'bob@server2';
+
+    final aliceDevice =
+        await OmemoDevice.generateNewDevice(aliceJid, opkAmount: 1);
+    final bobDevice = await OmemoDevice.generateNewDevice(bobJid, opkAmount: 1);
+
+    final aliceManager = OmemoManager(
+      aliceDevice,
+      AlwaysTrustingTrustManager(),
+      (result, recipientJid) async {},
+      (jid) async {
+        expect(jid, bobJid);
+        return [bobDevice.id];
+      },
+      (jid, id) async {
+        expect(jid, bobJid);
+        return bobDevice.toBundle();
+      },
+      (jid) async {},
+      (_) async {},
+    );
+
+    EncryptionResult? bobEmptyMessage;
+    final bobManager = OmemoManager(
+      bobDevice,
+      TestingTrustManager(),
+      (result, recipientJid) async {
+        bobEmptyMessage = result;
+      },
+      (jid) async {
+        expect(jid, aliceJid);
+        return [
+          aliceDevice.id,
+        ];
+      },
+      (jid, id) async {
+        expect(jid, aliceJid);
+
+        if (id == aliceDevice.id) {
+          return aliceDevice.toBundle();
+        }
+
+        return null;
+      },
+      (jid) async {},
+      (_) async {},
+    );
+
+    // Alice sends Bob a message
+    final aliceResult1 = await aliceManager.onOutgoingStanza(
+      const OmemoOutgoingStanza(
+        [bobJid],
+        'Hello World!',
+      ),
+    );
+    expect(aliceResult1.newRatchets[bobJid], [bobDevice.id]);
+    expect(aliceResult1.replacedRatchets.isEmpty, isTrue);
+
+    // Bob decrypts Alice's message
+    final bobResult1 = await bobManager.onIncomingStanza(
+      OmemoIncomingStanza(
+        aliceJid,
+        aliceDevice.id,
+        aliceResult1.encryptedKeys[bobJid]!,
+        base64.encode(aliceResult1.ciphertext!),
+        false,
+      ),
+    );
+    expect(bobResult1.error, null);
+    expect(bobEmptyMessage, isNotNull);
+    expect(bobResult1.newRatchets[aliceJid], [aliceDevice.id]);
+    expect(bobResult1.replacedRatchets.isEmpty, isTrue);
+
+    // Bob now sends the empty OMEMO message to Alice, who then decrypts
+    // it.
+    final aliceResult2 = await aliceManager.onIncomingStanza(
+      OmemoIncomingStanza(
+        bobJid,
+        bobDevice.id,
+        bobEmptyMessage!.encryptedKeys[aliceJid]!,
+        bobEmptyMessage!.ciphertext?.toBase64(),
+        false,
+      ),
+    );
+    expect(aliceResult2.newRatchets.isEmpty, isTrue);
+    expect(aliceResult2.replacedRatchets.isEmpty, isTrue);
+
+    // Bob now removes all ratchets and sends a new message to alice
+    await bobManager.removeAllRatchets(aliceJid);
+    final bobResult2 = await bobManager.onOutgoingStanza(
+      const OmemoOutgoingStanza(
+        [aliceJid],
+        'New Ratchet, so cool',
+      ),
+    );
+
+    // And Alice decrypts it
+    final aliceResult3 = await aliceManager.onIncomingStanza(
+      OmemoIncomingStanza(
+        bobJid,
+        bobDevice.id,
+        bobResult2.encryptedKeys[aliceJid]!,
+        bobResult2.ciphertext?.toBase64(),
+        false,
+      ),
+    );
+    expect(aliceResult3.error, isNull);
+    expect(aliceResult3.payload, 'New Ratchet, so cool');
+    expect(aliceResult3.newRatchets.isEmpty, isTrue);
+    expect(aliceResult3.replacedRatchets[bobJid], [bobDevice.id]);
+  });
 }