Merge pull request #198 from matrix-org/rav/refactor_crypto

Move crypto bits into a subdirectory

lib/crypto/OlmDevice.js

@@ -18,11 +18,11 @@ limitations under the License.
 /**
  * olm.js wrapper
  *
- * @module OlmDevice
+ * @module crypto/OlmDevice
  */
 
 var Olm = require("olm");
-var utils = require("./utils");
+var utils = require("../utils");
 
 /**
  * Manages the olm cryptography functions. Each OlmDevice has a single
@@ -31,7 +31,7 @@ var utils = require("./utils");
  * Accounts and sessions are kept pickled in a sessionStore.
  *
  * @constructor
- * @alias module:OlmDevice
+ * @alias module:crypto/OlmDevice
  *
  * @param {Object} sessionStore A store to be used for data in end-to-end
  *    crypto

lib/crypto/algorithms/base.js

@@ -18,23 +18,23 @@ limitations under the License.
 /**
  * Internal module. Defines the base classes of the encryption implementations
  *
- * @module crypto-algorithms/base
+ * @module crypto/algorithms/base
  */
-var utils = require("../utils");
+var utils = require("../../utils");
 
 /**
  * map of registered encryption algorithm classes. A map from string to {@link
- * module:crypto-algorithms/base.EncryptionAlgorithm|EncryptionAlgorithm} class
+ * module:crypto/algorithms/base.EncryptionAlgorithm|EncryptionAlgorithm} class
  *
- * @type {Object.<string, function(new: module:crypto-algorithms/base.EncryptionAlgorithm)>}
+ * @type {Object.<string, function(new: module:crypto/algorithms/base.EncryptionAlgorithm)>}
  */
 module.exports.ENCRYPTION_CLASSES = {};
 
 /**
  * map of registered encryption algorithm classes. Map from string to {@link
- * module:crypto-algorithms/base.DecryptionAlgorithm|DecryptionAlgorithm} class
+ * module:crypto/algorithms/base.DecryptionAlgorithm|DecryptionAlgorithm} class
  *
- * @type {Object.<string, function(new: module:crypto-algorithms/base.DecryptionAlgorithm)>}
+ * @type {Object.<string, function(new: module:crypto/algorithms/base.DecryptionAlgorithm)>}
  */
 module.exports.DECRYPTION_CLASSES = {};
 
@@ -42,12 +42,12 @@ module.exports.DECRYPTION_CLASSES = {};
  * base type for encryption implementations
  *
  * @constructor
- * @alias module:crypto-algorithms/base.EncryptionAlgorithm
+ * @alias module:crypto/algorithms/base.EncryptionAlgorithm
  *
  * @param {object} params parameters
  * @param {string} params.deviceId The identifier for this device.
  * @param {module:crypto} params.crypto crypto core
- * @param {module:OlmDevice} params.olmDevice olm.js wrapper
+ * @param {module:crypto/OlmDevice} params.olmDevice olm.js wrapper
  * @param {module:base-apis~MatrixBaseApis} baseApis base matrix api interface
  * @param {string} params.roomId  The ID of the room we will be sending to
  */
