Return null from decryptEvent if session is unknown

This just makes the shape of the API a bit saner.

lib/crypto/OlmDevice.js

@@ -557,11 +557,15 @@ OlmDevice.prototype._saveInboundGroupSession = function(
  * @param {string} roomId
  * @param {string} senderKey
  * @param {string} sessionId
- * @param {function} func
- * @return {object} Object with two keys "result": result of func, "exists"
- *  whether the session exists. if the session doesn't exist then the function
- *  isn't called and the "result" is undefined.
+ * @param {function(Olm.InboundGroupSession): T} func
+ *
+ * @return {null} the sessionId is unknown
+ *
+ * @return {{result: T, keysProved: Object<string, string>, keysClaimed:
+ *    Object<string, string>}} result
+ *
  * @private
+ * @template {T}
  */
 OlmDevice.prototype._getInboundGroupSession = function(
     roomId, senderKey, sessionId, func
@@ -571,7 +575,7 @@ OlmDevice.prototype._getInboundGroupSession = function(
     );
 
     if (r === null) {
-        return {sessionExists: false};
+        return null;
     }
 
     r = JSON.parse(r);
@@ -585,14 +589,18 @@ OlmDevice.prototype._getInboundGroupSession = function(
         );
     }
 
+    // the sender must have had the senderKey to persuade us to save the
+    // session.
+    var keysProved = {curve25519: senderKey};
+    var keysClaimed = r.keysClaimed || {};
+
     var session = new Olm.InboundGroupSession();
     try {
         session.unpickle(this._pickleKey, r.session);
         return {
-            sessionExists: true,
             result: func(session),
-            keysProved: {curve25519: senderKey},
-            keysClaimed: r.keysClaimed || {},
+            keysProved: keysProved,
+            keysClaimed: keysClaimed,
         };
     } finally {
         session.free();
@@ -634,7 +642,10 @@ OlmDevice.prototype.addInboundGroupSession = function(
  * @param {string} sessionId session identifier
  * @param {string} body      base64-encoded body of the encrypted message
  *
- * @return {object} {result: "plaintext"|undefined, sessionExists: Boolean}
+ * @return {null} the sessionId is unknown
+ *
+ * @return {{result: string, keysProved: Object<string, string>, keysClaimed:
+ *    Object<string, string>}} result
  */
 OlmDevice.prototype.decryptGroupMessage = function(
     roomId, senderKey, sessionId, body

lib/crypto/algorithms/base.js

@@ -109,6 +109,20 @@ var DecryptionAlgorithm = function(params) {
 /** */
 module.exports.DecryptionAlgorithm = DecryptionAlgorithm;
 
+/**
+ * @typedef {Object} module:crypto/algorithms/base.DecryptionResult
+ *
+ * @property {Object} result decrypted payload (with properties 'type',
+ *     'content').
+ *
+ * @property {Object<string, string>} keysClaimed keys that the sender of the
+ *     event claims ownership of: map from key type to base64-encoded key
+ *
+ * @property {Object<string, string>} keysProved keys that the sender of the
+ *     event is known to have ownership of: map from key type to base64-encoded
+ *     key
+ */
+
 /**
  * Decrypt an event
  *
@@ -117,7 +131,8 @@ module.exports.DecryptionAlgorithm = DecryptionAlgorithm;
  *
  * @param {object} event raw event
  *
- * @return {object} decrypted payload (with properties 'type', 'content')
+ * @return {null} if the event referred to an unknown megolm session
+ * @return {module:crypto/algorithms/base.DecryptionResult} decryption result
  *
  * @throws {module:crypto/algorithms/base.DecryptionError} if there is a
  *   problem decrypting the event

lib/crypto/algorithms/megolm.js

@@ -398,8 +398,8 @@ utils.inherits(MegolmDecryption, base.DecryptionAlgorithm);
  *
  * @param {object} event raw event
  *
- * @return {object} object with 'result' key with decrypted payload (with
- *  properties 'type', 'content') and a 'sessionExists' key.
+ * @return {null} The event referred to an unknown megolm session
+ * @return {module:crypto/algorithms/base.DecryptionResult} decryption result
  *
  * @throws {module:crypto/algorithms/base.DecryptionError} if there is a
  *   problem decrypting the event
@@ -417,12 +417,10 @@ MegolmDecryption.prototype.decryptEvent = function(event) {
         var res = this._olmDevice.decryptGroupMessage(
             event.room_id, content.sender_key, content.session_id, content.ciphertext
         );
-        if (res.sessionExists) {
+        if (res !== null) {
             res.result = JSON.parse(res.result);
-            return res;
-        } else {
-            return {sessionExists: false};
         }
+        return res;
     } catch (e) {
         throw new base.DecryptionError(e);
     }

lib/crypto/algorithms/olm.js

@@ -153,9 +153,7 @@ utils.inherits(OlmDecryption, base.DecryptionAlgorithm);
  *
  * @param {object} event raw event
  *
- * @return {object} result object with result property with the decrypted
- *  payload (with properties 'type', 'content'), and a "sessionExists" key
- *  always set to true.
+ * @return {module:crypto/algorithms/base.DecryptionResult} decryption result
  *
  * @throws {module:crypto/algorithms/base.DecryptionError} if there is a
  *   problem decrypting the event

lib/crypto/index.js

@@ -869,8 +869,9 @@ Crypto.prototype.decryptEvent = function(event) {
         olmDevice: this._olmDevice,
     });
     var r = alg.decryptEvent(event);
-    var payload = r.result;
-    if (r.sessionExists) {
+
+    if (r !== null) {
+        var payload = r.result;
         payload.keysClaimed = r.keysClaimed;
         payload.keysProved = r.keysProved;
         return payload;