v0.6.4

Change version back so npm can change it back again
There is now one change
2016-11-04 10:00:09 +00:00 · 2016-11-04 09:59:49 +00:00 · 2016-11-04 09:57:37 +00:00 · 2016-11-04 09:42:08 +00:00 · 2016-11-04 09:20:17 +00:00 · 2016-11-04 09:20:17 +00:00
54 changed files with 2466 additions and 217664 deletions
@@ -1,5 +1,3 @@
-# Keep this file in sync with .npmignore.
-
 .jsdoc
 node_modules
 .lock-wscript
@@ -8,7 +6,7 @@ coverage
 lib-cov
 out
 reports
-dist/browser-matrix-dev.js
+/dist

 # version file and tarball created by 'npm pack'
 /git-revision.txt
@@ -1,15 +0,0 @@
-# Keep this file in sync with .gitignore.
-
-.jsdoc
-node_modules
-.lock-wscript
-build/Release
-coverage
-lib-cov
-out
-reports
-dist/browser-matrix-dev.js
-
-# tarball created by 'npm pack'.
-/matrix-js-sdk-*.tgz
-
@@ -1,3 +1,176 @@
+Changes in [0.6.4](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v0.6.4) (2016-11-04)
+================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v0.6.4-rc.2...v0.6.4)
+
+ * Change release script to pass version by environment variable
+
+
+Changes in [0.6.4-rc.2](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v0.6.4-rc.2) (2016-11-02)
+==========================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v0.6.4-rc.1...v0.6.4-rc.2)
+
+ * Add getRoomTags method to client
+   [\#236](https://github.com/matrix-org/matrix-js-sdk/pull/236)
+
+Changes in [0.6.4-rc.1](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v0.6.4-rc.1) (2016-11-02)
+==========================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v0.6.3...v0.6.4-rc.1)
+
+Breaking Changes
+----------------
+ * Bundled version of the JS SDK are no longer versioned along with
+   source files in the dist/ directory. As of this release, they
+   will be included in the release tarball, but not the source
+   repository.
+
+Other Changes
+-------------
+ * More fixes to the release script
+   [\#272](https://github.com/matrix-org/matrix-js-sdk/pull/272)
+ * Update the release process to use github releases
+   [\#271](https://github.com/matrix-org/matrix-js-sdk/pull/271)
+ * Don't package the world when we release
+   [\#270](https://github.com/matrix-org/matrix-js-sdk/pull/270)
+ * Add ability to set a filter prior to the first /sync
+   [\#269](https://github.com/matrix-org/matrix-js-sdk/pull/269)
+ * Sign one-time keys, and verify their signatures
+   [\#243](https://github.com/matrix-org/matrix-js-sdk/pull/243)
+ * Check for duplicate message indexes for group messages
+   [\#241](https://github.com/matrix-org/matrix-js-sdk/pull/241)
+ * Rotate megolm sessions
+   [\#240](https://github.com/matrix-org/matrix-js-sdk/pull/240)
+ * Check recipient and sender in Olm messages
+   [\#239](https://github.com/matrix-org/matrix-js-sdk/pull/239)
+ * Consistency checks for E2E device downloads
+   [\#237](https://github.com/matrix-org/matrix-js-sdk/pull/237)
+ * Support User-Interactive auth for delete device
+   [\#235](https://github.com/matrix-org/matrix-js-sdk/pull/235)
+ * Utility to help with interactive auth
+   [\#234](https://github.com/matrix-org/matrix-js-sdk/pull/234)
+ * Fix sync breaking when an invalid filterId is in localStorage
+   [\#228](https://github.com/matrix-org/matrix-js-sdk/pull/228)
+
+Changes in [0.6.3](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v0.6.3) (2016-10-12)
+================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v0.6.2...v0.6.3)
+
+Breaking Changes
+----------------
+ * Add a 'RECONNECTING' state to the sync states. This is an additional state
+   between 'SYNCING' and 'ERROR', so most clients should not notice.
+
+Other Changes
+----------------
+ * Fix params getting replaced on register calls
+   [\#233](https://github.com/matrix-org/matrix-js-sdk/pull/233)
+ * Fix potential 30s delay on reconnect
+   [\#232](https://github.com/matrix-org/matrix-js-sdk/pull/232)
+ * uploadContent: Attempt some consistency between browser and node
+   [\#230](https://github.com/matrix-org/matrix-js-sdk/pull/230)
+ * Fix error handling on uploadContent
+   [\#229](https://github.com/matrix-org/matrix-js-sdk/pull/229)
+ * Fix uploadContent for node.js
+   [\#226](https://github.com/matrix-org/matrix-js-sdk/pull/226)
+ * Don't emit ERROR until a keepalive poke fails
+   [\#223](https://github.com/matrix-org/matrix-js-sdk/pull/223)
+ * Function to get the fallback url for interactive auth
+   [\#224](https://github.com/matrix-org/matrix-js-sdk/pull/224)
+ * Revert "Handle the first /sync failure differently."
+   [\#222](https://github.com/matrix-org/matrix-js-sdk/pull/222)
+
+Changes in [0.6.2](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v0.6.2) (2016-10-05)
+================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v0.6.1...v0.6.2)
+
+ * Check dependencies aren't on develop in release.sh
+   [\#221](https://github.com/matrix-org/matrix-js-sdk/pull/221)
+ * Fix checkTurnServers leak on logout
+   [\#220](https://github.com/matrix-org/matrix-js-sdk/pull/220)
+ * Fix leak of file upload objects
+   [\#219](https://github.com/matrix-org/matrix-js-sdk/pull/219)
+ * crypto: remove duplicate code
+   [\#218](https://github.com/matrix-org/matrix-js-sdk/pull/218)
+ * Add API for 3rd party location lookup
+   [\#217](https://github.com/matrix-org/matrix-js-sdk/pull/217)
+ * Handle the first /sync failure differently.
+   [\#216](https://github.com/matrix-org/matrix-js-sdk/pull/216)
+
+Changes in [0.6.1](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v0.6.1) (2016-09-21)
+================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v0.6.0...v0.6.1)
+
+ * Fix the ed25519 key checking
+   [\#215](https://github.com/matrix-org/matrix-js-sdk/pull/215)
+ * Add MatrixClient.getEventSenderDeviceInfo()
+   [\#214](https://github.com/matrix-org/matrix-js-sdk/pull/214)
+
+Changes in [0.6.0](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v0.6.0) (2016-09-21)
+================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v0.5.6...v0.6.0)
+
+ * Pull user device list on join
+   [\#212](https://github.com/matrix-org/matrix-js-sdk/pull/212)
+ * Fix sending of oh_hais on bad sessions
+   [\#213](https://github.com/matrix-org/matrix-js-sdk/pull/213)
+ * Support /publicRooms pagination
+   [\#211](https://github.com/matrix-org/matrix-js-sdk/pull/211)
+ * Update the olm library version to 1.3.0
+   [\#205](https://github.com/matrix-org/matrix-js-sdk/pull/205)
+ * Comment what the logic in uploadKeys does
+   [\#209](https://github.com/matrix-org/matrix-js-sdk/pull/209)
+ * Include keysProved and keysClaimed in the local echo for events we send.
+   [\#210](https://github.com/matrix-org/matrix-js-sdk/pull/210)
+ * Check if we need to upload new one-time keys every 10 minutes
+   [\#208](https://github.com/matrix-org/matrix-js-sdk/pull/208)
+ * Reset oneTimeKey to null on each loop iteration.
+   [\#207](https://github.com/matrix-org/matrix-js-sdk/pull/207)
+ * Add getKeysProved and getKeysClaimed methods to MatrixEvent.
+   [\#206](https://github.com/matrix-org/matrix-js-sdk/pull/206)
+ * Send a 'm.new_device' when we get a message for an unknown group session
+   [\#204](https://github.com/matrix-org/matrix-js-sdk/pull/204)
+ * Introduce EventTimelineSet, filtered timelines and global notif timeline.
+   [\#196](https://github.com/matrix-org/matrix-js-sdk/pull/196)
+ * Wrap the crypto event handlers in try/catch blocks
+   [\#203](https://github.com/matrix-org/matrix-js-sdk/pull/203)
+ * Show warnings on to-device decryption fail
+   [\#202](https://github.com/matrix-org/matrix-js-sdk/pull/202)
+ * s/Displayname/DisplayName/
+   [\#201](https://github.com/matrix-org/matrix-js-sdk/pull/201)
+ * OH HAI
+   [\#200](https://github.com/matrix-org/matrix-js-sdk/pull/200)
+ * Share the current ratchet with new members
+   [\#199](https://github.com/matrix-org/matrix-js-sdk/pull/199)
+ * Move crypto bits into a subdirectory
+   [\#198](https://github.com/matrix-org/matrix-js-sdk/pull/198)
+ * Refactor event handling in Crypto
+   [\#197](https://github.com/matrix-org/matrix-js-sdk/pull/197)
+ * Don't create Olm sessions proactively
+   [\#195](https://github.com/matrix-org/matrix-js-sdk/pull/195)
+ * Use to-device events for key sharing
+   [\#194](https://github.com/matrix-org/matrix-js-sdk/pull/194)
+ * README: callbacks deprecated
+   [\#193](https://github.com/matrix-org/matrix-js-sdk/pull/193)
+ * Fix sender verification for megolm messages
+   [\#192](https://github.com/matrix-org/matrix-js-sdk/pull/192)
+ * Use `ciphertext` instead of `body` in megolm events
+   [\#191](https://github.com/matrix-org/matrix-js-sdk/pull/191)
+ * Add debug methods to get the state of OlmSessions
+   [\#189](https://github.com/matrix-org/matrix-js-sdk/pull/189)
+ * MatrixClient.getStoredDevicesForUser
+   [\#190](https://github.com/matrix-org/matrix-js-sdk/pull/190)
+ * Olm-related cleanups
+   [\#188](https://github.com/matrix-org/matrix-js-sdk/pull/188)
+ * Update to fixed olmlib
+   [\#187](https://github.com/matrix-org/matrix-js-sdk/pull/187)
+ * always play audio out of the remoteAudioElement if it exists.
+   [\#186](https://github.com/matrix-org/matrix-js-sdk/pull/186)
+ * Fix exceptions where HTMLMediaElement loads and plays race
+   [\#185](https://github.com/matrix-org/matrix-js-sdk/pull/185)
+ * Reset megolm session when people join/leave the room
+   [\#183](https://github.com/matrix-org/matrix-js-sdk/pull/183)
+ * Fix exceptions when dealing with redactions
+   [\#184](https://github.com/matrix-org/matrix-js-sdk/pull/184)
+
 Changes in [0.5.6](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v0.5.6) (2016-08-28)
 ================================================================================================
 [Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v0.5.5...v0.5.6)
@@ -0,0 +1,4 @@
+Contributing code to matrix-js-sdk
+==================================
+
+matrix-js-sdk follows the same pattern as https://github.com/matrix-org/synapse/blob/master/CONTRIBUTING.rst
@@ -10,9 +10,10 @@ Quickstart

 In a browser
 ------------
-Copy ``dist/$VERSION/browser-matrix-$VERSION.js`` and add that as a ``<script>`` to
-your page. There will be a global variable ``matrixcs`` attached to
-``window`` through which you can access the SDK.
+Download either the full or minified version from
+https://github.com/matrix-org/matrix-js-sdk/releases/latest and add that as a
+``<script>`` to your page. There will be a global variable ``matrixcs``
+attached to ``window`` through which you can access the SDK.

 Please check [the working browser example](examples/browser) for more information.

@@ -1 +0,0 @@
-Release builds and development builds will reside here.
@@ -28,4 +28,6 @@ rm -f matrix-js-sdk-*.tgz
 npm pack ||
    fail "npm pack finished with return code $?"

+npm run gendoc || fail "JSDoc failed with code $?"
+
 exit $RC
@@ -136,10 +136,12 @@ MatrixBaseApis.prototype.register = function(
    var params = {
        auth: auth
    };
-    if (username !== undefined) { params.username = username; }
-    if (password !== undefined) { params.password = password; }
-    if (bindEmail !== undefined) { params.bind_email = bindEmail; }
-    if (guestAccessToken !== undefined) { params.guest_access_token = guestAccessToken; }
+    if (username !== undefined && username !== null) { params.username = username; }
+    if (password !== undefined && password !== null) { params.password = password; }
+    if (bindEmail !== undefined && bindEmail !== null) { params.bind_email = bindEmail; }
+    if (guestAccessToken !== undefined && guestAccessToken !== null) {
+        params.guest_access_token = guestAccessToken;
+    }

    return this.registerRequest(params, undefined, callback);
 };
@@ -290,6 +292,23 @@ MatrixBaseApis.prototype.deactivateAccount = function(auth, callback) {
    );
 };

+/**
+ * Get the fallback URL to use for unknown interactive-auth stages.
+ *
+ * @param {string} loginType     the type of stage being attempted
+ * @param {string} authSessionId the auth session ID provided by the homeserver
+ *
+ * @return {string} HS URL to hit to for the fallback interface
+ */
+MatrixBaseApis.prototype.getFallbackAuthUrl = function(loginType, authSessionId) {
+    var path = utils.encodeUri("/auth/$loginType/fallback/web", {
+        $loginType: loginType,
+    });
+
+    return this._http.getUrl(path, {
+        session: authSessionId,
+    }, httpApi.PREFIX_R0);
+};

 // Room operations
 // ===============
@@ -415,12 +434,39 @@ MatrixBaseApis.prototype.roomInitialSync = function(roomId, limit, callback) {
 // =========================

 /**
+ * @param {string} options.server The remote server to query for the room list.
+ *                                Optional. If unspecified, get the local home
+ *                                server's public room list.
+ * @param {number} options.limit Maximum number of entries to return
+ * @param {string} options.since Token to paginate from
+ * @param {object} options.filter Filter parameters
+ * @param {string} options.filter.generic_search_term String to search for
 * @param {module:client.callback} callback Optional.
 * @return {module:client.Promise} Resolves: TODO
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 */
-MatrixBaseApis.prototype.publicRooms = function(callback) {
-    return this._http.authedRequest(callback, "GET", "/publicRooms");
+MatrixBaseApis.prototype.publicRooms = function(options, callback) {
+    if (typeof(options) == 'function') {
+        callback = options;
+        options = {};
+    }
+    if (options === undefined) {
+        options = {};
+    }
+
+    var query_params = {};
+    if (options.server) {
+        query_params.server = options.server;
+        delete options.server;
+    }
+
+    if (Object.keys(options).length === 0 && Object.keys(query_params).length === 0) {
+        return this._http.authedRequest(callback, "GET", "/publicRooms");
+    } else {
+        return this._http.authedRequest(
+            callback, "POST", "/publicRooms", query_params, options
+        );
+    }
 };

 /**
@@ -530,13 +576,38 @@ MatrixBaseApis.prototype.setRoomDirectoryVisibility =

 /**
 * Upload a file to the media repository on the home server.
- * @param {File} file object
- * @param {module:client.callback} callback Optional.
- * @return {module:client.Promise} Resolves: TODO
- * @return {module:http-api.MatrixError} Rejects: with an error response.
+ *
+ * @param {object} file The object to upload. On a browser, something that
+ *   can be sent to XMLHttpRequest.send (typically a File).  Under node.js,
+ *   a a Buffer, String or ReadStream.
+ *
+ * @param {object} opts  options object
+ *
+ * @param {string=} opts.name   Name to give the file on the server. Defaults
+ *   to <tt>file.name</tt>.
+ *
+ * @param {string=} opts.type   Content-type for the upload. Defaults to
+ *   <tt>file.type</tt>, or <tt>applicaton/octet-stream</tt>.
+ *
+ * @param {boolean=} opts.rawResponse Return the raw body, rather than
+ *   parsing the JSON. Defaults to false (except on node.js, where it
+ *   defaults to true for backwards compatibility).
+ *
+ * @param {boolean=} opts.onlyContentUri Just return the content URI,
+ *   rather than the whole body. Defaults to false (except on browsers,
+ *   where it defaults to true for backwards compatibility). Ignored if
+ *   opts.rawResponse is true.
+ *
+ * @param {Function=} opts.callback Deprecated. Optional. The callback to
+ *    invoke on success/failure. See the promise return values for more
+ *    information.
+ *
+ * @return {module:client.Promise} Resolves to response object, as
+ *    determined by this.opts.onlyData, opts.rawResponse, and
+ *    opts.onlyContentUri.  Rejects with an error (usually a MatrixError).
 */
-MatrixBaseApis.prototype.uploadContent = function(file, callback) {
-    return this._http.uploadContent(file, callback);
+MatrixBaseApis.prototype.uploadContent = function(file, opts) {
+    return this._http.uploadContent(file, opts);
 };

 /**
@@ -678,16 +749,23 @@ MatrixBaseApis.prototype.setDeviceDetails = function(device_id, body) {
 * Delete the given device
 *
 * @param {string} device_id  device to delete
+ * @param {object} auth Optional. Auth data to supply for User-Interactive auth.
 * @return {module:client.Promise} Resolves: result object
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 */
-MatrixBaseApis.prototype.deleteDevice = function(device_id) {
+MatrixBaseApis.prototype.deleteDevice = function(device_id, auth) {
    var path = utils.encodeUri("/devices/$device_id", {
        $device_id: device_id,
    });

+    var body = {};
+
+    if (auth) {
+        body.auth = auth;
+    }
+
    return this._http.authedRequestWithPrefix(
-        undefined, "DELETE", path, undefined, undefined,
+        undefined, "DELETE", path, undefined, body,
        httpApi.PREFIX_UNSTABLE
    );
 };
@@ -898,24 +976,28 @@ MatrixBaseApis.prototype.downloadKeysForUsers = function(userIds, callback) {
 *
 * @param {string[][]} devices  a list of [userId, deviceId] pairs
 *
- * @param {module:client.callback=} callback
+ * @param {string} [key_algorithm = signed_curve25519]  desired key type
 *
 * @return {module:client.Promise} Resolves: result object. Rejects: with
 *     an error response ({@link module:http-api.MatrixError}).
 */
-MatrixBaseApis.prototype.claimOneTimeKeys = function(devices, callback) {
+MatrixBaseApis.prototype.claimOneTimeKeys = function(devices, key_algorithm) {
    var queries = {};

+    if (key_algorithm === undefined) {
+        key_algorithm = "signed_curve25519";
+    }
+
    for (var i = 0; i < devices.length; ++i) {
        var userId = devices[i][0];
        var deviceId = devices[i][1];
        var query = queries[userId] || {};
        queries[userId] = query;
-        query[deviceId] = "curve25519";
+        query[deviceId] = key_algorithm;
    }
    var content = {one_time_keys: queries};
    return this._http.authedRequestWithPrefix(
-        callback, "POST", "/keys/claim", undefined, content,
+        undefined, "POST", "/keys/claim", undefined, content,
        httpApi.PREFIX_UNSTABLE
    );
 };
@@ -1012,6 +1094,39 @@ MatrixBaseApis.prototype.sendToDevice = function(
    );
 };

+// Third party Lookup API
+// ======================
+
+/**
+ * Get the third party protocols that can be reached using
+ * this HS
+ * @return {module:client.Promise} Resolves to the result object
+ */
+MatrixBaseApis.prototype.getThirdpartyProtocols = function() {
+    return this._http.authedRequestWithPrefix(
+        undefined, "GET", "/thirdparty/protocols", undefined, undefined,
+        httpApi.PREFIX_UNSTABLE
+    );
+};
+
+/**
+ * Get information on how a specific place on a third party protocol
+ * may be reached.
+ * @param {string} protocol The protocol given in getThirdpartyProtocols()
+ * @param {object} params Protocol-specific parameters, as given in th
+ *                        response to getThirdpartyProtocols()
+ * @return {module:client.Promise} Resolves to the result object
+ */
+MatrixBaseApis.prototype.getThirdpartyLocation = function(protocol, params) {
+    var path = utils.encodeUri("/thirdparty/location/$protocol", {
+        $protocol: protocol
+    });
+
+    return this._http.authedRequestWithPrefix(
+        undefined, "GET", path, params, undefined,
+        httpApi.PREFIX_UNSTABLE
+    );
+};

 /**
 * MatrixBaseApis object
@@ -401,6 +401,21 @@ function _setDeviceVerification(client, userId, deviceId, verified, blocked) {
    client.emit("deviceVerificationChanged", userId, deviceId);
 }

+/**
+ * Get e2e information on the device that sent an event
+ *
+ * @param {MatrixEvent} event event to be checked
+ *
+ * @return {module:crypto/deviceinfo?}
+ */
+MatrixClient.prototype.getEventSenderDeviceInfo = function(event) {
+    if (!this._crypto) {
+        return null;
+    }
+
+    return this._crypto.getEventSenderDeviceInfo(event);
+};
+
 /**
 * Check if the sender of an event is verified
 *
@@ -410,21 +425,11 @@ function _setDeviceVerification(client, userId, deviceId, verified, blocked) {
 * {@link module:client~MatrixClient#setDeviceVerified|setDeviceVerified}.
 */
 MatrixClient.prototype.isEventSenderVerified = function(event) {
-    if (!this._crypto) {
+    var device = this.getEventSenderDeviceInfo(event);
+    if (!device) {
        return false;
    }
-
-    var sender_key = event.getSenderKey();
-
-    if (!sender_key) {
-        return false;
-    }
-
-    var algorithm = event.getWireContent().algorithm;
-
-    return this._crypto.isSenderKeyVerified(
-        event.getSender(), algorithm, sender_key
-    );
+    return device.isVerified();
 };

 /**
@@ -460,32 +465,38 @@ MatrixClient.prototype.isRoomEncrypted = function(roomId) {
 * @param {MatrixClient} client
 * @param {object} raw event
 *
- * @return {object} decrypted payload (with properties 'type', 'content')
+ * @return {MatrixEvent}
 */
-function _decryptMessage(client, event) {
+function _decryptEvent(client, event) {
    if (!client._crypto) {
        return _badEncryptedMessage(event, "**Encryption not enabled**");
    }

+    var decryptionResult;
    try {
-        return client._crypto.decryptEvent(event);
+        decryptionResult = client._crypto.decryptEvent(event);
    } catch (e) {
        if (!(e instanceof Crypto.DecryptionError)) {
            throw e;
        }
        return _badEncryptedMessage(event, "**" + e.message + "**");
    }
+    return new MatrixEvent(
+        event, decryptionResult.payload,
+        decryptionResult.keysProved,
+        decryptionResult.keysClaimed
+    );
 }

 function _badEncryptedMessage(event, reason) {
-    return {
+    return new MatrixEvent(event, {
        type: "m.room.message",
        content: {
            msgtype: "m.bad.encrypted",
            body: reason,
            content: event.content,
        },
-    };
+    });
 }

 // Room ops
@@ -685,6 +696,22 @@ MatrixClient.prototype.setRoomTopic = function(roomId, topic, callback) {
                               undefined, callback);
 };

+/**
+ * @param {string} roomId
+ * @param {module:client.callback} callback Optional.
+ * @return {module:client.Promise} Resolves: TODO
+ * @return {module:http-api.MatrixError} Rejects: with an error response.
+ */
+MatrixClient.prototype.getRoomTags = function(roomId, callback) {
+    var path = utils.encodeUri("/user/$userId/rooms/$roomId/tags/", {
+        $userId: this.credentials.userId,
+        $roomId: roomId,
+    });
+    return this._http.authedRequest(
+        callback, "GET", path, undefined
+    );
+};
+
 /**
 * @param {string} roomId
 * @param {string} tagName name of room tag to be set
@@ -2384,7 +2411,26 @@ MatrixClient.prototype.getOrCreateFilter = function(filterName, filter) {
            }
            // debuglog("Existing filter ID %s: %s; new filter: %s",
            //          filterId, JSON.stringify(oldDef), JSON.stringify(newDef));
-            return;
+            self.store.setFilterIdByName(filterName, undefined);
+            return undefined;
+        }, function(error) {
+            // Synapse currently returns the following when the filter cannot be found:
+            // {
+            //     errcode: "M_UNKNOWN",
+            //     name: "M_UNKNOWN",
+            //     message: "No row found",
+            //     data: Object, httpStatus: 404
+            // }
+            if (error.httpStatus === 404 &&
+                (error.errcode === "M_UNKNOWN" || error.errcode === "M_NOT_FOUND")) {
+                // Clear existing filterId from localStorage
+                // if it no longer exists on the server
+                self.store.setFilterIdByName(filterName, undefined);
+                // Return a undefined value for existingId further down the promise chain
+                return undefined;
+            } else {
+                throw error;
+            }
        });
    }

@@ -2481,6 +2527,9 @@ MatrixClient.prototype.getTurnServers = function() {
 *
 * @param {Number=} opts.pollTimeout The number of milliseconds to wait on /events.
 * Default: 30000 (30 seconds).
+ *
+ * @param {Filter=} opts.filter The filter to apply to /sync calls. This will override
+ * the opts.initialSyncLimit, which would normally result in a timeline limit filter.
 */
 MatrixClient.prototype.startClient = function(opts) {
    if (this.clientRunning) {
@@ -2532,6 +2581,7 @@ MatrixClient.prototype.stopClient = function() {
    if (this._crypto) {
        global.clearInterval(this._uploadIntervalID);
    }
+    global.clearTimeout(this._checkTurnServersTimeoutID);
 };

 function setupCallEventHandler(client) {
@@ -2751,13 +2801,15 @@ function checkTurnServers(client) {
            };
            client._turnServers = [servers];
            // re-fetch when we're about to reach the TTL
-            setTimeout(function() { checkTurnServers(client); },
-                (res.ttl || (60 * 60)) * 1000 * 0.9
-            );
+            client._checkTurnServersTimeoutID =
+                setTimeout(function() { checkTurnServers(client); },
+                           (res.ttl || (60 * 60)) * 1000 * 0.9
+                          );
        }
    }, function(err) {
        console.error("Failed to get TURN URIs");
-        setTimeout(function() { checkTurnServers(client); }, 60000);
+        client._checkTurnServersTimeoutID =
+            setTimeout(function() { checkTurnServers(client); }, 60000);
    });
 }

@@ -2777,12 +2829,10 @@ function _resolve(callback, defer, res) {

 function _PojoToMatrixEventMapper(client) {
    function mapper(plainOldJsObject) {
-        var clearData;
        if (plainOldJsObject.type === "m.room.encrypted") {
-            clearData = _decryptMessage(client, plainOldJsObject);
+            return _decryptEvent(client, plainOldJsObject);
        }
-        var matrixEvent = new MatrixEvent(plainOldJsObject, clearData);
-        return matrixEvent;
+        return new MatrixEvent(plainOldJsObject);
    }
    return mapper;
 }
@@ -2855,6 +2905,9 @@ module.exports.CRYPTO_ENABLED = CRYPTO_ENABLED;
 * the server for updates. This may be called multiple times even if the state is
 * already ERROR. <i>This is the equivalent of "syncError" in the previous
 * API.</i></li>
+ * <li>RECONNECTING: The sync connedtion has dropped, but not in a way that should
+ * be considered erroneous.
+ * </li>
 * <li>STOPPED: The client has stopped syncing with server due to stopClient
 * being called.
 * </li>
@@ -2864,8 +2917,10 @@ module.exports.CRYPTO_ENABLED = CRYPTO_ENABLED;
 *                                          +---->STOPPED
 *                                          |
 *              +----->PREPARED -------> SYNCING <--+
- *              |        ^                  |       |
- *   null ------+        |  +---------------+       |
+ *              |        ^                  ^       |
+ *              |        |                  |       |
+ *              |        |                  V       |
+ *   null ------+        |  +-RECONNECTING<-+       |
 *              |        |  V                       |
 *              +------->ERROR ---------------------+
 *
@@ -58,6 +58,18 @@ function OlmDevice(sessionStore) {
    // we don't bother stashing outboundgroupsessions in the sessionstore -
    // instead we keep them here.
    this._outboundGroupSessionStore = {};
+
+    // Store a set of decrypted message indexes for each group session.
+    // This partially mitigates a replay attack where a MITM resends a group
+    // message into the room.
+    //
+    // TODO: If we ever remove an event from memory we will also need to remove
+    // it from this map. Otherwise if we download the event from the server we
+    // will think that it is a duplicate.
+    //
+    // Keys are strings of form "<senderKey>|<session_id>|<message_index>"
+    // Values are true.
+    this._inboundGroupSessionMessageIndexes = {};
 }

 function _initialise_account(sessionStore, pickleKey, account) {
@@ -260,7 +272,8 @@ OlmDevice.prototype.createOutboundSession = function(
 * @param {number} message_type  message_type field from the received message (must be 0)
 * @param {string} ciphertext base64-encoded body from the received message
 *
- * @return {string} decrypted payload
+ * @return {{payload: string, session_id: string}} decrypted payload, and
+ *     session id of new session
 *
 * @raises {Error} if the received message was not valid (for instance, it
 *     didn't use a valid one-time key).
@@ -284,7 +297,10 @@ OlmDevice.prototype.createInboundSession = function(

            self._saveSession(theirDeviceIdentityKey, session);

-            return payloadString;
+            return {
+                payload: payloadString,
+                session_id: session.session_id(),
+            };
        } finally {
            session.free();
        }
@@ -370,6 +386,10 @@ OlmDevice.prototype.encryptMessage = function(
 ) {
    var self = this;

+    if (payloadString === undefined) {
+        throw new Error("payloadString undefined");
+    }
+
    return this._getSession(theirDeviceIdentityKey, sessionId, function(session) {
        var res = session.encrypt(payloadString);
        self._saveSession(theirDeviceIdentityKey, session);
@@ -386,12 +406,7 @@ OlmDevice.prototype.encryptMessage = function(
 * @param {number} message_type  message_type field from the received message
 * @param {string} ciphertext base64-encoded body from the received message
 *
- * @return {object} Result, with keys <ul>
- *   <li><tt>matchesInbound</tt>: (boolean): true if the message was a pre-key
- *      message which matched an existing inbound session.</li>
- *   <li><tt>payload</tt>: (string): decrypted payload; null if the received
- *     message was not valid (for instance, it did not match this session).</li>
- * </ul>
+ * @return {string} decrypted payload.
 */
 OlmDevice.prototype.decryptMessage = function(
    theirDeviceIdentityKey, sessionId, message_type, ciphertext
@@ -399,28 +414,38 @@ OlmDevice.prototype.decryptMessage = function(
    var self = this;

    return this._getSession(theirDeviceIdentityKey, sessionId, function(session) {
-        var matchesInbound = (message_type === 0 &&
-                              session.matches_inbound(ciphertext));
-
-        var payloadString = null;
-        try {
-            payloadString = session.decrypt(message_type, ciphertext);
-        } catch (e) {
-            console.log(
-                "Failed to decrypt with an existing session: " + e.message
-            );
-            // return null as the payload
-        }
-
+        var payloadString = session.decrypt(message_type, ciphertext);
        self._saveSession(theirDeviceIdentityKey, session);

-        return {
-            matchesInbound: matchesInbound,
-            payload: payloadString,
-        };
+        return payloadString;
    });
 };

+/**
+ * Determine if an incoming messages is a prekey message matching an existing session
+ *
+ * @param {string} theirDeviceIdentityKey Curve25519 identity key for the
+ *     remote device
+ * @param {string} sessionId  the id of the active session
+ * @param {number} message_type  message_type field from the received message
+ * @param {string} ciphertext base64-encoded body from the received message
+ *
+ * @return {boolean} true if the received message is a prekey message which matches
+ *    the given session.
+ */
+OlmDevice.prototype.matchesSession = function(
+    theirDeviceIdentityKey, sessionId, message_type, ciphertext
+) {
+    if (message_type !== 0) {
+        return false;
+    }
+
+    return this._getSession(theirDeviceIdentityKey, sessionId, function(session) {
+        return session.matches_inbound(ciphertext);
+    });
+};
+
+

 // Outbound group session
 // ======================
@@ -548,11 +573,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, Object<string, string>): T} func
+ *   function to call. Second argument is the map of keys claimed by the session.
+ *
+ * @return {null} the sessionId is unknown
+ *
+ * @return {T} result of func
+ *
 * @private
+ * @template {T}
 */
 OlmDevice.prototype._getInboundGroupSession = function(
    roomId, senderKey, sessionId, func
@@ -562,7 +591,7 @@ OlmDevice.prototype._getInboundGroupSession = function(
    );

    if (r === null) {
-        return {sessionExists: false};
+        return null;
    }

    r = JSON.parse(r);
@@ -579,12 +608,7 @@ OlmDevice.prototype._getInboundGroupSession = function(
    var session = new Olm.InboundGroupSession();
    try {
        session.unpickle(this._pickleKey, r.session);
-        return {
-            sessionExists: true,
-            result: func(session),
-            keysProved: {curve25519: senderKey},
-            keysClaimed: r.keysClaimed || {},
-        };
+        return func(session, r.keysClaimed || {});
    } finally {
        session.free();
    }
@@ -596,11 +620,11 @@ OlmDevice.prototype._getInboundGroupSession = function(
 * @param {string} roomId     room in which this session will be used
 * @param {string} senderKey  base64-encoded curve25519 key of the sender
 * @param {string} sessionId  session identifier
- * @param {string} sessionKey base64-encoded secret key at index chainIndex
- * @param {number} chainIndex index at which sessionKey applies
+ * @param {string} sessionKey base64-encoded secret key
+ * @param {Object<string, string>} keysClaimed Other keys the sender claims.
 */
 OlmDevice.prototype.addInboundGroupSession = function(
-    roomId, senderKey, sessionId, sessionKey, chainIndex
+    roomId, senderKey, sessionId, sessionKey, keysClaimed
 ) {
    var self = this;
    var session = new Olm.InboundGroupSession();
@@ -611,7 +635,9 @@ OlmDevice.prototype.addInboundGroupSession = function(
                "Mismatched group session ID from senderKey: " + senderKey
            );
        }
-        self._saveInboundGroupSession(roomId, senderKey, sessionId, session);
+        self._saveInboundGroupSession(
+            roomId, senderKey, sessionId, session, keysClaimed
+        );
    } finally {
        session.free();
    }
@@ -625,19 +651,47 @@ 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
 ) {
    var self = this;

-    function decrypt(session) {
+    function decrypt(session, keysClaimed) {
        var res = session.decrypt(body);
+
+        var plaintext = res.plaintext;
+        if (plaintext === undefined) {
+            // Compatibility for older olm versions.
+            plaintext = res;
+        } else {
+            // Check if we have seen this message index before to detect replay attacks.
+            var messageIndexKey = senderKey + "|" + sessionId + "|" + res.message_index;
+            if (messageIndexKey in self._inboundGroupSessionMessageIndexes) {
+                throw new Error(
+                    "Duplicate message index, possible replay attack: " +
+                    messageIndexKey
+                );
+            }
+            self._inboundGroupSessionMessageIndexes[messageIndexKey] = true;
+        }
+
+        // the sender must have had the senderKey to persuade us to save the
+        // session.
+        var keysProved = {curve25519: senderKey};
+
        self._saveInboundGroupSession(
-            roomId, senderKey, sessionId, session
+            roomId, senderKey, sessionId, session, keysClaimed
        );
-        return res;
+        return {
+            result: plaintext,
+            keysClaimed: keysClaimed,
+            keysProved: keysProved,
+        };
    }

    return this._getInboundGroupSession(
@@ -45,13 +45,16 @@ module.exports.DECRYPTION_CLASSES = {};
 * @alias module:crypto/algorithms/base.EncryptionAlgorithm
 *
 * @param {object} params parameters
+ * @param {string} params.userId  The UserID for the local user
 * @param {string} params.deviceId The identifier for this device.
 * @param {module:crypto} params.crypto crypto core
 * @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
+ * @param {object} params.config  The body of the m.room.encryption event
 */
 var EncryptionAlgorithm = function(params) {
+    this._userId = params.userId;
    this._deviceId = params.deviceId;
    this._crypto = params.crypto;
    this._olmDevice = params.olmDevice;
@@ -101,9 +104,11 @@ EncryptionAlgorithm.prototype.onNewDevice = function(userId, deviceId) {};
 * @alias module:crypto/algorithms/base.DecryptionAlgorithm
 *
 * @param {object} params parameters
+ * @param {string} params.userId  The UserID for the local user
 * @param {module:crypto/OlmDevice} params.olmDevice olm.js wrapper
 */
 var DecryptionAlgorithm = function(params) {
+    this._userId = params.userId;
    this._olmDevice = params.olmDevice;
 };
 /** */
@@ -117,7 +122,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.DecryptionResult} decryption result
 *
 * @throws {module:crypto/algorithms/base.DecryptionError} if there is a
 *   problem decrypting the event
@@ -27,6 +27,52 @@ var utils = require("../../utils");
 var olmlib = require("../olmlib");
 var base = require("./base");

+/**
+ * @private
+ * @constructor
+ *
+ * @param {string} sessionId
+ *
+ * @property {string} sessionId
+ * @property {Number} useCount     number of times this session has been used
+ * @property {Number} creationTime when the session was created (ms since the epoch)
+ * @property {module:client.Promise?} sharePromise  If a share operation is in progress,
+ *    a promise which resolves when it is complete.
+ */
+function OutboundSessionInfo(sessionId) {
+    this.sessionId = sessionId;
+    this.useCount = 0;
+    this.creationTime = new Date().getTime();
+    this.sharePromise = null;
+}
+
+
+/**
+ * Check if it's time to rotate the session
+ *
+ * @param {Number} rotationPeriodMsgs
+ * @param {Number} rotationPeriodMs
+ * @return {Boolean}
+ */
+OutboundSessionInfo.prototype.needsRotation = function(
+    rotationPeriodMsgs, rotationPeriodMs
+) {
+    var sessionLifetime = new Date().getTime() - this.creationTime;
+
+    if (this.useCount >= rotationPeriodMsgs ||
+        sessionLifetime >= rotationPeriodMs
+       ) {
+        console.log(
+            "Rotating megolm session after " + this.useCount +
+                " messages, " + sessionLifetime + "ms"
+        );
+        return true;
+    }
+
+    return false;
+};
+
+
 /**
 * Megolm encryption implementation
 *
@@ -38,15 +84,28 @@ var base = require("./base");
 */
 function MegolmEncryption(params) {
    base.EncryptionAlgorithm.call(this, params);
-    this._prepPromise = null;
-    this._outboundSessionId = null;
-    this._discardNewSession = false;
+
+    // OutboundSessionInfo. Null if we haven't yet started setting one up. Note
+    // that even if this is non-null, it may not be ready for use (in which
+    // case _outboundSession.sharePromise will be non-null.)
+    this._outboundSession = null;

    // devices which have joined since we last sent a message.
    // userId -> {deviceId -> true}, or
    // userId -> true
    this._devicesPendingKeyShare = {};
-    this._sharePromise = null;
+
+    // default rotation periods
+    this._sessionRotationPeriodMsgs = 100;
+    this._sessionRotationPeriodMs = 7 * 24 * 3600 * 1000;
+
+    if (params.config.rotation_period_ms !== undefined) {
+        this._sessionRotationPeriodMs = params.config.rotation_period_ms;
+    }
+
+    if (params.config.rotation_period_msgs !== undefined) {
+        this._sessionRotationPeriodMsgs = params.config.rotation_period_msgs;
+    }
 }
 utils.inherits(MegolmEncryption, base.EncryptionAlgorithm);

@@ -55,34 +114,27 @@ utils.inherits(MegolmEncryption, base.EncryptionAlgorithm);
 *
 * @param {module:models/room} room
 *
- * @return {module:client.Promise} Promise which resolves to the megolm
- *   sessionId when setup is complete.
+ * @return {module:client.Promise} Promise which resolves to the
+ *    OutboundSessionInfo when setup is complete.
 */
 MegolmEncryption.prototype._ensureOutboundSession = function(room) {
    var self = this;

-    if (this._prepPromise) {
-        // prep already in progress
-        return this._prepPromise;
-    }
-
-    var sessionId = this._outboundSessionId;
+    var session = this._outboundSession;

    // need to make a brand new session?
-    if (!sessionId) {
-        this._prepPromise = this._prepareNewSession(room).
-            finally(function() {
-                self._prepPromise = null;
-            });
-        return this._prepPromise;
+    if (!session || session.needsRotation(self._sessionRotationPeriodMsgs,
+                                          self._sessionRotationPeriodMs)
+       ) {
+        this._outboundSession = session = this._prepareNewSession(room);
    }

-    if (this._sharePromise) {
+    if (session.sharePromise) {
        // key share already in progress
-        return this._sharePromise;
+        return session.sharePromise;
    }

-    // prep already done, but check for new devices
+    // no share in progress: check for new devices
    var shareMap = this._devicesPendingKeyShare;
    this._devicesPendingKeyShare = {};

@@ -99,15 +151,15 @@ MegolmEncryption.prototype._ensureOutboundSession = function(room) {
        }
    }

-    this._sharePromise = this._shareKeyWithDevices(
-        sessionId, shareMap
+    session.sharePromise = this._shareKeyWithDevices(
+        session.sessionId, shareMap
    ).finally(function() {
-        self._sharePromise = null;
+        session.sharePromise = null;
    }).then(function() {
-        return sessionId;
+        return session;
    });

-    return this._sharePromise;
+    return session.sharePromise;
 };

 /**
@@ -115,8 +167,7 @@ MegolmEncryption.prototype._ensureOutboundSession = function(room) {
 *
 * @param {module:models/room} room
 *
- * @return {module:client.Promise} Promise which resolves to the megolm
- *   sessionId when setup is complete.
+ * @return {module:crypto/algorithms/megolm.OutboundSessionInfo} session
 */
 MegolmEncryption.prototype._prepareNewSession = function(room) {
    var session_id = this._olmDevice.createOutboundGroupSession();
@@ -124,13 +175,15 @@ MegolmEncryption.prototype._prepareNewSession = function(room) {

    this._olmDevice.addInboundGroupSession(
        this._roomId, this._olmDevice.deviceCurve25519Key, session_id,
-        key.key
+        key.key, {ed25519: this._olmDevice.deviceEd25519Key}
    );

    // we're going to share the key with all current members of the room,
    // so we can reset this.
    this._devicesPendingKeyShare = {};

+    var session = new OutboundSessionInfo(session_id);
+
    var roomMembers = utils.map(room.getJoinedMembers(), function(u) {
        return u.userId;
    });
@@ -145,31 +198,28 @@ MegolmEncryption.prototype._prepareNewSession = function(room) {

    // TODO: we need to give the user a chance to block any devices or users
    // before we send them the keys; it's too late to download them here.
-    return this._crypto.downloadKeys(
+    session.sharePromise = this._crypto.downloadKeys(
        roomMembers, false
    ).then(function(res) {
        return self._shareKeyWithDevices(session_id, shareMap);
    }).then(function() {
-        if (self._discardNewSession) {
-            // we've had cause to reset the session_id since starting this process.
-            // we'll use the current session for any currently pending events, but
-            // don't save it as the current _outboundSessionId, so that new events
-            // will use a new session.
-            console.log("Session generation complete, but discarding");
-        } else {
-            self._outboundSessionId = session_id;
-        }
-        return session_id;
+        return session;
    }).finally(function() {
-        self._discardNewSession = false;
+        session.sharePromise = null;
    });
+
+    return session;
 };

 /**
 * @private
 *
 * @param {string} session_id
+ *
 * @param {Object<string, Object<string, boolean>|boolean>} shareMap
+ *    Map from userid to either: true (meaning this is a new user in the room,
+ *    so all of his devices need the keys); or a map from deviceid to true
+ *    (meaning this user has one or more new devices, which need the keys).
 *
 * @return {module:client.Promise} Promise which resolves once the key sharing
 *     message has been sent.
@@ -189,6 +239,9 @@ MegolmEncryption.prototype._shareKeyWithDevices = function(session_id, shareMap)
        }
    };

+    // we downloaded the user's device list when they joined the room, or when
+    // the new device announced itself, so there is no need to do so now.
+
    return self._crypto.ensureOlmSessionsForUsers(
        utils.keys(shareMap)
    ).then(function(devicemap) {
@@ -201,10 +254,10 @@ MegolmEncryption.prototype._shareKeyWithDevices = function(session_id, shareMap)
            }

            var devicesToShareWith = shareMap[userId];
-            var deviceInfos = devicemap[userId];
+            var sessionResults = devicemap[userId];

-            for (var deviceId in deviceInfos) {
-                if (!deviceInfos.hasOwnProperty(deviceId)) {
+            for (var deviceId in sessionResults) {
+                if (!sessionResults.hasOwnProperty(deviceId)) {
                    continue;
                }

@@ -215,23 +268,49 @@ MegolmEncryption.prototype._shareKeyWithDevices = function(session_id, shareMap)
                    continue;
                }

+                var sessionResult = sessionResults[deviceId];
+                if (!sessionResult.sessionId) {
+                    // no session with this device, probably because there
+                    // were no one-time keys.
+                    //
+                    // we could send them a to_device message anyway, as a
+                    // signal that they have missed out on the key sharing
+                    // message because of the lack of keys, but there's not
+                    // much point in that really; it will mostly serve to clog
+                    // up to_device inboxes.
+                    //
+                    // ensureOlmSessionsForUsers has already done the logging,
+                    // so just skip it.
+                    continue;
+                }
+
                console.log(
                    "sharing keys with device " + userId + ":" + deviceId
                );

-                var deviceInfo = deviceInfos[deviceId].device;
+                var deviceInfo = sessionResult.device;
+
+                var encryptedContent = {
+                    algorithm: olmlib.OLM_ALGORITHM,
+                    sender_key: self._olmDevice.deviceCurve25519Key,
+                    ciphertext: {},
+                };
+
+                olmlib.encryptMessageForDevice(
+                    encryptedContent.ciphertext,
+                    self._userId,
+                    self._deviceId,
+                    self._olmDevice,
+                    userId,
+                    deviceInfo,
+                    payload
+                );

                if (!contentMap[userId]) {
                    contentMap[userId] = {};
                }

-                contentMap[userId][deviceId] =
-                    olmlib.encryptMessageForDevices(
-                        self._deviceId,
-                        self._olmDevice,
-                        [deviceInfo.getIdentityKey()],
-                        payload
-                    );
+                contentMap[userId][deviceId] = encryptedContent;
                haveTargets = true;
            }
        }
@@ -256,7 +335,7 @@ MegolmEncryption.prototype._shareKeyWithDevices = function(session_id, shareMap)
 */
 MegolmEncryption.prototype.encryptMessage = function(room, eventType, content) {
    var self = this;
-    return this._ensureOutboundSession(room).then(function(session_id) {
+    return this._ensureOutboundSession(room).then(function(session) {
        var payloadJson = {
            room_id: self._roomId,
            type: eventType,
@@ -264,19 +343,20 @@ MegolmEncryption.prototype.encryptMessage = function(room, eventType, content) {
        };

        var ciphertext = self._olmDevice.encryptGroupMessage(
-            session_id, JSON.stringify(payloadJson)
+            session.sessionId, JSON.stringify(payloadJson)
        );

        var encryptedContent = {
            algorithm: olmlib.MEGOLM_ALGORITHM,
            sender_key: self._olmDevice.deviceCurve25519Key,
            ciphertext: ciphertext,
-            session_id: session_id,
+            session_id: session.sessionId,
             // Include our device ID so that recipients can send us a
             // m.new_device message if they don't have our session key.
            device_id: self._deviceId,
        };

+        session.useCount++;
        return encryptedContent;
    });
 };
@@ -289,11 +369,15 @@ MegolmEncryption.prototype.encryptMessage = function(room, eventType, content) {
 * @param {string=} oldMembership  previous membership
 */
 MegolmEncryption.prototype.onRoomMembership = function(event, member, oldMembership) {
+    // if we haven't yet made a session, there's nothing to do here.
+    if (!this._outboundSession) {
+        return;
+    }
+
    var newMembership = member.membership;

    if (newMembership === 'join') {
-        // new member in the room.
-        this._devicesPendingKeyShare[member.userId] = true;
+        this._onNewRoomMember(member.userId);
        return;
    }

@@ -303,21 +387,31 @@ MegolmEncryption.prototype.onRoomMembership = function(event, member, oldMembers
    }

    // otherwise we assume the user is leaving, and start a new outbound session.
-    if (this._outboundSessionId) {
-        console.log("Discarding outbound megolm session due to change in " +
-                    "membership of " + member.userId + " (" + oldMembership +
-                    "->" + newMembership + ")");
-        this._outboundSessionId = null;
-    }
+    console.log("Discarding outbound megolm session due to change in " +
+                "membership of " + member.userId + " (" + oldMembership +
+                "->" + newMembership + ")");

-    if (this._prepPromise) {
-        console.log("Discarding as-yet-incomplete megolm session due to " +
-                    "change in membership of " + member.userId + " (" +
-                    oldMembership + "->" + newMembership + ")");
-        this._discardNewSession = true;
-    }
+    // this ensures that we will start a new session on the next message.
+    this._outboundSession = null;
 };

+/**
+ * handle a new user joining a room
+ *
+ * @param {string} userId   new member
+ */
+MegolmEncryption.prototype._onNewRoomMember = function(userId) {
+    // make sure we have a list of this user's devices. We are happy to use a
+    // cached version here: we assume that if we already have a list of the
+    // user's devices, then we already share an e2e room with them, which means
+    // that they will have announced any new devices via an m.new_device.
+    this._crypto.downloadKeys([userId], false).done();
+
+    // also flag this user up for needing a keyshare.
+    this._devicesPendingKeyShare[userId] = true;
+};
+
+
 /**
 * @inheritdoc
 *
@@ -359,8 +453,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.DecryptionResult} decryption result
 *
 * @throws {module:crypto/algorithms/base.DecryptionError} if there is a
 *   problem decrypting the event
@@ -368,28 +462,41 @@ utils.inherits(MegolmDecryption, base.DecryptionAlgorithm);
 MegolmDecryption.prototype.decryptEvent = function(event) {
    var content = event.content;

-    console.log("decrypting " + event.event_id + " with sid " +
-                content.session_id);
-
    if (!content.sender_key || !content.session_id ||
        !content.ciphertext
       ) {
        throw new base.DecryptionError("Missing fields in input");
    }

+    var res;
    try {
-        var res = this._olmDevice.decryptGroupMessage(
+        res = this._olmDevice.decryptGroupMessage(
            event.room_id, content.sender_key, content.session_id, content.ciphertext
        );
-        if (res.sessionExists) {
-            res.result = JSON.parse(res.result);
-            return res;
-        } else {
-            return {sessionExists: false};
-        }
    } catch (e) {
        throw new base.DecryptionError(e);
    }
+
+    if (res === null) {
+        return null;
+    }
+
+    var payload = JSON.parse(res.result);
+
+    // belt-and-braces check that the room id matches that indicated by the HS
+    // (this is somewhat redundant, since the megolm session is scoped to the
+    // room, so neither the sender nor a MITM can lie about the room_id).
+    if (payload.room_id !== event.room_id) {
+        throw new base.DecryptionError(
+            "Message intended for room " + payload.room_id
+        );
+    }
+
+    return {
+        payload: payload,
+        keysClaimed: res.keysClaimed,
+        keysProved: res.keysProved,
+    };
 };

 /**
@@ -95,43 +95,43 @@ OlmEncryption.prototype.encryptMessage = function(room, eventType, content) {

    var self = this;
    return this._ensureSession(users).then(function() {
-        var participantKeys = [];
+        var payloadFields = {
+            room_id: room.roomId,
+            type: eventType,
+            content: content,
+        };
+
+        var encryptedContent = {
+            algorithm: olmlib.OLM_ALGORITHM,
+            sender_key: self._olmDevice.deviceCurve25519Key,
+            ciphertext: {},
+        };
+
        for (var i = 0; i < users.length; ++i) {
            var userId = users[i];
            var devices = self._crypto.getStoredDevicesForUser(userId);
+
            for (var j = 0; j < devices.length; ++j) {
                var deviceInfo = devices[j];
                var key = deviceInfo.getIdentityKey();
                if (key == self._olmDevice.deviceCurve25519Key) {
-                    // don't bother setting up session to ourself
+                    // don't bother sending to ourself
                    continue;
                }
                if (deviceInfo.verified == DeviceVerification.BLOCKED) {
                    // don't bother setting up sessions with blocked users
                    continue;
                }
-                participantKeys.push(key);
+
+                olmlib.encryptMessageForDevice(
+                    encryptedContent.ciphertext,
+                    self._userId, self._deviceId, self._olmDevice,
+                    userId, deviceInfo, payloadFields
+                );
            }
        }

-        return olmlib.encryptMessageForDevices(
-            self._deviceId, self._olmDevice, participantKeys, {
-                room_id: room.roomId,
-                type: eventType,
-                content: content,
-                // Include the ED25519 key so that the recipient knows what
-                // device this message came from.
-                // We don't need to include the curve25519 key since the
-                // recipient will already know this from the olm headers.
-                // When combined with the device keys retrieved from the
-                // homeserver signed by the ed25519 key this proves that
-                // the curve25519 key and the ed25519 key are owned by
-                // the same device.
-                keys: {
-                    "ed25519": self._olmDevice.deviceEd25519Key
-                },
-            }
-        );
+        return encryptedContent;
    });
 };

@@ -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.DecryptionResult} decryption result
 *
 * @throws {module:crypto/algorithms/base.DecryptionError} if there is a
 *   problem decrypting the event
@@ -169,58 +167,176 @@ OlmDecryption.prototype.decryptEvent = function(event) {
        throw new base.DecryptionError("Missing ciphertext");
    }

-    if (!(this._olmDevice.deviceCurve25519Key in content.ciphertext)) {
+    if (!(this._olmDevice.deviceCurve25519Key in ciphertext)) {
        throw new base.DecryptionError("Not included in recipients");
    }
+    var message = ciphertext[this._olmDevice.deviceCurve25519Key];
+    var payloadString;

-    var message = content.ciphertext[this._olmDevice.deviceCurve25519Key];
-    var sessionIds = this._olmDevice.getSessionIdsForDevice(deviceKey);
-    var payloadString = null;
-    var foundSession = false;
-    for (var i = 0; i < sessionIds.length; i++) {
-        var sessionId = sessionIds[i];
-        var res = this._olmDevice.decryptMessage(
-            deviceKey, sessionId, message.type, message.body
+    try {
+        payloadString = this._decryptMessage(deviceKey, message);
+    } catch (e) {
+        console.warn(
+            "Failed to decrypt Olm event (id=" +
+                event.event_id + ") from " + deviceKey +
+                ": " + e.message
        );
-        payloadString = res.payload;
-        if (payloadString) {
-            console.log("decrypted with sessionId " + sessionId);
-            break;
-        }
-
-        if (res.matchesInbound) {
-            // this was a prekey message which matched this session; don't
-            // create a new session.
-            foundSession = true;
-            break;
-        }
-    }
-
-    if (message.type === 0 && !foundSession && payloadString === null) {
-        try {
-            payloadString = this._olmDevice.createInboundSession(
-                deviceKey, message.type, message.body
-            );
-            console.log("created new inbound sesion");
-        } catch (e) {
-            // Failed to decrypt with a new session.
-            console.warn("Failed to decrypt message with new session", e);
-        }
-    }
-
-    // TODO: Check the sender user id matches the sender key.
-    // TODO: check the room_id and fingerprint
-    if (payloadString !== null) {
-        var payload = JSON.parse(payloadString);
-        return {
-            result: payload,
-            sessionExists: true,
-            keysProved: {curve25519: deviceKey},
-            keysClaimed: payload.keys || {}
-        };
-    } else {
        throw new base.DecryptionError("Bad Encrypted Message");
    }
+
+    var payload = JSON.parse(payloadString);
+
+    // check that we were the intended recipient, to avoid unknown-key attack
+    // https://github.com/vector-im/vector-web/issues/2483
+    if (payload.recipient === undefined) {
+        // older versions of riot did not set this field, so we cannot make
+        // this check. TODO: kill this off once our users have updated
+        console.warn(
+            "Olm event (id=" + event.event_id + ") contains no 'recipient' " +
+             "property; cannot prevent unknown-key attack");
+    } else if (payload.recipient != this._userId) {
+        console.warn(
+            "Event " + event.event_id + ": Intended recipient " +
+            payload.recipient + " does not match our id " + this._userId
+        );
+        throw new base.DecryptionError(
+            "Message was intented for " + payload.recipient
+        );
+    }
+
+    if (payload.recipient_keys === undefined) {
+        // ditto
+        console.warn(
+            "Olm event (id=" + event.event_id + ") contains no " +
+            "'recipient_keys' property; cannot prevent unknown-key attack");
+    } else if (payload.recipient_keys.ed25519 !=
+               this._olmDevice.deviceEd25519Key) {
+        console.warn(
+            "Event " + event.event_id + ": Intended recipient ed25519 key " +
+            payload.recipient_keys.ed25519 + " did not match ours"
+        );
+        throw new base.DecryptionError("Message not intended for this device");
+    }
+
+    // check that the original sender matches what the homeserver told us, to
+    // avoid people masquerading as others.
+    // (this check is also provided via the sender's embedded ed25519 key,
+    // which is checked elsewhere).
+    if (payload.sender === undefined) {
+        // ditto
+        console.warn(
+            "Olm event (id=" + event.event_id + ") contains no " +
+            "'sender' property; cannot prevent unknown-key attack");
+    } else if (payload.sender != event.sender) {
+        console.warn(
+            "Event " + event.event_id + ": original sender " + payload.sender +
+            " does not match reported sender " + event.sender
+        );
+        throw new base.DecryptionError(
+            "Message forwarded from " + payload.sender
+        );
+    }
+
+    // Olm events intended for a room have a room_id.
+    if (payload.room_id !== event.room_id) {
+        console.warn(
+            "Event " + event.event_id + ": original room " + payload.room_id +
+            " does not match reported room " + event.room_id
+        );
+        throw new base.DecryptionError(
+            "Message intended for room " + payload.room_id
+        );
+    }
+
+    return {
+        payload: payload,
+        sessionExists: true,
+        keysProved: {curve25519: deviceKey},
+        keysClaimed: payload.keys || {}
+    };
 };

+
+/**
+ * Attempt to decrypt an Olm message
+ *
+ * @param {string} theirDeviceIdentityKey  Curve25519 identity key of the sender
+ * @param {object} message  message object, with 'type' and 'body' fields
+ *
+ * @return {string} payload, if decrypted successfully.
+ */
+OlmDecryption.prototype._decryptMessage = function(theirDeviceIdentityKey, message) {
+    var sessionIds = this._olmDevice.getSessionIdsForDevice(theirDeviceIdentityKey);
+
+    // try each session in turn.
+    var decryptionErrors = {};
+    for (var i = 0; i < sessionIds.length; i++) {
+        var sessionId = sessionIds[i];
+        try {
+            var payload = this._olmDevice.decryptMessage(
+                theirDeviceIdentityKey, sessionId, message.type, message.body
+            );
+            console.log(
+                "Decrypted Olm message from " + theirDeviceIdentityKey +
+                    " with session " + sessionId
+            );
+            return payload;
+        } catch (e) {
+            var foundSession = this._olmDevice.matchesSession(
+                theirDeviceIdentityKey, sessionId, message.type, message.body
+            );
+
+            if (foundSession) {
+                // decryption failed, but it was a prekey message matching this
+                // session, so it should have worked.
+                throw new Error(
+                    "Error decrypting prekey message with existing session id " +
+                        sessionId + ": " + e.message
+                );
+            }
+
+            // otherwise it's probably a message for another session; carry on, but
+            // keep a record of the error
+            decryptionErrors[sessionId] = e.message;
+        }
+    }
+
+    if (message.type !== 0) {
+        // not a prekey message, so it should have matched an existing session, but it
+        // didn't work.
+
+        if (sessionIds.length === 0) {
+            throw new Error("No existing sessions");
+        }
+
+        throw new Error(
+            "Error decrypting non-prekey message with existing sessions: " +
+                JSON.stringify(decryptionErrors)
+        );
+    }
+
+    // prekey message which doesn't match any existing sessions: make a new
+    // session.
+
+    var res;
+    try {
+        res = this._olmDevice.createInboundSession(
+            theirDeviceIdentityKey, message.type, message.body
+        );
+    } catch (e) {
+        decryptionErrors["(new)"] = e.message;
+        throw new Error(
+            "Error decrypting prekey message: " +
+                JSON.stringify(decryptionErrors)
+        );
+    }
+
+    console.log(
+        "created new inbound Olm session ID " +
+            res.session_id + " with " + theirDeviceIdentityKey
+    );
+    return res.payload;
+};
+
+
 base.registerAlgorithm(olmlib.OLM_ALGORITHM, OlmEncryption, OlmDecryption);
@@ -86,6 +86,7 @@ function Crypto(baseApis, eventEmitter, sessionStore, userId, deviceId) {

    _registerEventHandlers(this, eventEmitter);

+    // map from userId -> deviceId -> roomId -> timestamp
    this._lastNewDeviceMessageTsByUserDeviceRoom = {};
 }

@@ -173,7 +174,7 @@ Crypto.prototype.uploadKeys = function(maxKeys) {
        // these factors.

        // We first find how many keys the server has for us.
-        var keyCount = res.one_time_key_counts.curve25519 || 0;
+        var keyCount = res.one_time_key_counts.signed_curve25519 || 0;
        // We then check how many keys we can store in the Account object.
        var maxOneTimeKeys = self._olmDevice.maxNumberOfOneTimeKeys();
        // Try to keep at most half that number on the server. This leaves the
@@ -216,11 +217,7 @@ function _uploadDeviceKeys(crypto) {
        keys: crypto._deviceKeys,
        user_id: userId,
    };
-
-    var sig = crypto._olmDevice.sign(anotherjson.stringify(deviceKeys));
-    deviceKeys.signatures = {};
-    deviceKeys.signatures[userId] = {};
-    deviceKeys.signatures[userId]["ed25519:" + deviceId] = sig;
+    crypto._signObject(deviceKeys);

    return crypto._baseApis.uploadKeysRequest({
        device_keys: deviceKeys,
@@ -238,9 +235,14 @@ function _uploadOneTimeKeys(crypto) {

    for (var keyId in oneTimeKeys.curve25519) {
        if (oneTimeKeys.curve25519.hasOwnProperty(keyId)) {
-            oneTimeJson["curve25519:" + keyId] = oneTimeKeys.curve25519[keyId];
+            var k = {
+                key: oneTimeKeys.curve25519[keyId],
+            };
+            crypto._signObject(k);
+            oneTimeJson["signed_curve25519:" + keyId] = k;
        }
    }
+
    return crypto._baseApis.uploadKeysRequest({
        one_time_keys: oneTimeJson
    }, {
@@ -317,10 +319,10 @@ Crypto.prototype.downloadKeys = function(userIds, forceDownload) {
                }

                storage[deviceId] = userStore[deviceId].toStorage();
-                self._sessionStore.storeEndToEndDevicesForUser(
-                    userId, storage
-                );
            }
+            self._sessionStore.storeEndToEndDevicesForUser(
+                userId, storage
+            );
        }
        return stored;
    });
@@ -349,9 +351,22 @@ function _updateStoredDeviceKeysForUser(_olmDevice, userId, userStore,
            continue;
        }

-        if (_storeDeviceKeys(
-            _olmDevice, userId, deviceId, userStore, userResult[deviceId]
-        )) {
+        var deviceResult = userResult[deviceId];
+
+        // check that the user_id and device_id in the response object are
+        // correct
+        if (deviceResult.user_id !== userId) {
+            console.warn("Mismatched user_id " + deviceResult.user_id +
+                         " in keys from " + userId + ":" + deviceId);
+            continue;
+        }
+        if (deviceResult.device_id !== deviceId) {
+            console.warn("Mismatched device_id " + deviceResult.device_id +
+                         " in keys from " + userId + ":" + deviceId);
+            continue;
+        }
+
+        if (_storeDeviceKeys(_olmDevice, userStore, deviceResult)) {
            updated = true;
        }
    }
@@ -364,12 +379,15 @@ function _updateStoredDeviceKeysForUser(_olmDevice, userId, userStore,
 *
 * returns true if a change was made, else false
 */
-function _storeDeviceKeys(_olmDevice, userId, deviceId, userStore, deviceResult) {
+function _storeDeviceKeys(_olmDevice, userStore, deviceResult) {
    if (!deviceResult.keys) {
        // no keys?
        return false;
    }

+    var deviceId = deviceResult.device_id;
+    var userId = deviceResult.user_id;
+
    var signKeyId = "ed25519:" + deviceId;
    var signKey = deviceResult.keys[signKeyId];
    if (!signKey) {
@@ -379,23 +397,9 @@ function _storeDeviceKeys(_olmDevice, userId, deviceId, userStore, deviceResult)
    }

    var unsigned = deviceResult.unsigned || {};
-    var signatures = deviceResult.signatures || {};
-    var userSigs = signatures[userId] || {};
-    var signature = userSigs[signKeyId];
-    if (!signature) {
-        console.log("Device " + userId + ":" + deviceId +
-                    " is not signed");
-        return false;
-    }
-
-    // prepare the canonical json: remove 'unsigned' and signatures, and
-    // stringify with anotherjson
-    delete deviceResult.unsigned;
-    delete deviceResult.signatures;
-    var json = anotherjson.stringify(deviceResult);

    try {
-        _olmDevice.verifySignature(signKey, json, signature);
+        _verifySignature(_olmDevice, deviceResult, userId, deviceId, signKey);
    } catch (e) {
        console.log("Unable to verify signature on device " +
                    userId + ":" + deviceId + ":", e);
@@ -610,33 +614,56 @@ Crypto.prototype.getOlmSessionsForUser = function(userId) {


 /**
- * Identify a device by curve25519 identity key and determine its verification state
+ * Get the device which sent an event
 *
- * @param {string} userId     owner of the device
- * @param {string} algorithm  encryption algorithm
- * @param {string} sender_key curve25519 key to match
+ * @param {module:models/event.MatrixEvent} event event to be checked
 *
- * @return {boolean} true if the device is verified
+ * @return {module:crypto/deviceinfo?}
 */
-Crypto.prototype.isSenderKeyVerified = function(userId, algorithm, sender_key) {
+Crypto.prototype.getEventSenderDeviceInfo = function(event) {
+    var sender_key = event.getSenderKey();
+    var algorithm = event.getWireContent().algorithm;

-    // sender_key is the curve25519 public key of the device, that the event
-    // purports to have been sent from. It's assumed that, by the time we get here,
-    // we have already checked that the event was, in fact, sent by that device.
-    //
-    // In the case of both olm and megolm, that is achieved primarily by the
-    // fact that sessions are indexed by the curve25519 key of the device that
-    // created the session, and we assume that only that device has the keys
-    // necessary to create valid messages in that session.
-    //
-    // So, all we need to do here is look up the device by sender and
-    // curve25519 key and determine the state of the verification flag.
-
-    var device = this.getDeviceByIdentityKey(userId, algorithm, sender_key);
-    if (!device) {
-        return false;
+    if (!sender_key || !algorithm) {
+        return null;
    }
-    return device.verified == DeviceVerification.VERIFIED;
+
+    // sender_key is the Curve25519 identity key of the device which the event
+    // was sent from. In the case of Megolm, it's actually the Curve25519
+    // identity key of the device which set up the Megolm session.
+
+    var device = this.getDeviceByIdentityKey(
+        event.getSender(), algorithm, sender_key
+    );
+
+    if (device === null) {
+        // we haven't downloaded the details of this device yet.
+        return null;
+    }
+
+    // so far so good, but now we need to check that the sender of this event
+    // hadn't advertised someone else's Curve25519 key as their own. We do that
+    // by checking the Ed25519 claimed by the event (or, in the case of megolm,
+    // the event which set up the megolm session), to check that it matches the
+    // fingerprint of the purported sending device.
+    //
+    // (see https://github.com/vector-im/vector-web/issues/2215)
+
+    var claimedKey = event.getKeysClaimed().ed25519;
+    if (!claimedKey) {
+        console.warn("Event " + event.getId() + " claims no ed25519 key: " +
+                     "cannot verify sending device");
+        return null;
+    }
+
+    if (claimedKey !== device.getFingerprint()) {
+        console.warn(
+            "Event " + event.getId() + " claims ed25519 key " + claimedKey +
+                "but sender device has key " + device.getFingerprint());
+        return null;
+    }
+
+    return device;
 };


@@ -670,11 +697,13 @@ Crypto.prototype.setRoomEncryption = function(roomId, config) {
    this._sessionStore.storeEndToEndRoom(roomId, config);

    var alg = new AlgClass({
+        userId: this._userId,
        deviceId: this._deviceId,
        crypto: this,
        olmDevice: this._olmDevice,
        baseApis: this._baseApis,
        roomId: roomId,
+        config: config,
    });
    this._roomAlgorithms[roomId] = alg;
 };
@@ -743,8 +772,9 @@ Crypto.prototype.ensureOlmSessionsForUsers = function(users) {
    // That should eventually resolve itself, but it's poor form.

    var self = this;
+    var oneTimeKeyAlgorithm = "signed_curve25519";
    return this._baseApis.claimOneTimeKeys(
-        devicesWithoutSession
+        devicesWithoutSession, oneTimeKeyAlgorithm
    ).then(function(res) {
        for (var i = 0; i < devicesWithoutSession.length; ++i) {
            var device = devicesWithoutSession[i];
@@ -756,22 +786,48 @@ Crypto.prototype.ensureOlmSessionsForUsers = function(users) {
            var deviceRes = userRes[deviceId];
            var oneTimeKey = null;
            for (var keyId in deviceRes) {
-                if (keyId.indexOf("curve25519:") === 0) {
+                if (keyId.indexOf(oneTimeKeyAlgorithm + ":") === 0) {
                    oneTimeKey = deviceRes[keyId];
                }
            }
-            if (oneTimeKey) {
-                var sid = self._olmDevice.createOutboundSession(
-                    deviceInfo.getIdentityKey(), oneTimeKey
-                );
-                console.log("Started new sessionid " + sid +
-                            " for device " + userId + ":" + deviceId);

-                result[userId][deviceId].sessionId = sid;
-            } else {
-                console.warn("No one-time keys for device " +
-                             userId + ":" + deviceId);
+            if (!oneTimeKey) {
+                console.warn(
+                    "No one-time keys (alg=" + oneTimeKeyAlgorithm +
+                        ") for device " + userId + ":" + deviceId
+                );
+                continue;
            }
+
+            try {
+                _verifySignature(
+                    self._olmDevice, oneTimeKey, userId, deviceId,
+                    deviceInfo.getFingerprint()
+                );
+            } catch (e) {
+                console.log(
+                    "Unable to verify signature on one-time key for device " +
+                        userId + ":" + deviceId + ":", e
+                );
+                continue;
+            }
+
+            var sid;
+            try {
+                sid = self._olmDevice.createOutboundSession(
+                    deviceInfo.getIdentityKey(), oneTimeKey.key
+                );
+            } catch (e) {
+                // possibly a bad key
+                console.error("Error starting session with device " +
+                              userId + ":" + deviceId + ": " + e);
+                continue;
+            }
+
+            console.log("Started new sessionid " + sid +
+                        " for device " + userId + ":" + deviceId);
+
+            result[userId][deviceId].sessionId = sid;
        }
        return result;
    });
@@ -847,12 +903,26 @@ Crypto.prototype.encryptEventIfNeeded = function(event, room) {
    });
 };

+/**
+ * @typedef {Object} module:crypto.DecryptionResult
+ *
+ * @property {Object} payload 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 a received event
 *
 * @param {object} event raw event
 *
- * @return {object} decrypted payload (with properties 'type', 'content')
+ * @return {module:crypto.DecryptionResult} decryption result
 *
 * @raises {algorithms.DecryptionError} if there is a problem decrypting the event
 */
@@ -863,23 +933,32 @@ Crypto.prototype.decryptEvent = function(event) {
        throw new algorithms.DecryptionError("Unable to decrypt " + content.algorithm);
    }
    var alg = new AlgClass({
+        userId: this._userId,
        olmDevice: this._olmDevice,
    });
    var r = alg.decryptEvent(event);
-    var payload = r.result;
-    if (r.sessionExists) {
-        payload.keysClaimed = r.keysClaimed;
-        payload.keysProved = r.keysProved;
-        return payload;
+
+    if (r !== null) {
+        return r;
    } else {
-        // We've got a message for a session we don't have.
-        // Maybe the sender forgot to tell us about the session.
-        // Remind the sender that we exist so that they might
-        // tell us about the sender.
-        if (event.getRoomId !== undefined && event.getSender !== undefined) {
-            this._sendPingToDevice(
-                event.getSender(), event.content.device, event.getRoomId
-            );
+        // We've got a message for a session we don't have.  Maybe the sender
+        // forgot to tell us about the session.  Remind the sender that we
+        // exist so that they might tell us about the session on their next
+        // send.
+        //
+        // (Alternatively, it might be that we are just looking at
+        // scrollback... at least we rate-limit the m.new_device events :/)
+        //
+        // XXX: this is a band-aid which masks symptoms of other bugs. It would
+        // be nice to get rid of it.
+        if (event.room_id !== undefined && event.sender !== undefined) {
+            var device_id = event.content.device_id;
+            if (device_id === undefined) {
+                // if the sending device didn't tell us its device_id, fall
+                // back to all devices.
+                device_id = null;
+            }
+            this._sendPingToDevice(event.sender, device_id, event.room_id);
        }

        throw new algorithms.DecryptionError("Unknown inbound session id");
@@ -892,39 +971,50 @@ Crypto.prototype.decryptEvent = function(event) {
 *
 * This is rate limited to send a message at most once an hour per desination.
 *
- * @param {string} userId   The ID of the user to ping.
- * @param {string} deviceId The ID of the device to ping.
- * @param {string} roomId   The ID of the room we want to remind them about.
+ * @param {string}  userId   The ID of the user to ping.
+ * @param {string?} deviceId The ID of the device to ping. If null, all
+ *     devices.
+ * @param {string}  roomId   The ID of the room we want to remind them about.
 */
 Crypto.prototype._sendPingToDevice = function(userId, deviceId, roomId) {
-    if (deviceId === undefined) {
+    if (deviceId === null) {
        deviceId = "*";
    }

    var lastMessageTsMap = this._lastNewDeviceMessageTsByUserDeviceRoom;
-    var lastTsByDevice = lastMessageTsMap[userId] || {};
-    var lastTsByRoom = lastTsByDevice[deviceId] || {};
+
+    var lastTsByDevice = lastMessageTsMap[userId];
+    if (!lastTsByDevice) {
+        lastTsByDevice = lastMessageTsMap[userId] = {};
+    }
+
+    var lastTsByRoom = lastTsByDevice[deviceId];
+    if (!lastTsByRoom) {
+        lastTsByRoom = lastTsByDevice[deviceId] = {};
+    }
+
    var lastTs = lastTsByRoom[roomId];
    var timeNowMs = Date.now();
    var oneHourMs = 1000 * 60 * 60;

-    if (lastTs === undefined || lastTs + oneHourMs < timeNowMs) {
-        var content = {
-            userId: {
-                deviceId: {
-                    device_id: this._deviceId,
-                    rooms: [roomId],
-                }
-            }
-        };
-
-        lastTsByRoom[roomId] = timeNowMs;
-
-        this._baseApis.sendToDevice(
-            "m.new_device", // OH HAI!
-            content
-        ).done(function() {});
+    if (lastTs !== undefined && lastTs + oneHourMs > timeNowMs) {
+        // rate-limiting
+        return;
    }
+
+    var content = {};
+    content[userId] = {};
+    content[userId][deviceId] = {
+        device_id: this._deviceId,
+        rooms: [roomId],
+    };
+
+    this._baseApis.sendToDevice(
+        "m.new_device", // OH HAI!
+        content
+    ).done();
+
+    lastTsByRoom[roomId] = timeNowMs;
 };

 /**
@@ -1027,6 +1117,7 @@ Crypto.prototype._onRoomKeyEvent = function(event) {
        );
    }
    var alg = new AlgClass({
+        userId: this._userId,
        olmDevice: this._olmDevice,
    });
    alg.onRoomKeyEvent(event);
@@ -1042,9 +1133,10 @@ Crypto.prototype._onRoomKeyEvent = function(event) {
 */
 Crypto.prototype._onRoomMembership = function(event, member, oldMembership) {

-    // this event handler is registered on the *client* (as opposed to the
-    // room member itself), which means it is only called on changes to the
-    // *live* membership state (ie, it is not called when we back-paginate).
+    // this event handler is registered on the *client* (as opposed to the room
+    // member itself), which means it is only called on changes to the *live*
+    // membership state (ie, it is not called when we back-paginate, nor when
+    // we load the state in the initialsync).
    //
    // Further, it is automatically registered and called when new members
    // arrive in the room.
@@ -1078,6 +1170,9 @@ Crypto.prototype._onNewDeviceEvent = function(event) {
        return;
    }

+    console.log("m.new_device event from " + userId + ":" + deviceId +
+                " for rooms " + rooms);
+
    var self = this;
    this.downloadKeys(
        [userId], true
@@ -1100,6 +1195,54 @@ Crypto.prototype._onNewDeviceEvent = function(event) {
    }).done();
 };

+
+/**
+ * sign the given object with our ed25519 key
+ *
+ * @param {Object} obj  Object to which we will add a 'signatures' property
+ */
+Crypto.prototype._signObject = function(obj) {
+    var sigs = {};
+    sigs[this._userId] = {};
+    sigs[this._userId]["ed25519:" + this._deviceId] =
+        this._olmDevice.sign(anotherjson.stringify(obj));
+    obj.signatures = sigs;
+};
+
+/**
+ * Verify the signature on an object
+ *
+ * @param {module:crypto/OlmDevice} olmDevice olm wrapper to use for verify op
+ *
+ * @param {Object} obj object to check signature on. Note that this will be
+ * stripped of its 'signatures' and 'unsigned' properties.
+ *
+ * @param {string} signingUserId  ID of the user whose signature should be checked
+ *
+ * @param {string} signingDeviceId  ID of the device whose signature should be checked
+ *
+ * @param {string} signingKey   base64-ed ed25519 public key
+ */
+function _verifySignature(olmDevice, obj, signingUserId, signingDeviceId, signingKey) {
+    var signKeyId = "ed25519:" + signingDeviceId;
+    var signatures = obj.signatures || {};
+    var userSigs = signatures[signingUserId] || {};
+    var signature = userSigs[signKeyId];
+    if (!signature) {
+        throw Error("No signature");
+    }
+
+    // prepare the canonical json: remove unsigned and signatures, and stringify with
+    // anotherjson
+    delete obj.unsigned;
+    delete obj.signatures;
+    var json = anotherjson.stringify(obj);
+
+    olmDevice.verifySignature(
+        signingKey, json, signature
+    );
+}
+
 /**
 * @see module:crypto/algorithms/base.DecryptionError
 */
@@ -34,45 +34,69 @@ module.exports.MEGOLM_ALGORITHM = "m.megolm.v1.aes-sha2";


 /**
- * Encrypt an event payload for a list of devices
+ * Encrypt an event payload for an Olm device
 *
+ * @param {Object<string, string>} resultsObject  The `ciphertext` property
+ *   of the m.room.encrypted event to which to add our result
+ *
+ * @param {string} ourUserId
 * @param {string} ourDeviceId
 * @param {module:crypto/OlmDevice} olmDevice olm.js wrapper
- * @param {string[]} participantKeys list of curve25519 keys to encrypt for
+ * @param {string} recipientUserId
+ * @param {module:crypto/deviceinfo} recipientDevice
 * @param {object} payloadFields fields to include in the encrypted payload
- *
- * @return {object} content for an m.room.encrypted event
 */
-module.exports.encryptMessageForDevices = function(
-    ourDeviceId, olmDevice, participantKeys, payloadFields
+module.exports.encryptMessageForDevice = function(
+    resultsObject,
+    ourUserId, ourDeviceId, olmDevice, recipientUserId, recipientDevice,
+    payloadFields
 ) {
-    participantKeys.sort();
-    var participantHash = ""; // Olm.sha256(participantKeys.join());
-    var payloadJson = {
-        fingerprint: participantHash,
-        sender_device: ourDeviceId,
-    };
-    utils.extend(payloadJson, payloadFields);
-
-    var ciphertext = {};
-    var payloadString = JSON.stringify(payloadJson);
-    for (var i = 0; i < participantKeys.length; ++i) {
-        var deviceKey = participantKeys[i];
-        var sessionId = olmDevice.getSessionIdForDevice(deviceKey);
-        if (sessionId === null) {
-            // If we don't have a session for a device then
-            // we can't encrypt a message for it.
-            continue;
-        }
-        console.log("Using sessionid " + sessionId + " for device " + deviceKey);
-        ciphertext[deviceKey] = olmDevice.encryptMessage(
-            deviceKey, sessionId, payloadString
-        );
+    var deviceKey = recipientDevice.getIdentityKey();
+    var sessionId = olmDevice.getSessionIdForDevice(deviceKey);
+    if (sessionId === null) {
+        // If we don't have a session for a device then
+        // we can't encrypt a message for it.
+        return;
    }
-    var encryptedContent = {
-        algorithm: module.exports.OLM_ALGORITHM,
-        sender_key: olmDevice.deviceCurve25519Key,
-        ciphertext: ciphertext
+
+    console.log(
+        "Using sessionid " + sessionId + " for device " +
+            recipientUserId + ":" + recipientDevice.deviceId
+    );
+
+    var payload = {
+        sender: ourUserId,
+        sender_device: ourDeviceId,
+
+        // Include the Ed25519 key so that the recipient knows what
+        // device this message came from.
+        // We don't need to include the curve25519 key since the
+        // recipient will already know this from the olm headers.
+        // When combined with the device keys retrieved from the
+        // homeserver signed by the ed25519 key this proves that
+        // the curve25519 key and the ed25519 key are owned by
+        // the same device.
+        keys: {
+            "ed25519": olmDevice.deviceEd25519Key,
+        },
+
+        // include the recipient device details in the payload,
+        // to avoid unknown key attacks, per
+        // https://github.com/vector-im/vector-web/issues/2483
+        recipient: recipientUserId,
+        recipient_keys: {
+            "ed25519": recipientDevice.getFingerprint(),
+        },
    };
-    return encryptedContent;
+
+    // TODO: technically, a bunch of that stuff only needs to be included for
+    // pre-key messages: after that, both sides know exactly which devices are
+    // involved in the session. If we're looking to reduce data transfer in the
+    // future, we could elide them for subsequent messages.
+
+    utils.extend(payload, payloadFields);
+
+    resultsObject[deviceKey] = olmDevice.encryptMessage(
+        deviceKey, sessionId, JSON.stringify(payload)
+    );
 };
@@ -63,9 +63,11 @@ module.exports.PREFIX_MEDIA_R0 = "/_matrix/media/r0";
 * requests. This function must look like function(opts, callback){ ... }.
 * @param {string} opts.prefix Required. The matrix client prefix to use, e.g.
 * '/_matrix/client/r0'. See PREFIX_R0 and PREFIX_UNSTABLE for constants.
- * @param {bool} opts.onlyData True to return only the 'data' component of the
- * response (e.g. the parsed HTTP body). If false, requests will return status
- * codes and headers in addition to data. Default: false.
+ *
+ * @param {bool=} opts.onlyData True to return only the 'data' component of the
+ * response (e.g. the parsed HTTP body). If false, requests will return an
+ * object with the properties <tt>code</tt>, <tt>headers</tt> and <tt>data</tt>.
+ *
 * @param {string} opts.accessToken The access_token to send with requests. Can be
 * null to not send an access token.
 * @param {Object} opts.extraParams Optional. Extra query parameters to send on
@@ -99,22 +101,87 @@ module.exports.MatrixHttpApi.prototype = {

    /**
     * Upload content to the Home Server
-     * @param {File} file A File object (in a browser) or in Node,
-                                 an object with properties:
-                                 name: The file's name
-                                 stream: A read stream
-     * @param {Function} callback Optional. The callback to invoke on
-     * success/failure. See the promise return values for more information.
-     * @return {module:client.Promise} Resolves to <code>{data: {Object},
+     *
+     * @param {object} file The object to upload. On a browser, something that
+     *   can be sent to XMLHttpRequest.send (typically a File).  Under node.js,
+     *   a a Buffer, String or ReadStream.
+     *
+     * @param {object} opts  options object
+     *
+     * @param {string=} opts.name   Name to give the file on the server. Defaults
+     *   to <tt>file.name</tt>.
+     *
+     * @param {string=} opts.type   Content-type for the upload. Defaults to
+     *   <tt>file.type</tt>, or <tt>applicaton/octet-stream</tt>.
+     *
+     * @param {boolean=} opts.rawResponse Return the raw body, rather than
+     *   parsing the JSON. Defaults to false (except on node.js, where it
+     *   defaults to true for backwards compatibility).
+     *
+     * @param {boolean=} opts.onlyContentUri Just return the content URI,
+     *   rather than the whole body. Defaults to false (except on browsers,
+     *   where it defaults to true for backwards compatibility). Ignored if
+     *   opts.rawResponse is true.
+     *
+     * @param {Function=} opts.callback Deprecated. Optional. The callback to
+     *    invoke on success/failure. See the promise return values for more
+     *    information.
+     *
+     * @return {module:client.Promise} Resolves to response object, as
+     *    determined by this.opts.onlyData, opts.rawResponse, and
+     *    opts.onlyContentUri.  Rejects with an error (usually a MatrixError).
     */
-    uploadContent: function(file, callback) {
-        if (callback !== undefined && !utils.isFunction(callback)) {
-            throw Error(
-                "Expected callback to be a function but got " + typeof callback
-            );
+    uploadContent: function(file, opts) {
+        if (utils.isFunction(opts)) {
+            // opts used to be callback
+            opts = {
+                callback: opts,
+            };
+        } else if (opts === undefined) {
+            opts = {};
        }
-        var defer = q.defer();
-        var url = this.opts.baseUrl + "/_matrix/media/v1/upload";
+
+        // if the file doesn't have a mime type, use a default since
+        // the HS errors if we don't supply one.
+        var contentType = opts.type || file.type || 'application/octet-stream';
+        var fileName = opts.name || file.name;
+
+        // we used to recommend setting file.stream to the thing to upload on
+        // nodejs.
+        var body = file.stream ? file.stream : file;
+
+        // backwards-compatibility hacks where we used to do different things
+        // between browser and node.
+        var rawResponse = opts.rawResponse;
+        if (rawResponse === undefined) {
+            if (global.XMLHttpRequest) {
+                rawResponse = false;
+            } else {
+                console.warn(
+                    "Returning the raw JSON from uploadContent(). Future " +
+                    "versions of the js-sdk will change this default, to " +
+                    "return the parsed object. Set opts.rawResponse=false " +
+                    "to change this behaviour now."
+                );
+                rawResponse = true;
+            }
+        }
+
+        var onlyContentUri = opts.onlyContentUri;
+        if (!rawResponse && onlyContentUri === undefined) {
+            if (global.XMLHttpRequest) {
+                console.warn(
+                    "Returning only the content-uri from uploadContent(). " +
+                    "Future versions of the js-sdk will change this " +
+                    "default, to return the whole response object. Set " +
+                    "opts.onlyContentUri=false to change this behaviour now."
+                );
+                onlyContentUri = true;
+            } else {
+                onlyContentUri = false;
+            }
+        }
+
        // browser-request doesn't support File objects because it deep-copies
        // the options using JSON.parse(JSON.stringify(options)). Instead of
        // loading the whole file into memory as a string and letting
@@ -124,40 +191,60 @@ module.exports.MatrixHttpApi.prototype = {
        // of important here)

        var upload = { loaded: 0, total: 0 };
+        var promise;
+
+        // XMLHttpRequest doesn't parse JSON for us. request normally does, but
+        // we're setting opts.json=false so that it doesn't JSON-encode the
+        // request, which also means it doesn't JSON-decode the response. Either
+        // way, we have to JSON-parse the response ourselves.
+        var bodyParser = null;
+        if (!rawResponse) {
+            bodyParser = function(rawBody) {
+                var body = JSON.parse(rawBody);
+                if (onlyContentUri) {
+                    body = body.content_uri;
+                    if (body === undefined) {
+                        throw Error('Bad response');
+                    }
+                }
+                return body;
+            };
+        }

        if (global.XMLHttpRequest) {
+            var defer = q.defer();
            var xhr = new global.XMLHttpRequest();
            upload.xhr = xhr;
-            var cb = requestCallback(defer, callback, this.opts.onlyData);
+            var cb = requestCallback(defer, opts.callback, this.opts.onlyData);

            var timeout_fn = function() {
                xhr.abort();
                cb(new Error('Timeout'));
            };

+            // set an initial timeout of 30s; we'll advance it each time we get
+            // a progress notification
            xhr.timeout_timer = callbacks.setTimeout(timeout_fn, 30000);

            xhr.onreadystatechange = function() {
                switch (xhr.readyState) {
                    case global.XMLHttpRequest.DONE:
                        callbacks.clearTimeout(xhr.timeout_timer);
-                        var err;
-                        if (!xhr.responseText) {
-                            err = new Error('No response body.');
+                        var resp;
+                        try {
+                            if (!xhr.responseText) {
+                                throw new Error('No response body.');
+                            }
+                            resp = xhr.responseText;
+                            if (bodyParser) {
+                                resp = bodyParser(resp);
+                            }
+                        } catch (err) {
                            err.http_status = xhr.status;
                            cb(err);
                            return;
                        }
-
-                        var resp = JSON.parse(xhr.responseText);
-                        if (resp.content_uri === undefined) {
-                            err = Error('Bad response');
-                            err.http_status = xhr.status;
-                            cb(err);
-                            return;
-                        }
-
-                        cb(undefined, xhr, resp.content_uri);
+                        cb(undefined, xhr, resp);
                        break;
                }
            };
@@ -168,59 +255,57 @@ module.exports.MatrixHttpApi.prototype = {
                xhr.timeout_timer = callbacks.setTimeout(timeout_fn, 30000);
                defer.notify(ev);
            });
+            var url = this.opts.baseUrl + "/_matrix/media/v1/upload";
            url += "?access_token=" + encodeURIComponent(this.opts.accessToken);
-            url += "&filename=" + encodeURIComponent(file.name);
+            url += "&filename=" + encodeURIComponent(fileName);

            xhr.open("POST", url);
-            if (file.type) {
-                xhr.setRequestHeader("Content-Type", file.type);
-            } else {
-                // if the file doesn't have a mime type, use a default since
-                // the HS errors if we don't supply one.
-                xhr.setRequestHeader("Content-Type", 'application/octet-stream');
-            }
-            xhr.send(file);
+            xhr.setRequestHeader("Content-Type", contentType);
+            xhr.send(body);
+            promise = defer.promise;
+
+            // dirty hack (as per _request) to allow the upload to be cancelled.
+            promise.abort = xhr.abort.bind(xhr);
        } else {
            var queryParams = {
-                filename: file.name,
-                access_token: this.opts.accessToken
+                filename: fileName,
            };
-            upload.request = this.opts.request({
-                uri: url,
-                qs: queryParams,
-                method: "POST",
-                headers: {"Content-Type": file.type},
-                body: file.stream
-            }, requestCallback(defer, callback, this.opts.onlyData));
+
+            promise = this.authedRequest(
+                opts.callback, "POST", "/upload", queryParams, body, {
+                    prefix: "/_matrix/media/v1",
+                    headers: {"Content-Type": contentType},
+                    json: false,
+                    bodyParser: bodyParser,
+                }
+            );
        }

-        this.uploads.push(upload);
-
        var self = this;
-        upload.promise = defer.promise.finally(function() {
-            var uploadsKeys = Object.keys(self.uploads);
-            for (var i = 0; i < uploadsKeys.length; ++i) {
-                if (self.uploads[uploadsKeys[i]].promise === defer.promise) {
-                    self.uploads.splice(uploadsKeys[i], 1);
+
+        // remove the upload from the list on completion
+        var promise0 = promise.finally(function() {
+            for (var i = 0; i < self.uploads.length; ++i) {
+                if (self.uploads[i] === upload) {
+                    self.uploads.splice(i, 1);
+                    return;
                }
            }
        });
-        return upload.promise;
+
+        // copy our dirty abort() method to the new promise
+        promise0.abort = promise.abort;
+
+        upload.promise = promise0;
+        this.uploads.push(upload);
+
+        return promise0;
    },

    cancelUpload: function(promise) {
-        var uploadsKeys = Object.keys(this.uploads);
-        for (var i = 0; i < uploadsKeys.length; ++i) {
-            var upload = this.uploads[uploadsKeys[i]];
-            if (upload.promise === promise) {
-                if (upload.xhr !== undefined) {
-                    upload.xhr.abort();
-                    return true;
-                } else if (upload.request !== undefined) {
-                    upload.request.abort();
-                    return true;
-                }
-            }
+        if (promise.abort) {
+            promise.abort();
+            return true;
        }
        return false;
    },
@@ -271,11 +356,22 @@ module.exports.MatrixHttpApi.prototype = {
     * @param {string} method The HTTP method e.g. "GET".
     * @param {string} path The HTTP path <b>after</b> the supplied prefix e.g.
     * "/createRoom".
-     * @param {Object} queryParams A dict of query params (these will NOT be
-     * urlencoded).
+     *
+     * @param {Object=} queryParams A dict of query params (these will NOT be
+     * urlencoded). If unspecified, there will be no query params.
+     *
     * @param {Object} data The HTTP JSON body.
-     * @param {Number=} localTimeoutMs The maximum amount of time to wait before
+     *
+     * @param {Object=} opts additional options
+     *
+     * @param {Number=} opts.localTimeoutMs The maximum amount of time to wait before
     * timing out the request. If not specified, there is no timeout.
+     *
+     * @param {sting=} opts.prefix The full prefix to use e.g.
+     * "/_matrix/client/v2_alpha". If not specified, uses this.opts.prefix.
+     *
+     * @param {Object=} opts.headers map of additional request headers
+     *
     * @return {module:client.Promise} Resolves to <code>{data: {Object},
     * headers: {Object}, code: {Number}}</code>.
     * If <code>onlyData</code> is set, this will resolve to the <code>data</code>
@@ -283,18 +379,25 @@ module.exports.MatrixHttpApi.prototype = {
     * @return {module:http-api.MatrixError} Rejects with an error if a problem
     * occurred. This includes network problems and Matrix-specific error JSON.
     */
-    authedRequest: function(callback, method, path, queryParams, data, localTimeoutMs) {
-        if (!queryParams) { queryParams = {}; }
-        queryParams.access_token = this.opts.accessToken;
-        var self = this;
+    authedRequest: function(callback, method, path, queryParams, data, opts) {
+        if (!queryParams) {
+            queryParams = {};
+        }
+        if (!queryParams.access_token) {
+            queryParams.access_token = this.opts.accessToken;
+        }
+
        var request_promise = this.request(
-            callback, method, path, queryParams, data, localTimeoutMs
+            callback, method, path, queryParams, data, opts
        );
+
+        var self = this;
        request_promise.catch(function(err) {
            if (err.errcode == 'M_UNKNOWN_TOKEN') {
                self.event_emitter.emit("Session.logged_out");
            }
        });
+
        // return the original promise, otherwise tests break due to it having to
        // go around the event loop one more time to process the result of the request
        return request_promise;
@@ -307,11 +410,22 @@ module.exports.MatrixHttpApi.prototype = {
     * @param {string} method The HTTP method e.g. "GET".
     * @param {string} path The HTTP path <b>after</b> the supplied prefix e.g.
     * "/createRoom".
-     * @param {Object} queryParams A dict of query params (these will NOT be
-     * urlencoded).
+     *
+     * @param {Object=} queryParams A dict of query params (these will NOT be
+     * urlencoded). If unspecified, there will be no query params.
+     *
     * @param {Object} data The HTTP JSON body.
-     * @param {Number=} localTimeoutMs The maximum amount of time to wait before
+     *
+     * @param {Object=} opts additional options
+     *
+     * @param {Number=} opts.localTimeoutMs The maximum amount of time to wait before
     * timing out the request. If not specified, there is no timeout.
+     *
+     * @param {sting=} opts.prefix The full prefix to use e.g.
+     * "/_matrix/client/v2_alpha". If not specified, uses this.opts.prefix.
+     *
+     * @param {Object=} opts.headers map of additional request headers
+     *
     * @return {module:client.Promise} Resolves to <code>{data: {Object},
     * headers: {Object}, code: {Number}}</code>.
     * If <code>onlyData</code> is set, this will resolve to the <code>data</code>
@@ -319,9 +433,13 @@ module.exports.MatrixHttpApi.prototype = {
     * @return {module:http-api.MatrixError} Rejects with an error if a problem
     * occurred. This includes network problems and Matrix-specific error JSON.
     */
-    request: function(callback, method, path, queryParams, data, localTimeoutMs) {
-        return this.requestWithPrefix(
-            callback, method, path, queryParams, data, this.opts.prefix, localTimeoutMs
+    request: function(callback, method, path, queryParams, data, opts) {
+        opts = opts || {};
+        var prefix = opts.prefix !== undefined ? opts.prefix : this.opts.prefix;
+        var fullUri = this.opts.baseUrl + prefix + path;
+
+        return this.requestOtherUrl(
+            callback, method, fullUri, queryParams, data, opts
        );
    },

@@ -347,16 +465,16 @@ module.exports.MatrixHttpApi.prototype = {
     * object only.
     * @return {module:http-api.MatrixError} Rejects with an error if a problem
     * occurred. This includes network problems and Matrix-specific error JSON.
+     *
+     * @deprecated prefer authedRequest with opts.prefix
     */
    authedRequestWithPrefix: function(callback, method, path, queryParams, data,
                                      prefix, localTimeoutMs) {
-        var fullUri = this.opts.baseUrl + prefix + path;
-        if (!queryParams) {
-            queryParams = {};
-        }
-        queryParams.access_token = this.opts.accessToken;
-        return this._request(
-            callback, method, fullUri, queryParams, data, localTimeoutMs
+        return this.authedRequest(
+            callback, method, path, queryParams, data, {
+                localTimeoutMs: localTimeoutMs,
+                prefix: prefix,
+            }
        );
    },

@@ -382,15 +500,16 @@ module.exports.MatrixHttpApi.prototype = {
     * object only.
     * @return {module:http-api.MatrixError} Rejects with an error if a problem
     * occurred. This includes network problems and Matrix-specific error JSON.
+     *
+     * @deprecated prefer request with opts.prefix
     */
    requestWithPrefix: function(callback, method, path, queryParams, data, prefix,
                                localTimeoutMs) {
-        var fullUri = this.opts.baseUrl + prefix + path;
-        if (!queryParams) {
-            queryParams = {};
-        }
-        return this._request(
-            callback, method, fullUri, queryParams, data, localTimeoutMs
+        return this.request(
+            callback, method, path, queryParams, data, {
+                localTimeoutMs: localTimeoutMs,
+                prefix: prefix,
+            }
        );
    },

@@ -400,11 +519,22 @@ module.exports.MatrixHttpApi.prototype = {
     * success/failure. See the promise return values for more information.
     * @param {string} method The HTTP method e.g. "GET".
     * @param {string} uri The HTTP URI
-     * @param {Object} queryParams A dict of query params (these will NOT be
-     * urlencoded).
+     *
+     * @param {Object=} queryParams A dict of query params (these will NOT be
+     * urlencoded). If unspecified, there will be no query params.
+     *
     * @param {Object} data The HTTP JSON body.
-     * @param {Number=} localTimeoutMs The maximum amount of time to wait before
+     *
+     * @param {Object=} opts additional options
+     *
+     * @param {Number=} opts.localTimeoutMs The maximum amount of time to wait before
     * timing out the request. If not specified, there is no timeout.
+     *
+     * @param {sting=} opts.prefix The full prefix to use e.g.
+     * "/_matrix/client/v2_alpha". If not specified, uses this.opts.prefix.
+     *
+     * @param {Object=} opts.headers map of additional request headers
+     *
     * @return {module:client.Promise} Resolves to <code>{data: {Object},
     * headers: {Object}, code: {Number}}</code>.
     * If <code>onlyData</code> is set, this will resolve to the <code>data</code>
@@ -413,12 +543,18 @@ module.exports.MatrixHttpApi.prototype = {
     * occurred. This includes network problems and Matrix-specific error JSON.
     */
    requestOtherUrl: function(callback, method, uri, queryParams, data,
-                                localTimeoutMs) {
-        if (!queryParams) {
-            queryParams = {};
+                              opts) {
+        if (opts === undefined || opts === null) {
+            opts = {};
+        } else if (isFinite(opts)) {
+            // opts used to be localTimeoutMs
+            opts = {
+                localTimeoutMs: opts
+            };
        }
+
        return this._request(
-            callback, method, uri, queryParams, data, localTimeoutMs
+            callback, method, uri, queryParams, data, opts
        );
    },

@@ -441,27 +577,56 @@ module.exports.MatrixHttpApi.prototype = {
        return this.opts.baseUrl + prefix + path + queryString;
    },

-    _request: function(callback, method, uri, queryParams, data, localTimeoutMs) {
+    /**
+     * @private
+     *
+     * @param {function} callback
+     * @param {string} method
+     * @param {string} uri
+     * @param {object} queryParams
+     * @param {object|string} data
+     * @param {object=} opts
+     *
+     * @param {boolean} [opts.json =true] Json-encode data before sending, and
+     *   decode response on receipt. (We will still json-decode error
+     *   responses, even if this is false.)
+     *
+     * @param {object=} opts.headers  extra request headers
+     *
+     * @param {number=} opts.localTimeoutMs client-side timeout for the
+     *    request. No timeout if undefined.
+     *
+     * @param {function=} opts.bodyParser function to parse the body of the
+     *    response before passing it to the promise and callback.
+     *
+     * @return {module:client.Promise} a promise which resolves to either the
+     * response object (if this.opts.onlyData is truthy), or the parsed
+     * body. Rejects
+     */
+    _request: function(callback, method, uri, queryParams, data, opts) {
        if (callback !== undefined && !utils.isFunction(callback)) {
            throw Error(
                "Expected callback to be a function but got " + typeof callback
            );
        }
+        opts = opts || {};
+
        var self = this;
-        if (!queryParams) {
-            queryParams = {};
-        }
        if (this.opts.extraParams) {
            for (var key in this.opts.extraParams) {
                if (!this.opts.extraParams.hasOwnProperty(key)) { continue; }
                queryParams[key] = this.opts.extraParams[key];
            }
        }
+
+        var json = opts.json === undefined ? true : opts.json;
+
        var defer = q.defer();

        var timeoutId;
        var timedOut = false;
        var req;
+        var localTimeoutMs = opts.localTimeoutMs;
        if (localTimeoutMs) {
            timeoutId = callbacks.setTimeout(function() {
                timedOut = true;
@@ -486,8 +651,9 @@ module.exports.MatrixHttpApi.prototype = {
                    withCredentials: false,
                    qs: queryParams,
                    body: data,
-                    json: true,
+                    json: json,
                    timeout: localTimeoutMs,
+                    headers: opts.headers || {},
                    _matrix_opts: this.opts
                },
                function(err, response, body) {
@@ -497,7 +663,15 @@ module.exports.MatrixHttpApi.prototype = {
                            return; // already rejected promise
                        }
                    }
-                    var handlerFn = requestCallback(defer, callback, self.opts.onlyData);
+
+                    // if json is falsy, we won't parse any error response, so need
+                    // to do so before turning it into a MatrixError
+                    var parseErrorJson = !json;
+                    var handlerFn = requestCallback(
+                        defer, callback, self.opts.onlyData,
+                        parseErrorJson,
+                        opts.bodyParser
+                    );
                    handlerFn(err, response, body);
                }
            );
@@ -524,14 +698,34 @@ module.exports.MatrixHttpApi.prototype = {
 *
 * If onlyData is true, the defer/callback is invoked with the body of the
 * response, otherwise the result code.
+ *
+ * If parseErrorJson is true, we will JSON.parse the body if we get a 4xx error.
+ *
 */
-var requestCallback = function(defer, userDefinedCallback, onlyData) {
+var requestCallback = function(
+    defer, userDefinedCallback, onlyData,
+    parseErrorJson, bodyParser
+) {
    userDefinedCallback = userDefinedCallback || function() {};

    return function(err, response, body) {
-        if (!err && response.statusCode >= 400) {
-            err = new module.exports.MatrixError(body);
-            err.httpStatus = response.statusCode;
+        if (!err) {
+            try {
+                if (response.statusCode >= 400) {
+                    if (parseErrorJson) {
+                        // we won't have json-decoded the response.
+                        body = JSON.parse(body);
+                    }
+                    err = new module.exports.MatrixError(body);
+                } else if (bodyParser) {
+                    body = bodyParser(body);
+                }
+            } catch (e) {
+                err = e;
+            }
+            if (err) {
+                err.httpStatus = response.statusCode;
+            }
        }

        if (err) {
@@ -0,0 +1,228 @@
+/*
+Copyright 2016 OpenMarket Ltd
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+"use strict";
+
+/** @module interactive-auth */
+var q = require("q");
+
+var utils = require("./utils");
+
+/**
+ * Abstracts the logic used to drive the interactive auth process.
+ *
+ * <p>Components implementing an interactive auth flow should instantiate one of
+ * these, passing in the necessary callbacks to the constructor. They should
+ * then call attemptAuth, which will return a promise which will resolve or
+ * reject when the interactive-auth process completes.
+ *
+ * <p>Meanwhile, calls will be made to the startAuthStage and doRequest
+ * callbacks, and information gathered from the user can be submitted with
+ * submitAuthDict.
+ *
+ * @constructor
+ * @alias module:interactive-auth
+ *
+ * @param {object} opts  options object
+ *
+ * @param {object?} opts.authData error response from the last request. If
+ *    null, a request will be made with no auth before starting.
+ *
+ * @param {function(object?): module:client.Promise} opts.doRequest
+ *     called with the new auth dict to submit the request. Should return a
+ *     promise which resolves to the successful response or rejects with a
+ *     MatrixError.
+ *
+ * @param {function(string, object?)} opts.startAuthStage
+ *     called to ask the UI to start a particular auth stage. The arguments
+ *     are: the login type (eg m.login.password); and (if the last request
+ *     returned an error), an error object, with fields 'errcode' and 'error'.
+ *
+ */
+function InteractiveAuth(opts) {
+    this._data = opts.authData;
+    this._requestCallback = opts.doRequest;
+    this._startAuthStageCallback = opts.startAuthStage;
+    this._completionDeferred = null;
+}
+
+InteractiveAuth.prototype = {
+    /**
+     * begin the authentication process.
+     *
+     * @return {module:client.Promise}  which resolves to the response on success,
+     * or rejects with the error on failure.
+     */
+    attemptAuth: function() {
+        this._completionDeferred = q.defer();
+
+        if (!this._data) {
+            this._doRequest(null);
+        } else {
+            this._startNextAuthStage();
+        }
+
+        return this._completionDeferred.promise;
+    },
+
+    /**
+     * get the auth session ID
+     *
+     * @return {string} session id
+     */
+    getSessionId: function() {
+        return this._data ? this._data.session : undefined;
+    },
+
+    /**
+     * get the server params for a given stage
+     *
+     * @param {string}  login type for the stage
+     * @return {object?}  any parameters from the server for this stage
+     */
+    getStageParams: function(loginType) {
+        var params = {};
+        if (this._data && this._data.params) {
+            params = this._data.params;
+        }
+        return params[loginType];
+    },
+
+    /**
+     * submit a new auth dict and fire off the request. This will either
+     * make attemptAuth resolve/reject, or cause the startAuthStage callback
+     * to be called for a new stage.
+     *
+     * @param {object} authData new auth dict to send to the server. Should
+     *    include a `type` propterty denoting the login type, as well as any
+     *    other params for that stage.
+     */
+    submitAuthDict: function(authData) {
+        if (!this._completionDeferred) {
+            throw new Error("submitAuthDict() called before attemptAuth()");
+        }
+
+        // use the sessionid from the last request.
+        var auth = {
+            session: this._data.session,
+        };
+        utils.extend(auth, authData);
+
+        this._doRequest(auth);
+    },
+
+    /**
+     * Fire off a request, and either resolve the promise, or call
+     * startAuthStage.
+     *
+     * @private
+     * @param {object?} auth new auth dict, including session id
+     */
+    _doRequest: function(auth) {
+        var self = this;
+
+        // hackery to make sure that synchronous exceptions end up in the catch
+        // handler (without the additional event loop entailed by q.fcall or an
+        // extra q().then)
+        var prom;
+        try {
+            prom = this._requestCallback(auth);
+        } catch (e) {
+            prom = q.reject(e);
+        }
+
+        prom.then(
+            function(result) {
+                console.log("result from request: ", result);
+                self._completionDeferred.resolve(result);
+            }, function(error) {
+                if (error.httpStatus !== 401 || !error.data || !error.data.flows) {
+                    // doesn't look like an interactive-auth failure. fail the whole lot.
+                    throw error;
+                }
+                self._data = error.data;
+                self._startNextAuthStage();
+            }
+        ).catch(this._completionDeferred.reject).done();
+    },
+
+    /**
+     * Pick the next stage and call the callback
+     *
+     * @private
+     */
+    _startNextAuthStage: function() {
+        var nextStage = this._chooseStage();
+        if (!nextStage) {
+            throw new Error("No incomplete flows from the server");
+        }
+
+        var stageError = null;
+        if (this._data.errcode || this._data.error) {
+            stageError = {
+                errcode: this._data.errcode || "",
+                error: this._data.error || "",
+            };
+        }
+        this._startAuthStageCallback(nextStage, stageError);
+    },
+
+    /**
+     * Pick the next auth stage
+     *
+     * @private
+     * @return {string?} login type
+     */
+    _chooseStage: function() {
+        var flow = this._chooseFlow();
+        console.log("Active flow => %s", JSON.stringify(flow));
+        var nextStage = this._firstUncompletedStage(flow);
+        console.log("Next stage: %s", nextStage);
+        return nextStage;
+    },
+
+    /**
+     * Pick one of the flows from the returned list
+     *
+     * @private
+     * @return {object} flow
+     */
+    _chooseFlow: function() {
+        var flows = this._data.flows || [];
+        // always use the first flow for now
+        return flows[0];
+    },
+
+    /**
+     * Get the first uncompleted stage in the given flow
+     *
+     * @private
+     * @param {object} flow
+     * @return {string} login type
+     */
+    _firstUncompletedStage: function(flow) {
+        var completed = (this._data || {}).completed || [];
+        for (var i = 0; i < flow.stages.length; ++i) {
+            var stageType = flow.stages[i];
+            if (completed.indexOf(stageType) === -1) {
+                return stageType;
+            }
+        }
+    },
+};
+
+
+/** */
+module.exports = InteractiveAuth;
@@ -55,6 +55,9 @@ module.exports.ContentRepo = require("./content-repo");
 module.exports.Filter = require("./filter");
 /** The {@link module:timeline-window~TimelineWindow} class. */
 module.exports.TimelineWindow = require("./timeline-window").TimelineWindow;
+/** The {@link module:interactive-auth} class. */
+module.exports.InteractiveAuth = require("./interactive-auth");
+

 /**
 * Create a new Matrix Call.
@@ -54,6 +54,12 @@ module.exports.EventStatus = {
 * @param {Object=} clearEvent For encrypted events, the plaintext payload for
 * the event (typically containing <tt>type</tt> and <tt>content</tt> fields).
 *
+ * @param {Object=} keysProved Keys owned by the sender of this event.
+ *    See {@link module:models/event.MatrixEvent#getKeysProved}.
+ *
+ * @param {Object=} keysClaimed Keys the sender of this event claims.
+ *    See {@link module:models/event.MatrixEvent#getKeysClaimed}.
+ *
 * @prop {Object} event The raw (possibly encrypted) event. <b>Do not access
 * this property</b> directly unless you absolutely have to. Prefer the getter
 * methods defined on this class. Using the getter methods shields your app
@@ -68,7 +74,9 @@ module.exports.EventStatus = {
 * that getDirectionalContent() will return event.content and not event.prev_content.
 * Default: true. <strong>This property is experimental and may change.</strong>
 */
-module.exports.MatrixEvent = function MatrixEvent(event, clearEvent) {
+module.exports.MatrixEvent = function MatrixEvent(
+    event, clearEvent, keysProved, keysClaimed
+) {
    this.event = event || {};
    this.sender = null;
    this.target = null;
@@ -77,6 +85,9 @@ module.exports.MatrixEvent = function MatrixEvent(event, clearEvent) {

    this._clearEvent = clearEvent || {};
    this._pushActions = null;
+
+    this._keysProved = keysProved || {};
+    this._keysClaimed = keysClaimed || {};
 };

 module.exports.MatrixEvent.prototype = {
@@ -221,11 +232,11 @@ module.exports.MatrixEvent.prototype = {
        this._clearEvent = {
            type: this.event.type,
            content: this.event.content,
-            keysProved: keys,
-            keysClaimed: keys,
        };
        this.event.type = crypto_type;
        this.event.content = crypto_content;
+        this._keysProved = keys;
+        this._keysClaimed = keys;
    },

    /**
@@ -246,32 +257,28 @@ module.exports.MatrixEvent.prototype = {

    /**
     * The keys that must have been owned by the sender of this encrypted event.
+     * <p>
     * These don't necessarily have to come from this event itself, but may be
     * implied by the cryptographic session.
-     * For example megolm messages don't prove keys directly, but instead
-     * inherit a proof from the olm message that established the session.
-     * @return {object}
+     *
+     * @return {Object<string, string>}
     */
    getKeysProved: function() {
-        // The keysProved property usually isn't actually part of the decrypted
-        // plaintext. Instead it is added after decryption by the crypto
-        // algorithm in lib/crypto/algorithms.
-        return this._clearEvent.keysProved || {};
+        return this._keysProved;
    },

    /**
-     * The additional keys the sender of this encrypted event claims to possess
+     * The additional keys the sender of this encrypted event claims to possess.
+     * <p>
     * These don't necessarily have to come from this event itself, but may be
     * implied by the cryptographic session.
     * For example megolm messages don't claim keys directly, but instead
     * inherit a claim from the olm message that established the session.
-     * @return {object}
+     *
+     * @return {Object<string, string>}
     */
    getKeysClaimed: function() {
-        // The keysClaimed property usually isn't actually part of the
-        // decrypted plaintext. Instead it is added after decryption by the
-        // crypto algorithm in lib/crypto/algorithms.
-        return this._clearEvent.keysClaimed || {};
+        return this._keysClaimed;
    },

    getUnsigned: function() {
@@ -66,7 +66,6 @@ function SyncApi(client, opts) {
    opts.pendingEventOrdering = opts.pendingEventOrdering || "chronological";
    this.opts = opts;
    this._peekRoomId = null;
-    this._syncConnectionLost = false;
    this._currentSyncRequest = null;
    this._syncState = null;
    this._running = false;
@@ -392,8 +391,13 @@ SyncApi.prototype.sync = function() {
    }

    function getFilter() {
-        var filter = new Filter(client.credentials.userId);
-        filter.setTimelineLimit(self.opts.initialSyncLimit);
+        var filter;
+        if (self.opts.filter) {
+            filter = self.opts.filter;
+        } else {
+            filter = new Filter(client.credentials.userId);
+            filter.setTimelineLimit(self.opts.initialSyncLimit);
+        }

        client.getOrCreateFilter(
            getFilterName(client.credentials.userId), filter
@@ -491,7 +495,7 @@ SyncApi.prototype._sync = function(syncOptions) {
        qps._cacheBuster = Date.now();
    }

-    if (self._syncConnectionLost) {
+    if (this.getSyncState() == 'ERROR' || this.getSyncState() == 'RECONNECTING') {
        // we think the connection is dead. If it comes back up, we won't know
        // about it till /sync returns. If the timeout= is high, this could
        // be a long time. Set it to 0 when doing retries so we don't have to wait
@@ -507,8 +511,6 @@ SyncApi.prototype._sync = function(syncOptions) {
    );

    this._currentSyncRequest.done(function(data) {
-        self._syncConnectionLost = false;
-
        // set the sync token NOW *before* processing the events. We do this so
        // if something barfs on an event we can skip it rather than constantly
        // polling with the same token.
@@ -546,12 +548,18 @@ SyncApi.prototype._sync = function(syncOptions) {
        console.error(err);

        debuglog("Starting keep-alive");
-        self._syncConnectionLost = true;
+        // Note that we do *not* mark the sync connection as
+        // lost yet: we only do this if a keepalive poke
+        // fails, since long lived HTTP connections will
+        // go away sometimes and we shouldn't treat this as
+        // erroneous. We set the state to 'reconnecting'
+        // instead, so that clients can onserve this state
+        // if they wish.
        self._startKeepAlives().done(function() {
            self._sync(syncOptions);
        });
        self._currentSyncRequest = null;
-        self._updateSyncState("ERROR", { error: err });
+        self._updateSyncState("RECONNECTING");
    });
 };

@@ -844,17 +852,21 @@ SyncApi.prototype._processSyncResponse = function(syncToken, data) {
 */
 SyncApi.prototype._startKeepAlives = function(delay) {
    if (delay === undefined) {
-        delay = 5000 + Math.floor(Math.random() * 5000);
+        delay = 2000 + Math.floor(Math.random() * 5000);
    }

    if (this._keepAliveTimer !== null) {
        clearTimeout(this._keepAliveTimer);
    }
    var self = this;
-    self._keepAliveTimer = setTimeout(
-        self._pokeKeepAlive.bind(self),
-        delay
-    );
+    if (delay > 0) {
+        self._keepAliveTimer = setTimeout(
+            self._pokeKeepAlive.bind(self),
+            delay
+        );
+    } else {
+        self._pokeKeepAlive();
+    }
    if (!this._connectionReturnedDefer) {
        this._connectionReturnedDefer = q.defer();
    }
@@ -874,9 +886,15 @@ SyncApi.prototype._pokeKeepAlive = function() {
        }
    }

-    this.client._http.requestWithPrefix(
-        undefined, "GET", "/_matrix/client/versions", undefined,
-        undefined, "", 15 * 1000
+    this.client._http.request(
+        undefined, // callback
+        "GET", "/_matrix/client/versions",
+        undefined, // queryParams
+        undefined, // data
+        {
+            prefix: '',
+            localTimeoutMs: 15 * 1000,
+        }
    ).done(function() {
        success();
    }, function(err) {
@@ -892,6 +910,13 @@ SyncApi.prototype._pokeKeepAlive = function() {
                self._pokeKeepAlive.bind(self),
                5000 + Math.floor(Math.random() * 5000)
            );
+            // A keepalive has failed, so we emit the
+            // error state (whether or not this is the
+            // first failure).
+            // Note we do this after setting the timer:
+            // this lets the unit tests advance the mock
+            // clock when the get the error.
+            self._updateSyncState("ERROR", { error: err });
        }
    });
 };
@@ -337,6 +337,9 @@ var deepCompare = module.exports.deepCompare = function(x, y) {
 *
 * All enumerable properties, included inherited ones, are copied.
 *
+ * This is approximately equivalent to ES6's Object.assign, except
+ * that the latter doesn't copy inherited properties.
+ *
 * @param {Object} target  The object that will receive new properties
 * @param {...Object} source  Objects from which to copy properties
 *
@@ -1,18 +1,17 @@
 {
  "name": "matrix-js-sdk",
-  "version": "0.5.6",
+  "version": "0.6.4",
  "description": "Matrix Client-Server SDK for Javascript",
  "main": "index.js",
  "scripts": {
    "test": "istanbul cover --report cobertura --config .istanbul.yml -i \"lib/**/*.js\" jasmine-node -- spec --verbose --junitreport --captureExceptions",
    "check": "jasmine-node spec --verbose --junitreport --captureExceptions",
    "gendoc": "jsdoc -r lib -P package.json -R README.md -d .jsdoc",
-    "build": "jshint -c .jshint lib/ && browserify browser-index.js -o dist/browser-matrix-dev.js --ignore-missing",
-    "watch": "watchify browser-index.js -o dist/browser-matrix-dev.js -v",
+    "build": "jshint -c .jshint lib/ && rimraf dist && mkdir dist && browserify --exclude olm browser-index.js -o dist/browser-matrix.js --ignore-missing && uglifyjs -c -m -o dist/browser-matrix.min.js dist/browser-matrix.js",
+    "dist": "npm run build",
+    "watch": "watchify --exclude olm browser-index.js -o dist/browser-matrix-dev.js -v",
    "lint": "jshint -c .jshint lib spec && gjslint --unix_mode --disable 0131,0211,0200,0222,0212 --max_line_length 90 -r spec/ -r lib/",
-    "release": "npm run build && mkdir -p dist/$npm_package_version && uglifyjs -c -m -o dist/$npm_package_version/browser-matrix-$npm_package_version.min.js dist/browser-matrix-dev.js && cp dist/browser-matrix-dev.js dist/$npm_package_version/browser-matrix-$npm_package_version.js",
-    "prepublish": "git rev-parse HEAD > git-revision.txt",
-    "version": "npm run release && git add dist/$npm_package_version"
+    "prepublish": "git rev-parse HEAD > git-revision.txt"
  },
  "repository": {
    "url": "https://github.com/matrix-org/matrix-js-sdk"
@@ -23,6 +22,23 @@
  "browser": "browser-index.js",
  "author": "matrix.org",
  "license": "Apache-2.0",
+  "files": [
+    "CHANGELOG.md",
+    "CONTRIBUTING.rst",
+    "LICENSE",
+    "README.md",
+    "RELEASING.md",
+    "examples",
+    "git-hooks",
+    "git-revision.txt",
+    "index.js",
+    "browser-index.js",
+    "jenkins.sh",
+    "lib",
+    "package.json",
+    "release.sh",
+    "spec"
+  ],
  "dependencies": {
    "another-json": "^0.2.0",
    "browser-request": "^0.3.3",
@@ -31,12 +47,13 @@
    "request": "^2.53.0"
  },
  "devDependencies": {
-    "watchify": "^3.2.1",
    "istanbul": "^0.3.13",
    "jasmine-node": "^1.14.5",
-    "jshint": "^2.8.0",
    "jsdoc": "^3.4.0",
-    "uglifyjs": "^2.4.10"
+    "jshint": "^2.8.0",
+    "rimraf": "^2.5.4",
+    "uglifyjs": "^2.4.10",
+    "watchify": "^3.2.1"
  },
  "optionalDependencies": {
    "olm": "https://matrix.org/packages/npm/olm/olm-1.3.0.tgz"
@@ -1,13 +1,18 @@
-#!/bin/sh
+#!/bin/bash
 #
 # Script to perform a release of matrix-js-sdk. Performs the steps documented
 # in RELEASING.md
 #
-# Requires github-changelog-generator; to install, do
-#   pip install git+https://github.com/matrix-org/github-changelog-generator.git
+# Requires:
+#   github-changelog-generator; to install, do
+#     pip install git+https://github.com/matrix-org/github-changelog-generator.git
+#   jq; install from your distibution's package manager (https://stedolan.github.io/jq/)

 set -e

+jq --version > /dev/null || (echo "jq is required: please install it"; exit)
+hub --version > /dev/null || (echo "hub is required: please install it"; exit)
+
 USAGE="$0 [-xz] [-c changelog_file] vX.Y.Z"

 help() {
@@ -20,6 +25,13 @@ $USAGE
 EOF
 }

+ret=0
+cat package.json | jq '.dependencies[]' | grep -q '#develop' || ret=$?
+if [ "$ret" -eq 0 ]; then
+    echo "package.json contains develop dependencies. Refusing to release."
+    exit
+fi
+
 skip_changelog=
 skip_jsdoc=
 changelog_file="CHANGELOG.md"
@@ -47,11 +59,27 @@ if [ $# -ne 1 ]; then
    exit 1
 fi

+if [ -z "$skip_changelog" ]; then
+    # update_changelog doesn't have a --version flag
+    update_changelog -h > /dev/null || (echo "github-changelog-generator is required: please install it"; exit)
+fi
+
 # ignore leading v on release
 release="${1#v}"
 tag="v${release}"
 rel_branch="release-$tag"

+prerelease=0
+# We check if this build is a prerelease by looking to
+# see if the version has a hyphen in it. Crude,
+# but semver doesn't support postreleases so anything
+# with a hyphen is a prerelease.
+echo $release | grep -q '-' && prerelease=1
+
+if [ $prerelease -eq 1 ]; then
+    echo Making a PRE-RELEASE
+fi
+
 if [ -z "$skip_changelog" ]; then
    if ! command -v update_changelog >/dev/null 2>&1; then
        echo "release.sh requires github-changelog-generator. Try:" >&2
@@ -61,9 +89,16 @@ if [ -z "$skip_changelog" ]; then
 fi

 # we might already be on the release branch, in which case, yay
-if [ $(git symbolic-ref --short HEAD) != "$rel_branch" ]; then
+# If we're on any branch starting with 'release', we don't create
+# a separate release branch (this allows us to use the same
+# release branch for releases and release candidates).
+curbranch=$(git symbolic-ref --short HEAD)
+if [[ "$curbranch" != release* ]]; then
    echo "Creating release branch"
    git checkout -b "$rel_branch"
+else
+    echo "Using current branch ($curbranch) for release"
+    rel_branch=$curbranch
 fi

 if [ -z "$skip_changelog" ]; then
@@ -81,7 +116,54 @@ set -x

 # Bump package.json, build the dist, and tag
 echo "npm version"
-npm version "$release"
+# npm version will automatically commit its modification
+# and make a release tag. We don't want it to create the tag
+# because github will do that, but we can only turn off both
+# of these behaviours, so we have to manually commit the
+# result.
+npm version --no-git-tag-version "$release"
+git commit package.json -m "$tag"
+
+# If there is a 'dist' script in the package.json,
+# run it in a separate checkout of the project, then
+# upload any files in the 'dist' directory as release
+# assets.
+# We make a completely separate checkout to be sure
+# we're using released versions of the dependencies
+# (rather than whatever we're pulling in from npm link)
+assets=''
+dodist=0
+jq -e .scripts.dist package.json 2> /dev/null || dodist=$?
+if [ $dodist -eq 0 ]; then
+    projdir=`pwd`
+    builddir=`mktemp -d 2>/dev/null || mktemp -d -t 'mytmpdir'`
+    echo "Building distribution copy in $builddir"
+    pushd "$builddir"
+    git clone "$projdir" .
+    git co "$rel_branch"
+    npm install
+    # We haven't tagged yet, so tell the dist script what version
+    # it's building
+    DIST_VERSION="$tag" npm run dist
+    popd
+    for i in "$builddir"/dist/*; do
+        assets="$assets -a $i"
+    done
+fi
+
+# push the release branch (github can't release from
+# a branch it doesn't have)
+git push origin "$rel_branch"
+
+hubflags=''
+if [ $prerelease -eq 1 ]; then
+    hubflags='-p'
+fi
+hub release create $hubflags $assets -m "$tag" "$tag"
+
+if [ $dodist -eq 0 ]; then
+    rm -rf "$builddir"
+fi

 if [ -z "$skip_jsdoc" ]; then
    echo "generating jsdocs"
@@ -104,8 +186,8 @@ git checkout master
 git pull
 git merge --ff-only "$rel_branch"

-# push everything to github
-git push origin master "$rel_branch" "$tag"
+# push master  and docs (if generated) to github
+git push origin master
 if [ -z "$skip_jsdoc" ]; then
    git push origin gh-pages
 fi
@@ -61,7 +61,7 @@ function expectKeyUpload(deviceId, httpBackend) {
        expect(content.one_time_keys).not.toBeDefined();
        expect(content.device_keys).toBeDefined();
        keys.device_keys = content.device_keys;
-        return {one_time_key_counts: {curve25519: 0}};
+        return {one_time_key_counts: {signed_curve25519: 0}};
    });

    httpBackend.when("POST", uploadPath).respond(200, function(path, content) {
@@ -76,7 +76,7 @@ function expectKeyUpload(deviceId, httpBackend) {
        }
        expect(count).toEqual(5);
        keys.one_time_keys = content.one_time_keys;
-        return {one_time_key_counts: {curve25519: count}};
+        return {one_time_key_counts: {signed_curve25519: count}};
    });

    return httpBackend.flush(uploadPath, 2).then(function() {
@@ -176,10 +176,11 @@ function expectAliClaimKeys() {
    expect(bobOneTimeKeys).toBeDefined();

    aliHttpBackend.when("POST", "/keys/claim").respond(200, function(path, content) {
-        expect(content.one_time_keys[bobUserId][bobDeviceId]).toEqual("curve25519");
+        var claimType = content.one_time_keys[bobUserId][bobDeviceId];
+        expect(claimType).toEqual("signed_curve25519");
        for (var keyId in bobOneTimeKeys) {
            if (bobOneTimeKeys.hasOwnProperty(keyId)) {
-                if (keyId.indexOf("curve25519:") === 0) {
+                if (keyId.indexOf(claimType + ":") === 0) {
                    break;
                }
            }
@@ -338,15 +339,15 @@ function expectSendMessageRequest(httpBackend) {

 function aliRecvMessage() {
    var message = bobMessages.shift();
-    return recvMessage(aliHttpBackend, aliClient, message);
+    return recvMessage(aliHttpBackend, aliClient, bobUserId, message);
 }

 function bobRecvMessage() {
    var message = aliMessages.shift();
-    return recvMessage(bobHttpBackend, bobClient, message);
+    return recvMessage(bobHttpBackend, bobClient, aliUserId, message);
 }

-function recvMessage(httpBackend, client, message) {
+function recvMessage(httpBackend, client, sender, message) {
    var syncData = {
        next_batch: "x",
        rooms: {
@@ -361,7 +362,8 @@ function recvMessage(httpBackend, client, message) {
                test_utils.mkEvent({
                    type: "m.room.encrypted",
                    room: roomId,
-                    content: message
+                    content: message,
+                    sender: sender,
                })
            ]
        }
@@ -529,6 +531,77 @@ describe("MatrixClient crypto", function() {
            .catch(test_utils.failTest).done(done);
    });

+    it("Ali gets keys with an incorrect userId", function(done) {
+        var eveUserId = "@eve:localhost";
+
+        var bobDeviceKeys = {
+            algorithms: ['m.olm.v1.curve25519-aes-sha2', 'm.megolm.v1.aes-sha2'],
+            device_id: 'bvcxz',
+            keys: {
+                'ed25519:bvcxz': 'pYuWKMCVuaDLRTM/eWuB8OlXEb61gZhfLVJ+Y54tl0Q',
+                'curve25519:bvcxz': '7Gni0loo/nzF0nFp9847RbhElGewzwUXHPrljjBGPTQ',
+            },
+            user_id: '@eve:localhost',
+            signatures: {
+                '@eve:localhost': {
+                    'ed25519:bvcxz': 'CliUPZ7dyVPBxvhSA1d+X+LYa5b2AYdjcTwG' +
+                        '0stXcIxjaJNemQqtdgwKDtBFl3pN2I13SEijRDCf1A8bYiQMDg',
+                },
+            },
+        };
+
+        var bobKeys = {};
+        bobKeys[bobDeviceId] = bobDeviceKeys;
+        aliHttpBackend.when("POST", "/keys/query").respond(200, function(path, content) {
+            var result = {};
+            result[bobUserId] = bobKeys;
+            return {device_keys: result};
+        });
+
+        q.all(
+            aliClient.downloadKeys([bobUserId, eveUserId]),
+            aliHttpBackend.flush("/keys/query", 1)
+        ).then(function() {
+            // should get an empty list
+            expect(aliClient.listDeviceKeys(bobUserId)).toEqual([]);
+            expect(aliClient.listDeviceKeys(eveUserId)).toEqual([]);
+        }).catch(test_utils.failTest).done(done);
+    });
+
+    it("Ali gets keys with an incorrect deviceId", function(done) {
+        var bobDeviceKeys = {
+            algorithms: ['m.olm.v1.curve25519-aes-sha2', 'm.megolm.v1.aes-sha2'],
+            device_id: 'bad_device',
+            keys: {
+                'ed25519:bad_device': 'e8XlY5V8x2yJcwa5xpSzeC/QVOrU+D5qBgyTK0ko+f0',
+                'curve25519:bad_device': 'YxuuLG/4L5xGeP8XPl5h0d7DzyYVcof7J7do+OXz0xc',
+            },
+            user_id: '@bob:localhost',
+            signatures: {
+                '@bob:localhost': {
+                    'ed25519:bad_device': 'fEFTq67RaSoIEVBJ8DtmRovbwUBKJ0A' +
+                        'me9m9PDzM9azPUwZ38Xvf6vv1A7W1PSafH4z3Y2ORIyEnZgHaNby3CQ',
+                },
+            },
+        };
+
+        var bobKeys = {};
+        bobKeys[bobDeviceId] = bobDeviceKeys;
+        aliHttpBackend.when("POST", "/keys/query").respond(200, function(path, content) {
+            var result = {};
+            result[bobUserId] = bobKeys;
+            return {device_keys: result};
+        });
+
+        q.all(
+            aliClient.downloadKeys([bobUserId]),
+            aliHttpBackend.flush("/keys/query", 1)
+        ).then(function() {
+            // should get an empty list
+            expect(aliClient.listDeviceKeys(bobUserId)).toEqual([]);
+        }).catch(test_utils.failTest).done(done);
+    });
+
    it("Ali enables encryption", function(done) {
        q()
            .then(bobUploadsKeys)
@@ -557,6 +630,63 @@ describe("MatrixClient crypto", function() {
            .catch(test_utils.failTest).done(done);
    });

+    it("Bob receives a message with a bogus sender", function(done) {
+        q()
+            .then(bobUploadsKeys)
+            .then(aliStartClient)
+            .then(aliEnablesEncryption)
+            .then(aliSendsFirstMessage)
+            .then(bobStartClient)
+            .then(function() {
+                var message = aliMessages.shift();
+                var syncData = {
+                    next_batch: "x",
+                    rooms: {
+                        join: {
+
+                        }
+                    }
+                };
+                syncData.rooms.join[roomId] = {
+                    timeline: {
+                        events: [
+                            test_utils.mkEvent({
+                                type: "m.room.encrypted",
+                                room: roomId,
+                                content: message,
+                                sender: "@bogus:sender",
+                            })
+                        ]
+                    }
+                };
+                bobHttpBackend.when("GET", "/sync").respond(200, syncData);
+
+                var deferred = q.defer();
+                var onEvent = function(event) {
+                    console.log(bobClient.credentials.userId + " received event",
+                                event);
+
+                    // ignore the m.room.member events
+                    if (event.getType() == "m.room.member") {
+                        return;
+                    }
+
+                    expect(event.getType()).toEqual("m.room.message");
+                    expect(event.getContent().msgtype).toEqual("m.bad.encrypted");
+                    expect(event.isEncrypted()).toBeTruthy();
+
+                    bobClient.removeListener("event", onEvent);
+                    deferred.resolve();
+                };
+
+                bobClient.on("event", onEvent);
+
+                bobHttpBackend.flush();
+                return deferred.promise;
+            })
+            .catch(test_utils.failTest).done(done);
+    });
+
    it("Ali blocks Bob's device", function(done) {
        q()
            .then(bobUploadsKeys)
@@ -37,6 +37,117 @@ describe("MatrixClient", function() {
        httpBackend.verifyNoOutstandingExpectation();
    });

+    describe("uploadContent", function() {
+        var buf = new Buffer('hello world');
+        it("should upload the file", function(done) {
+            httpBackend.when(
+                "POST", "/_matrix/media/v1/upload"
+            ).check(function(req) {
+                expect(req.data).toEqual(buf);
+                expect(req.queryParams.filename).toEqual("hi.txt");
+                expect(req.queryParams.access_token).toEqual(accessToken);
+                expect(req.headers["Content-Type"]).toEqual("text/plain");
+                expect(req.opts.json).toBeFalsy();
+                expect(req.opts.timeout).toBe(undefined);
+            }).respond(200, "content");
+
+            var prom = client.uploadContent({
+                stream: buf,
+                name: "hi.txt",
+                type: "text/plain",
+            });
+
+            expect(prom).toBeDefined();
+
+            var uploads = client.getCurrentUploads();
+            expect(uploads.length).toEqual(1);
+            expect(uploads[0].promise).toBe(prom);
+            expect(uploads[0].loaded).toEqual(0);
+
+            prom.then(function(response) {
+                // for backwards compatibility, we return the raw JSON
+                expect(response).toEqual("content");
+
+                var uploads = client.getCurrentUploads();
+                expect(uploads.length).toEqual(0);
+            }).catch(utils.failTest).done(done);
+
+            httpBackend.flush();
+        });
+
+        it("should parse the response if rawResponse=false", function(done) {
+            httpBackend.when(
+                "POST", "/_matrix/media/v1/upload"
+            ).check(function(req) {
+                expect(req.opts.json).toBeFalsy();
+            }).respond(200, JSON.stringify({ "content_uri": "uri" }));
+
+            client.uploadContent({
+                stream: buf,
+                name: "hi.txt",
+                type: "text/plain",
+            }, {
+                rawResponse: false,
+            }).then(function(response) {
+                expect(response.content_uri).toEqual("uri");
+            }).catch(utils.failTest).done(done);
+
+            httpBackend.flush();
+        });
+
+        it("should parse errors into a MatrixError", function(done) {
+            // opts.json is false, so request returns unparsed json.
+            httpBackend.when(
+                "POST", "/_matrix/media/v1/upload"
+            ).check(function(req) {
+                expect(req.data).toEqual(buf);
+                expect(req.opts.json).toBeFalsy();
+            }).respond(400, JSON.stringify({
+                "errcode": "M_SNAFU",
+                "error": "broken",
+            }));
+
+            client.uploadContent({
+                stream: buf,
+                name: "hi.txt",
+                type: "text/plain",
+            }).then(function(response) {
+                throw Error("request not failed");
+            }, function(error) {
+                expect(error.httpStatus).toEqual(400);
+                expect(error.errcode).toEqual("M_SNAFU");
+                expect(error.message).toEqual("broken");
+            }).catch(utils.failTest).done(done);
+
+            httpBackend.flush();
+        });
+
+        it("should return a promise which can be cancelled", function(done) {
+            var prom = client.uploadContent({
+                stream: buf,
+                name: "hi.txt",
+                type: "text/plain",
+            });
+
+            var uploads = client.getCurrentUploads();
+            expect(uploads.length).toEqual(1);
+            expect(uploads[0].promise).toBe(prom);
+            expect(uploads[0].loaded).toEqual(0);
+
+            prom.then(function(response) {
+                throw Error("request not aborted");
+            }, function(error) {
+                expect(error).toEqual("aborted");
+
+                var uploads = client.getCurrentUploads();
+                expect(uploads.length).toEqual(0);
+            }).catch(utils.failTest).done(done);
+
+            var r = client.cancelUpload(prom);
+            expect(r).toBe(true);
+        });
+    });
+
    describe("joinRoom", function() {
        it("should no-op if you've already joined a room", function() {
            var roomId = "!foo:bar";
@@ -184,58 +295,65 @@ describe("MatrixClient", function() {

    describe("downloadKeys", function() {
        it("should do an HTTP request and then store the keys", function(done) {
-            var ed25519key = "wV5E3EUSHpHuoZLljNzojlabjGdXT3Mz7rugG9zgbkI";
+            var ed25519key = "7wG2lzAqbjcyEkOP7O4gU7ItYcn+chKzh5sT/5r2l78";
+            // ed25519key = client.getDeviceEd25519Key();
            var borisKeys = {
                dev1: {
-                    algorithms: ["1"], keys: { "ed25519:dev1": ed25519key },
+                    algorithms: ["1"],
+                    device_id: "dev1",
+                    keys: { "ed25519:dev1": ed25519key },
                    signatures: {
                        boris: {
-                           "ed25519:dev1":
-                                "u99n8WZ61G//K6eVgYc+RDLVapmjttxqhjNucIFGEIJ" +
-                                "oA4TUY8FmiGv3zl0EA71zrvPDfnFL5XLNsdc55NGbDg"
+                            "ed25519:dev1":
+                                "RAhmbNDq1efK3hCpBzZDsKoGSsrHUxb25NW5/WbEV9R" +
+                                "JVwLdP032mg5QsKt/pBDUGtggBcnk43n3nBWlA88WAw"
                        }
                    },
                    unsigned: { "abc": "def" },
+                    user_id: "boris",
                }
            };
            var chazKeys = {
                dev2: {
-                    algorithms: ["2"], keys: { "ed25519:dev2": ed25519key },
+                    algorithms: ["2"],
+                    device_id: "dev2",
+                    keys: { "ed25519:dev2": ed25519key },
                    signatures: {
                        chaz: {
                           "ed25519:dev2":
-                                "8eaeXUWy9AQzjaNVOjVLs4FQk+cgobkNS811EjZBCMA" +
-                                "apd8aPOfE26E13nFFOCLC1V6fOH5wVo61hxGR/j4PBA"
-                        }
-                    },
-                    unsigned: { "ghi": "def" },
-                }
-            };
-            var daveKeys = {
-                dev3: {
-                    algorithms: ["3"], keys: { "ed25519:dev2": ed25519key },
-                    signatures: {
-                        dave: {
-                           "ed25519:dev2":
-                                "8eaeXUWy9AQzjaNVOjVLs4FQk+cgobkNS811EjZBCMA" +
-                                "apd8aPOfE26E13nFFOCLC1V6fOH5wVo61hxGR/j4PBA"
+                                "FwslH/Q7EYSb7swDJbNB5PSzcbEO1xRRBF1riuijqvL" +
+                                "EkrK9/XVN8jl4h7thGuRITQ01siBQnNmMK9t45QfcCQ"
                        }
                    },
                    unsigned: { "ghi": "def" },
+                    user_id: "chaz",
                }
            };

+            /*
+            function sign(o) {
+                var anotherjson = require('another-json');
+                var b = JSON.parse(JSON.stringify(o));
+                delete(b.signatures);
+                delete(b.unsigned);
+                return client._crypto._olmDevice.sign(anotherjson.stringify(b));
+            };
+
+            console.log("Ed25519: " + ed25519key);
+            console.log("boris:", sign(borisKeys.dev1));
+            console.log("chaz:", sign(chazKeys.dev2));
+            */
+
            httpBackend.when("POST", "/keys/query").check(function(req) {
-                expect(req.data).toEqual({device_keys: {boris: {}, chaz: {}, dave: {}}});
+                expect(req.data).toEqual({device_keys: {boris: {}, chaz: {}}});
            }).respond(200, {
                device_keys: {
                    boris: borisKeys,
                    chaz: chazKeys,
-                    dave: daveKeys,
                },
            });

-            client.downloadKeys(["boris", "chaz", "dave"]).then(function(res) {
+            client.downloadKeys(["boris", "chaz"]).then(function(res) {
                assertObjectContains(res.boris.dev1, {
                    verified: 0, // DeviceVerification.UNVERIFIED
                    keys: { "ed25519:dev1": ed25519key },
@@ -249,9 +367,6 @@ describe("MatrixClient", function() {
                    algorithms: ["2"],
                    unsigned: { "ghi": "def" },
                });
-
-                // dave's key fails validation.
-                expect(res.dave).toEqual({});
            }).catch(utils.failTest).done(done);

            httpBackend.flush();
@@ -272,6 +387,23 @@ describe("MatrixClient", function() {
            httpBackend.flush();
        });
    });
+
+    describe("deleteDevice", function() {
+        var auth = {a: 1};
+        it("should pass through an auth dict", function(done) {
+            httpBackend.when(
+                "DELETE", "/_matrix/client/unstable/devices/my_device"
+            ).check(function(req) {
+                expect(req.data).toEqual({auth: auth});
+            }).respond(200);
+
+            client.deleteDevice(
+                "my_device", auth
+            ).catch(utils.failTest).done(done);
+
+            httpBackend.flush();
+        });
+    });
 });

 function assertObjectContains(obj, expected) {
@@ -11,18 +11,17 @@ function HttpBackend() {
    var self = this;
    // the request function dependency that the SDK needs.
    this.requestFn = function(opts, callback) {
-        var realReq = new Request(opts.method, opts.uri, opts.body, opts.qs);
-        realReq.callback = callback;
-        console.log("HTTP backend received request: %s %s", opts.method, opts.uri);
-        self.requests.push(realReq);
+        var req = new Request(opts, callback);
+        console.log("HTTP backend received request: %s", req);
+        self.requests.push(req);

        var abort = function() {
-            var idx = self.requests.indexOf(realReq);
+            var idx = self.requests.indexOf(req);
            if (idx >= 0) {
                console.log("Aborting HTTP request: %s %s", opts.method,
                            opts.uri);
                self.requests.splice(idx, 1);
-                realReq.callback("aborted");
+                req.callback("aborted");
            }
        };

@@ -161,22 +160,32 @@ HttpBackend.prototype = {
     * @return {Request} An expected request.
     */
    when: function(method, path, data) {
-        var pendingReq = new Request(method, path, data);
+        var pendingReq = new ExpectedRequest(method, path, data);
        this.expectedRequests.push(pendingReq);
        return pendingReq;
    }
 };

-function Request(method, path, data, queryParams) {
+/**
+ * Represents the expectation of a request.
+ *
+ * <p>Includes the conditions to be matched against, the checks to be made,
+ * and the response to be returned.
+ *
+ * @constructor
+ * @param {string} method
+ * @param {string} path
+ * @param {object?} data
+ */
+function ExpectedRequest(method, path, data) {
    this.method = method;
    this.path = path;
    this.data = data;
-    this.queryParams = queryParams;
-    this.callback = null;
    this.response = null;
    this.checks = [];
 }
-Request.prototype = {
+
+ExpectedRequest.prototype = {
    /**
     * Execute a check when this request has been satisfied.
     * @param {Function} fn The function to execute.
@@ -221,6 +230,44 @@ Request.prototype = {
    }
 };

+/**
+ * Represents a request made by the app.
+ *
+ * @constructor
+ * @param {object} opts opts passed to request()
+ * @param {function} callback
+ */
+function Request(opts, callback) {
+    this.opts = opts;
+    this.callback = callback;
+
+    Object.defineProperty(this, 'method', {
+        get: function() { return opts.method; }
+    });
+
+    Object.defineProperty(this, 'path', {
+        get: function() { return opts.uri; }
+    });
+
+    Object.defineProperty(this, 'data', {
+        get: function() { return opts.body; }
+    });
+
+    Object.defineProperty(this, 'queryParams', {
+        get: function() { return opts.qs; }
+    });
+
+    Object.defineProperty(this, 'headers', {
+        get: function() { return opts.headers || {}; }
+    });
+}
+
+Request.prototype = {
+    toString: function() {
+        return this.method + " " + this.path;
+    },
+};
+
 /**
 * The HttpBackend class.
 */
@@ -0,0 +1,141 @@
+/*
+Copyright 2016 OpenMarket Ltd
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+"use strict";
+
+var q = require("q");
+var sdk = require("../..");
+var utils = require("../test-utils");
+
+var InteractiveAuth = sdk.InteractiveAuth;
+var MatrixError = sdk.MatrixError;
+
+describe("InteractiveAuth", function() {
+    beforeEach(function() {
+        utils.beforeEach(this);
+    });
+
+    it("should start an auth stage and complete it", function(done) {
+        var doRequest = jasmine.createSpy('doRequest');
+        var startAuthStage = jasmine.createSpy('startAuthStage');
+
+        var ia = new InteractiveAuth({
+            doRequest: doRequest,
+            startAuthStage: startAuthStage,
+            authData: {
+                session: "sessionId",
+                flows: [
+                    { stages: ["logintype"] },
+                ],
+                params: {
+                    "logintype": { param: "aa" },
+                },
+            },
+        });
+
+        expect(ia.getSessionId()).toEqual("sessionId");
+        expect(ia.getStageParams("logintype")).toEqual({
+            param: "aa",
+        });
+
+        // first we expect a call here
+        startAuthStage.andCallFake(function(stage) {
+            expect(stage).toEqual("logintype");
+            ia.submitAuthDict({
+                type: "logintype",
+                foo: "bar",
+            });
+        });
+
+        // .. which should trigger a call here
+        var requestRes = {"a": "b"};
+        doRequest.andCallFake(function(authData) {
+            expect(authData).toEqual({
+                session: "sessionId",
+                type: "logintype",
+                foo: "bar",
+            });
+            return q(requestRes);
+        });
+
+        ia.attemptAuth().then(function(res) {
+            expect(res).toBe(requestRes);
+            expect(doRequest.calls.length).toEqual(1);
+            expect(startAuthStage.calls.length).toEqual(1);
+        }).catch(utils.failTest).done(done);
+    });
+
+    it("should make a request if no authdata is provided", function(done) {
+        var doRequest = jasmine.createSpy('doRequest');
+        var startAuthStage = jasmine.createSpy('startAuthStage');
+
+        var ia = new InteractiveAuth({
+            doRequest: doRequest,
+            startAuthStage: startAuthStage,
+        });
+
+        expect(ia.getSessionId()).toBe(undefined);
+        expect(ia.getStageParams("logintype")).toBe(undefined);
+
+        // first we expect a call to doRequest
+        doRequest.andCallFake(function(authData) {
+            console.log("request1", authData);
+            expect(authData).toBe(null);
+            var err = new MatrixError({
+                session: "sessionId",
+                flows: [
+                    { stages: ["logintype"] },
+                ],
+                params: {
+                    "logintype": { param: "aa" },
+                },
+            });
+            err.httpStatus = 401;
+            throw err;
+        });
+
+        // .. which should be followed by a call to startAuthStage
+        var requestRes = {"a": "b"};
+        startAuthStage.andCallFake(function(stage) {
+            expect(stage).toEqual("logintype");
+            expect(ia.getSessionId()).toEqual("sessionId");
+            expect(ia.getStageParams("logintype")).toEqual({
+                param: "aa",
+            });
+
+            // submitAuthDict should trigger another call to doRequest
+            doRequest.andCallFake(function(authData) {
+                console.log("request2", authData);
+                expect(authData).toEqual({
+                    session: "sessionId",
+                    type: "logintype",
+                    foo: "bar",
+                });
+                return q(requestRes);
+            });
+
+            ia.submitAuthDict({
+                type: "logintype",
+                foo: "bar",
+            });
+        });
+
+        ia.attemptAuth().then(function(res) {
+            expect(res).toBe(requestRes);
+            expect(doRequest.calls.length).toEqual(2);
+            expect(startAuthStage.calls.length).toEqual(1);
+        }).catch(utils.failTest).done(done);
+    });
+});
@@ -51,9 +51,10 @@ describe("MatrixClient", function() {
        // }
        // items are popped off when processed and block if no items left.
    ];
+    var accept_keepalives;
    var pendingLookup = null;
    function httpReq(cb, method, path, qp, data, prefix) {
-        if (path === KEEP_ALIVE_PATH) {
+        if (path === KEEP_ALIVE_PATH && accept_keepalives) {
            return q();
        }
        var next = httpLookups.shift();
@@ -103,6 +104,7 @@ describe("MatrixClient", function() {
            if (next.error) {
                return q.reject({
                    errcode: next.error.errcode,
+                    httpStatus: next.error.httpStatus,
                    name: next.error.errcode,
                    message: "Expected testing error",
                    data: next.error
@@ -143,8 +145,10 @@ describe("MatrixClient", function() {
        client._http.authedRequest.andCallFake(httpReq);
        client._http.authedRequestWithPrefix.andCallFake(httpReq);
        client._http.requestWithPrefix.andCallFake(httpReq);
+        client._http.request.andCallFake(httpReq);

        // set reasonable working defaults
+        accept_keepalives = true;
        pendingLookup = null;
        httpLookups = [];
        httpLookups.push(PUSH_RULES_RESPONSE);
@@ -204,6 +208,44 @@ describe("MatrixClient", function() {
        });
    });

+    describe("getOrCreateFilter", function() {
+        it("should POST createFilter if no id is present in localStorage", function() {
+        });
+        it("should use an existing filter if id is present in localStorage", function() {
+        });
+        it("should handle localStorage filterId missing from the server", function(done) {
+            function getFilterName(userId, suffix) {
+                // scope this on the user ID because people may login on many accounts
+                // and they all need to be stored!
+                return "FILTER_SYNC_" + userId + (suffix ? "_" + suffix : "");
+            }
+            var invalidFilterId = 'invalidF1lt3r';
+            httpLookups = [];
+            httpLookups.push({
+                method: "GET",
+                path: FILTER_PATH + '/' + invalidFilterId,
+                error: {
+                    errcode: "M_UNKNOWN",
+                    name: "M_UNKNOWN",
+                    message: "No row found",
+                    data: { errcode: "M_UNKNOWN", error: "No row found" },
+                    httpStatus: 404
+                }
+            });
+            httpLookups.push(FILTER_RESPONSE);
+            store.getFilterIdByName.andReturn(invalidFilterId);
+
+            var filterName = getFilterName(client.credentials.userId);
+            client.store.setFilterIdByName(filterName, invalidFilterId);
+            var filter = new sdk.Filter(client.credentials.userId);
+
+            client.getOrCreateFilter(filterName, filter).then(function(filterId) {
+                expect(filterId).toEqual(FILTER_RESPONSE.data.filter_id);
+                done();
+            });
+        });
+    });
+
    describe("retryImmediately", function() {
        it("should return false if there is no request waiting", function() {
            client.startClient();
@@ -250,6 +292,8 @@ describe("MatrixClient", function() {
                        true, "retryImmediately returned false"
                    );
                    jasmine.Clock.tick(1);
+                } else if (state === "RECONNECTING" && httpLookups.length > 0) {
+                    jasmine.Clock.tick(10000);
                } else if (state === "SYNCING" && httpLookups.length === 0) {
                    client.removeListener("sync", syncListener);
                    done();
@@ -329,17 +373,25 @@ describe("MatrixClient", function() {
        it("should transition ERROR -> PREPARED after /sync if prev failed",
        function(done) {
            var expectedStates = [];
+            accept_keepalives = false;
            httpLookups = [];
            httpLookups.push(PUSH_RULES_RESPONSE);
            httpLookups.push(FILTER_RESPONSE);
            httpLookups.push({
                method: "GET", path: "/sync", error: { errcode: "NOPE_NOPE_NOPE" }
            });
+            httpLookups.push({
+                method: "GET", path: KEEP_ALIVE_PATH, error: { errcode: "KEEPALIVE_FAIL" }
+            });
+            httpLookups.push({
+                method: "GET", path: KEEP_ALIVE_PATH, data: {}
+            });
            httpLookups.push({
                method: "GET", path: "/sync", data: SYNC_DATA
            });

-            expectedStates.push(["ERROR", null]);
+            expectedStates.push(["RECONNECTING", null]);
+            expectedStates.push(["ERROR", "RECONNECTING"]);
            expectedStates.push(["PREPARED", "ERROR"]);
            client.on("sync", syncChecker(expectedStates, done));
            client.startClient();
@@ -354,14 +406,19 @@ describe("MatrixClient", function() {
        });

        it("should transition SYNCING -> ERROR after a failed /sync", function(done) {
+            accept_keepalives = false;
            var expectedStates = [];
            httpLookups.push({
                method: "GET", path: "/sync", error: { errcode: "NONONONONO" }
            });
+            httpLookups.push({
+                method: "GET", path: KEEP_ALIVE_PATH, error: { errcode: "KEEPALIVE_FAIL" }
+            });

            expectedStates.push(["PREPARED", null]);
            expectedStates.push(["SYNCING", "PREPARED"]);
-            expectedStates.push(["ERROR", "SYNCING"]);
+            expectedStates.push(["RECONNECTING", "SYNCING"]);
+            expectedStates.push(["ERROR", "RECONNECTING"]);
            client.on("sync", syncChecker(expectedStates, done));
            client.startClient();
        });
@@ -394,18 +451,23 @@ describe("MatrixClient", function() {
            client.startClient();
        });

-        it("should transition ERROR -> ERROR if multiple /sync fails", function(done) {
+        it("should transition ERROR -> ERROR if keepalive keeps failing", function(done) {
+            accept_keepalives = false;
            var expectedStates = [];
            httpLookups.push({
                method: "GET", path: "/sync", error: { errcode: "NONONONONO" }
            });
            httpLookups.push({
-                method: "GET", path: "/sync", error: { errcode: "NONONONONO" }
+                method: "GET", path: KEEP_ALIVE_PATH, error: { errcode: "KEEPALIVE_FAIL" }
+            });
+            httpLookups.push({
+                method: "GET", path: KEEP_ALIVE_PATH, error: { errcode: "KEEPALIVE_FAIL" }
            });

            expectedStates.push(["PREPARED", null]);
            expectedStates.push(["SYNCING", "PREPARED"]);
-            expectedStates.push(["ERROR", "SYNCING"]);
+            expectedStates.push(["RECONNECTING", "SYNCING"]);
+            expectedStates.push(["ERROR", "RECONNECTING"]);
            expectedStates.push(["ERROR", "ERROR"]);
            client.on("sync", syncChecker(expectedStates, done));
            client.startClient();
				`@@ -1 +0,0 @@`
				`Release builds and development builds will reside here.`