@@ -64,7 +64,7 @@ module.exports.EncryptionAlgorithm = EncryptionAlgorithm;
 /**
  * Encrypt a message event
  *
- * @method module:crypto-algorithms/base.EncryptionAlgorithm#encryptMessage
+ * @method module:crypto/algorithms/base.EncryptionAlgorithm#encryptMessage
  * @abstract
  *
  * @param {module:models/room} room
@@ -86,10 +86,10 @@ EncryptionAlgorithm.prototype.onRoomMembership = function(event, member) {};
  * base type for decryption implementations
  *
  * @constructor
- * @alias module:crypto-algorithms/base.DecryptionAlgorithm
+ * @alias module:crypto/algorithms/base.DecryptionAlgorithm
  *
  * @param {object} params parameters
- * @param {module:OlmDevice} params.olmDevice olm.js wrapper
+ * @param {module:crypto/OlmDevice} params.olmDevice olm.js wrapper
  */
 var DecryptionAlgorithm = function(params) {
     this._olmDevice = params.olmDevice;
@@ -100,21 +100,21 @@ module.exports.DecryptionAlgorithm = DecryptionAlgorithm;
 /**
  * Decrypt an event
  *
- * @method module:crypto-algorithms/base.DecryptionAlgorithm#decryptEvent
+ * @method module:crypto/algorithms/base.DecryptionAlgorithm#decryptEvent
  * @abstract
  *
  * @param {object} event raw event
  *
  * @return {object} decrypted payload (with properties 'type', 'content')
  *
- * @throws {module:crypto-algorithms/base.DecryptionError} if there is a
+ * @throws {module:crypto/algorithms/base.DecryptionError} if there is a
  *   problem decrypting the event
  */
 
 /**
  * Handle a key event
  *
- * @method module:crypto-algorithms/base.DecryptionAlgorithm#onRoomKeyEvent
+ * @method module:crypto/algorithms/base.DecryptionAlgorithm#onRoomKeyEvent
  *
  * @param {module:models/event.MatrixEvent} event key event
  */
@@ -140,11 +140,11 @@ utils.inherits(module.exports.DecryptionError, Error);
  * @param {string} algorithm algorithm tag to register for
  *
  * @param {class} encryptor {@link
- *     module:crypto-algorithms/base.EncryptionAlgorithm|EncryptionAlgorithm}
+ *     module:crypto/algorithms/base.EncryptionAlgorithm|EncryptionAlgorithm}
  *     implementation
  *
  * @param {class} decryptor {@link
- *     module:crypto-algorithms/base.DecryptionAlgorithm|DecryptionAlgorithm}
+ *     module:crypto/algorithms/base.DecryptionAlgorithm|DecryptionAlgorithm}
  *     implementation
  */
 module.exports.registerAlgorithm = function(algorithm, encryptor, decryptor) {

lib/crypto/algorithms/index.js

@@ -16,7 +16,7 @@ limitations under the License.
 "use strict";
 
 /**
- * @module crypto-algorithms
+ * @module crypto/algorithms
  */
 
 var base = require("./base");
@@ -25,16 +25,16 @@ require("./olm");
 require("./megolm");
 
 /**
- * @see module:crypto-algorithms/base.ENCRYPTION_CLASSES
+ * @see module:crypto/algorithms/base.ENCRYPTION_CLASSES
  */
 module.exports.ENCRYPTION_CLASSES = base.ENCRYPTION_CLASSES;
 
 /**
- * @see module:crypto-algorithms/base.DECRYPTION_CLASSES
+ * @see module:crypto/algorithms/base.DECRYPTION_CLASSES
  */
 module.exports.DECRYPTION_CLASSES = base.DECRYPTION_CLASSES;
 
 /**
- * @see module:crypto-algorithms/base.DecryptionError
+ * @see module:crypto/algorithms/base.DecryptionError
  */
 module.exports.DecryptionError = base.DecryptionError;

lib/crypto/algorithms/megolm.js

@@ -18,12 +18,12 @@ limitations under the License.
 /**
  * Defines m.olm encryption/decryption
  *
- * @module crypto-algorithms/megolm
+ * @module crypto/algorithms/megolm
  */
 
 var q = require("q");
 
-var utils = require("../utils");
+var utils = require("../../utils");
 var olmlib = require("../olmlib");
 var base = require("./base");
 
@@ -31,10 +31,10 @@ var base = require("./base");
  * Megolm encryption implementation
  *
  * @constructor
- * @extends {module:crypto-algorithms/base.EncryptionAlgorithm}
+ * @extends {module:crypto/algorithms/base.EncryptionAlgorithm}
  *
  * @param {object} params parameters, as per
- *     {@link module:crypto-algorithms/base.EncryptionAlgorithm}
+ *     {@link module:crypto/algorithms/base.EncryptionAlgorithm}
  */
 function MegolmEncryption(params) {
     base.EncryptionAlgorithm.call(this, params);
@@ -211,10 +211,10 @@ MegolmEncryption.prototype.onRoomMembership = function(event, member) {
  * Megolm decryption implementation
  *
  * @constructor
- * @extends {module:crypto-algorithms/base.DecryptionAlgorithm}
+ * @extends {module:crypto/algorithms/base.DecryptionAlgorithm}
  *
  * @param {object} params parameters, as per
- *     {@link module:crypto-algorithms/base.DecryptionAlgorithm}
+ *     {@link module:crypto/algorithms/base.DecryptionAlgorithm}
  */
 function MegolmDecryption(params) {
     base.DecryptionAlgorithm.call(this, params);
@@ -228,7 +228,7 @@ utils.inherits(MegolmDecryption, base.DecryptionAlgorithm);
  *
  * @return {object} decrypted payload (with properties 'type', 'content')
  *
- * @throws {module:crypto-algorithms/base.DecryptionError} if there is a
+ * @throws {module:crypto/algorithms/base.DecryptionError} if there is a
  *   problem decrypting the event
  */
 MegolmDecryption.prototype.decryptEvent = function(event) {

lib/crypto/algorithms/olm.js

@@ -18,13 +18,13 @@ limitations under the License.
 /**
  * Defines m.olm encryption/decryption
  *
- * @module crypto-algorithms/olm
+ * @module crypto/algorithms/olm
  */
 var q = require('q');
 
-var utils = require("../utils");
+var utils = require("../../utils");
 var olmlib = require("../olmlib");
-var DeviceInfo = require("../crypto-deviceinfo");
+var DeviceInfo = require("../deviceinfo");
 var DeviceVerification = DeviceInfo.DeviceVerification;
 
 
@@ -34,10 +34,10 @@ var base = require("./base");
  * Olm encryption implementation
  *
  * @constructor
- * @extends {module:crypto-algorithms/base.EncryptionAlgorithm}
+ * @extends {module:crypto/algorithms/base.EncryptionAlgorithm}
  *
  * @param {object} params parameters, as per
- *     {@link module:crypto-algorithms/base.EncryptionAlgorithm}
+ *     {@link module:crypto/algorithms/base.EncryptionAlgorithm}
  */
 function OlmEncryption(params) {
     base.EncryptionAlgorithm.call(this, params);
@@ -128,9 +128,9 @@ OlmEncryption.prototype.encryptMessage = function(room, eventType, content) {
  * Olm decryption implementation
  *
  * @constructor
- * @extends {module:crypto-algorithms/base.DecryptionAlgorithm}
+ * @extends {module:crypto/algorithms/base.DecryptionAlgorithm}
  * @param {object} params parameters, as per
- *     {@link module:crypto-algorithms/base.DecryptionAlgorithm}
+ *     {@link module:crypto/algorithms/base.DecryptionAlgorithm}
  */
 function OlmDecryption(params) {
     base.DecryptionAlgorithm.call(this, params);
@@ -144,7 +144,7 @@ utils.inherits(OlmDecryption, base.DecryptionAlgorithm);
  *
  * @return {object} decrypted payload (with properties 'type', 'content')
  *
- * @throws {module:crypto-algorithms/base.DecryptionError} if there is a
+ * @throws {module:crypto/algorithms/base.DecryptionError} if there is a
  *   problem decrypting the event
  */
 OlmDecryption.prototype.decryptEvent = function(event) {

lib/crypto/deviceinfo.js

@@ -17,14 +17,14 @@ limitations under the License.
 
 
 /**
- * @module crypto-deviceinfo
+ * @module crypto/deviceinfo
  */
 
 /**
   * Information about a user's device
   *
   * @constructor
-  * @alias module:crypto-deviceinfo
+  * @alias module:crypto/deviceinfo
   *
   * @property {string} deviceId the ID of this device
   *
@@ -33,7 +33,7 @@ limitations under the License.
   * @property {Object.<string,string>} keys a map from
   *      &lt;key type&gt;:&lt;id&gt; -> &lt;base64-encoded key&gt;>
   *
-  * @property {module:crypto-deviceinfo.DeviceVerification} verified
+  * @property {module:crypto/deviceinfo.DeviceVerification} verified
   *     whether the device has been verified by the user
   *
   * @property {Object} unsigned  additional data from the homeserver

lib/crypto/index.js

@@ -23,17 +23,16 @@ limitations under the License.
 var anotherjson = require('another-json');
 var q = require("q");
 
-var utils = require("./utils");
+var utils = require("../utils");
 var OlmDevice = require("./OlmDevice");
 var olmlib = require("./olmlib");
-var algorithms = require("./crypto-algorithms");
+var algorithms = require("./algorithms");
-var DeviceInfo = require("./crypto-deviceinfo");
+var DeviceInfo = require("./deviceinfo");
 var DeviceVerification = DeviceInfo.DeviceVerification;
 
 /**
  * Cryptography bits
  *
- * @alias module:crypto.Crypto
  * @constructor
  * @alias module:crypto
  *
@@ -198,7 +197,7 @@ function _uploadOneTimeKeys(crypto) {
  * @param {bool} forceDownload Always download the keys even if cached.
  *
  * @return {Promise} A promise which resolves to a map userId->deviceId->{@link
- * module:crypto-deviceinfo|DeviceInfo}.
+ * module:crypto/deviceinfo|DeviceInfo}.
  */
 Crypto.prototype.downloadKeys = function(userIds, forceDownload) {
     var self = this;
@@ -371,7 +370,7 @@ function _storeDeviceKeys(_olmDevice, userId, deviceId, userStore, deviceResult)
  *
  * @param {string} userId the user to list keys for.
  *
- * @return {module:crypto-deviceinfo[]} list of devices
+ * @return {module:crypto/deviceinfo[]} list of devices
  */
 Crypto.prototype.getStoredDevicesForUser = function(userId) {
     var devs = this._sessionStore.getEndToEndDevicesForUser(userId);
@@ -434,7 +433,7 @@ Crypto.prototype.listDeviceKeys = function(userId) {
  * @param {string} algorithm  encryption algorithm
  * @param {string} sender_key curve25519 key to match
  *
- * @return {module:crypto-deviceinfo?}
+ * @return {module:crypto/deviceinfo?}
  */
 Crypto.prototype.getDeviceByIdentityKey = function(userId, algorithm, sender_key) {
     if (
@@ -521,7 +520,8 @@ Crypto.prototype.setDeviceVerification = function(userId, deviceId, verified, bl
  * <p>
  * Returns a map from device id to an object with keys 'deviceIdKey' (the
  * device's curve25519 identity key) and 'sessions' (an array of objects in the
- * same format as that returned by {@link module:OlmDevice#getSessionInfoForDevice}).
+ * same format as that returned by
+ * {@link module:crypto/OlmDevice#getSessionInfoForDevice}).
  * <p>
  * This method is provided for debugging purposes.
  *
@@ -619,7 +619,7 @@ Crypto.prototype.setRoomEncryption = function(roomId, config) {
 
 /**
  * @typedef {Object} module:crypto~OlmSessionResult
- * @property {module:crypto-deviceinfo} device  device info
+ * @property {module:crypto/deviceinfo} device  device info
  * @property {string?} sessionId base64 olm session id; null if no session
  *    could be established
  */
@@ -863,7 +863,7 @@ Crypto.prototype._onRoomMembership = function(event, member) {
 };
 
 /**
- * @see module:crypto-algorithms/base.DecryptionError
+ * @see module:crypto/algorithms/base.DecryptionError
  */
 Crypto.DecryptionError = algorithms.DecryptionError;
 

lib/crypto/olmlib.js

@@ -20,7 +20,7 @@ limitations under the License.
  * Utilities common to olm encryption algorithms
  */
 
-var utils = require("./utils");
+var utils = require("../utils");
 
 /**
  * matrix algorithm tag for olm
@@ -37,7 +37,7 @@ module.exports.MEGOLM_ALGORITHM = "m.megolm.v1.aes-sha2";
  * Encrypt an event payload for a list of devices
  *
  * @param {string} ourDeviceId
- * @param {module:OlmDevice} olmDevice olm.js wrapper
+ * @param {module:crypto/OlmDevice} olmDevice olm.js wrapper
  * @param {string[]} participantKeys list of curve25519 keys to encrypt for
  * @param {object} payloadFields fields to include in the encrypted payload
  *