v5.1.1-rc.1

Prepare changelog for v5.1.1-rc.1
Merge pull request #1252 from matrix-org/uhoreg/megolm_speed
2020-03-11 15:05:49 +00:00 · 2020-03-11 15:05:48 +00:00 · 2020-03-10 20:09:41 -04:00 · 2020-03-10 15:56:33 -04:00 · 2020-03-10 09:30:22 -06:00 · 2020-03-10 12:42:50 +00:00
57 changed files with 4978 additions and 2608 deletions
@@ -1,58 +0,0 @@
-steps:
-  - label: ":eslint: JS Lint"
-    command:
-      - "yarn install"
-      - "yarn lint:js"
-    plugins:
-      - docker#v3.0.1:
-          image: "node:12"
-
-  - label: ":tslint: TS Lint"
-    command:
-      - "yarn install"
-      - "yarn lint:ts"
-    plugins:
-      - docker#v3.0.1:
-          image: "node:12"
-
-  - label: ":typescript: Types Lint"
-    command:
-      - "yarn install"
-      - "yarn lint:types"
-    plugins:
-      - docker#v3.0.1:
-          image: "node:12"
-
-  - label: "🛠 Build"
-    command:
-      - "yarn install"
-      - "yarn build"
-    plugins:
-      - docker#v3.0.1:
-          image: "node:12"
-
-  - label: ":jest: Tests"
-    command:
-      - "yarn install"
-      - "yarn test"
-    plugins:
-      - docker#v3.0.1:
-          image: "node:12"
-
-  - label: "📃 Docs"
-    command:
-      - "yarn install"
-      - "yarn gendoc"
-    plugins:
-      - docker#v3.0.1:
-          image: "node:12"
-
-  - wait
-
-  - label: "🐴 Trigger matrix-react-sdk"
-    trigger: "matrix-react-sdk"
-    branches: "develop"
-    build:
-        branch: "develop"
-        message: "[js-sdk] ${BUILDKITE_MESSAGE}"
-    async: true
@@ -1,3 +1,193 @@
+Changes in [5.1.1-rc.1](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v5.1.1-rc.1) (2020-03-11)
+==========================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v5.1.0...v5.1.1-rc.1)
+
+ * refactor megolm encryption to improve perceived speed
+   [\#1252](https://github.com/matrix-org/matrix-js-sdk/pull/1252)
+ * Remove v1 identity server fallbacks
+   [\#1253](https://github.com/matrix-org/matrix-js-sdk/pull/1253)
+ * Use alt_aliases instead of local ones for room names
+   [\#1251](https://github.com/matrix-org/matrix-js-sdk/pull/1251)
+ * Upload cross-signing key signatures in the background
+   [\#1250](https://github.com/matrix-org/matrix-js-sdk/pull/1250)
+ * Fix secret sharing names to match spec
+   [\#1249](https://github.com/matrix-org/matrix-js-sdk/pull/1249)
+ * Cleanup: remove crypto.verification.start event
+   [\#1248](https://github.com/matrix-org/matrix-js-sdk/pull/1248)
+ * Fix regression in key backup request params
+   [\#1246](https://github.com/matrix-org/matrix-js-sdk/pull/1246)
+ * Use cross-signing trust to mark backups verified
+   [\#1244](https://github.com/matrix-org/matrix-js-sdk/pull/1244)
+ * Check both cross-signing and local trust for key sharing
+   [\#1243](https://github.com/matrix-org/matrix-js-sdk/pull/1243)
+ * Fixed up tests to match new way that crypto stores are created
+   [\#1242](https://github.com/matrix-org/matrix-js-sdk/pull/1242)
+ * Store USK and SSK locally
+   [\#1235](https://github.com/matrix-org/matrix-js-sdk/pull/1235)
+ * Use unpadded base64 for QR code secrets
+   [\#1236](https://github.com/matrix-org/matrix-js-sdk/pull/1236)
+ * Don't require .done event for finishing self-verification
+   [\#1239](https://github.com/matrix-org/matrix-js-sdk/pull/1239)
+ * Don't cancel as 3rd party in verification request
+   [\#1237](https://github.com/matrix-org/matrix-js-sdk/pull/1237)
+ * Verification: log when switching start event
+   [\#1234](https://github.com/matrix-org/matrix-js-sdk/pull/1234)
+ * Perform crypto store operations directly after transaction
+   [\#1233](https://github.com/matrix-org/matrix-js-sdk/pull/1233)
+ * More verification request logging
+   [\#1232](https://github.com/matrix-org/matrix-js-sdk/pull/1232)
+ * Upgrade deps
+   [\#1231](https://github.com/matrix-org/matrix-js-sdk/pull/1231)
+
+Changes in [5.1.0](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v5.1.0) (2020-03-02)
+================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v5.1.0-rc.1...v5.1.0)
+
+ * No changes since rc.1
+
+Changes in [5.1.0-rc.1](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v5.1.0-rc.1) (2020-02-26)
+==========================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v5.0.1...v5.1.0-rc.1)
+
+ * Add latest dist-tag for releases
+   [\#1230](https://github.com/matrix-org/matrix-js-sdk/pull/1230)
+ * Add room method for alt_aliases
+   [\#1225](https://github.com/matrix-org/matrix-js-sdk/pull/1225)
+ * Remove buildkite pipeline
+   [\#1227](https://github.com/matrix-org/matrix-js-sdk/pull/1227)
+ * don't assume verify has been called when receiving a cancellation in
+   verifier
+   [\#1226](https://github.com/matrix-org/matrix-js-sdk/pull/1226)
+ * Reduce secret size for new binary packing
+   [\#1221](https://github.com/matrix-org/matrix-js-sdk/pull/1221)
+ * misc rageshake fixes
+   [\#1223](https://github.com/matrix-org/matrix-js-sdk/pull/1223)
+ * Fix cancelled historical requests not appearing as cancelled
+   [\#1220](https://github.com/matrix-org/matrix-js-sdk/pull/1220)
+ * Fix renaming error that broke QR code verification
+   [\#1217](https://github.com/matrix-org/matrix-js-sdk/pull/1217)
+
+Changes in [5.0.1](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v5.0.1) (2020-02-19)
+================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v5.0.0...v5.0.1)
+
+ * add method for new /aliases endpoint
+   [\#1219](https://github.com/matrix-org/matrix-js-sdk/pull/1219)
+ * method for checking if other party supports verification method
+   [\#1213](https://github.com/matrix-org/matrix-js-sdk/pull/1213)
+ * add local echo state for accepting or declining a verif req
+   [\#1210](https://github.com/matrix-org/matrix-js-sdk/pull/1210)
+ * make logging compatible with rageshakes
+   [\#1214](https://github.com/matrix-org/matrix-js-sdk/pull/1214)
+ * Find existing requests when starting a new verification request
+   [\#1209](https://github.com/matrix-org/matrix-js-sdk/pull/1209)
+ * log MAC calculation during SAS
+   [\#1211](https://github.com/matrix-org/matrix-js-sdk/pull/1211)
+
+Changes in [5.0.0](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v5.0.0) (2020-02-17)
+================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v5.0.0-rc.1...v5.0.0)
+
+ * No changes since rc.1
+
+Changes in [5.0.0-rc.1](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v5.0.0-rc.1) (2020-02-13)
+==========================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v4.0.0...v5.0.0-rc.1)
+
+BREAKING CHANGES
+---
+
+ * The verification methods API has removed an argument ([\#1206](https://github.com/matrix-org/matrix-js-sdk/pull/1206))
+
+All Changes
+---
+
+ * Remove methods argument to verification
+   [\#1206](https://github.com/matrix-org/matrix-js-sdk/pull/1206)
+ * don't do a dynamic import of request
+   [\#1207](https://github.com/matrix-org/matrix-js-sdk/pull/1207)
+ * QR self-verification fixes
+   [\#1201](https://github.com/matrix-org/matrix-js-sdk/pull/1201)
+ * Log every verification event
+   [\#1204](https://github.com/matrix-org/matrix-js-sdk/pull/1204)
+ * dont require .done event from other party
+   [\#1203](https://github.com/matrix-org/matrix-js-sdk/pull/1203)
+ * New option to fully reset Secret Storage keys in boostrapSecretStorage
+   [\#1202](https://github.com/matrix-org/matrix-js-sdk/pull/1202)
+ * Add function to estimate target device for a VerificationRequest
+   [\#1190](https://github.com/matrix-org/matrix-js-sdk/pull/1190)
+ * pass ssss item name to callback so we can differentiate UI on it
+   [\#1200](https://github.com/matrix-org/matrix-js-sdk/pull/1200)
+ * add export/import of Olm devices
+   [\#1167](https://github.com/matrix-org/matrix-js-sdk/pull/1167)
+ * Convert utils.js -> utils.ts
+   [\#1199](https://github.com/matrix-org/matrix-js-sdk/pull/1199)
+ * Don't sign ourselves as a user
+   [\#1197](https://github.com/matrix-org/matrix-js-sdk/pull/1197)
+ * Add a bunch of logging to verification
+   [\#1196](https://github.com/matrix-org/matrix-js-sdk/pull/1196)
+ * Fix: always return a valid string from InRoomChannel.getEventType
+   [\#1198](https://github.com/matrix-org/matrix-js-sdk/pull/1198)
+ * add logging when a request is being cancelled
+   [\#1195](https://github.com/matrix-org/matrix-js-sdk/pull/1195)
+ * Don't explode verification validation if we don't have an event type
+   [\#1194](https://github.com/matrix-org/matrix-js-sdk/pull/1194)
+ * Fix: verification request appearing for users that are not the receiver or
+   sender if they are in room
+   [\#1193](https://github.com/matrix-org/matrix-js-sdk/pull/1193)
+ * Fix getting secrets encoded with passthrough keys
+   [\#1192](https://github.com/matrix-org/matrix-js-sdk/pull/1192)
+ * Update QR code handling for new spec
+   [\#1175](https://github.com/matrix-org/matrix-js-sdk/pull/1175)
+ * Don't add ephemeral events to timeline when peeking
+   [\#1188](https://github.com/matrix-org/matrix-js-sdk/pull/1188)
+ * Fix typo
+   [\#1189](https://github.com/matrix-org/matrix-js-sdk/pull/1189)
+ * Verification: resolve race between .start events from both parties
+   [\#1187](https://github.com/matrix-org/matrix-js-sdk/pull/1187)
+ * Add option to bootstrap to start new key backup
+   [\#1184](https://github.com/matrix-org/matrix-js-sdk/pull/1184)
+ * Add a bunch of null guards to feature checks
+   [\#1182](https://github.com/matrix-org/matrix-js-sdk/pull/1182)
+ * docs: fix MatrixClient reference
+   [\#1183](https://github.com/matrix-org/matrix-js-sdk/pull/1183)
+ * Add helper to obtain the cancellation code for a verification request
+   [\#1180](https://github.com/matrix-org/matrix-js-sdk/pull/1180)
+ * Publish pre-releases as a separate tag on npm
+   [\#1178](https://github.com/matrix-org/matrix-js-sdk/pull/1178)
+ * Fix support for passthrough keys
+   [\#1177](https://github.com/matrix-org/matrix-js-sdk/pull/1177)
+ * Trust our own cross-signing keys if we verify them with another device
+   [\#1174](https://github.com/matrix-org/matrix-js-sdk/pull/1174)
+ * Ensure cross-signing keys are downloaded when checking trust
+   [\#1176](https://github.com/matrix-org/matrix-js-sdk/pull/1176)
+ * Don't log verification validation errors for normal messages
+   [\#1172](https://github.com/matrix-org/matrix-js-sdk/pull/1172)
+ * Fix bootstrap cleanup
+   [\#1173](https://github.com/matrix-org/matrix-js-sdk/pull/1173)
+ * QR code verification
+   [\#1155](https://github.com/matrix-org/matrix-js-sdk/pull/1155)
+ * expose deviceId prop on device channel
+   [\#1171](https://github.com/matrix-org/matrix-js-sdk/pull/1171)
+ * Move & upgrade babel runtime into dependencies (like it wants)
+   [\#1169](https://github.com/matrix-org/matrix-js-sdk/pull/1169)
+ * Add unit tests for verifying your own device, remove .event property on
+   verification request
+   [\#1166](https://github.com/matrix-org/matrix-js-sdk/pull/1166)
+ * For dm-verification, also consider events sent by other devices of same user
+   as "our" events
+   [\#1163](https://github.com/matrix-org/matrix-js-sdk/pull/1163)
+ * Add a prepare script
+   [\#1161](https://github.com/matrix-org/matrix-js-sdk/pull/1161)
+ * Remove :deviceId from /keys/upload/:deviceId as not spec-compliant
+   [\#1162](https://github.com/matrix-org/matrix-js-sdk/pull/1162)
+ * Refactor and expose some logic publicly for the TimelineWindow class.
+   [\#1159](https://github.com/matrix-org/matrix-js-sdk/pull/1159)
+ * Allow a device key upload request without auth
+   [\#1158](https://github.com/matrix-org/matrix-js-sdk/pull/1158)
+ * Support for .ready verification event (MSC2366) & other things
+   [\#1140](https://github.com/matrix-org/matrix-js-sdk/pull/1140)
+
 Changes in [4.0.0](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v4.0.0) (2020-01-27)
 ================================================================================================
 [Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v4.0.0-rc.1...v4.0.0)
@@ -0,0 +1,2 @@
+olm.js
+olm.wasm
@@ -0,0 +1 @@
+../../../dist/browser-matrix.js
@@ -0,0 +1,59 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta http-equiv="X-UA-Compatible" content="ie=edge">
+    <title>Test Crypto in Browser</title>
+    <script src="lib/olm.js"></script>
+    <script src="lib/matrix.js"></script>
+</head>
+<body>
+    <h1>Testing export/import of Olm devices in the browser</h1>
+    <ul>
+        <li>
+            Make sure you built the current version of the Matrix JS SDK
+            (<code>yarn build</code>)
+        </li>
+        <li>
+            copy <code>olm.js</code> and <code>olm.wasm</code>
+            from a recent release of Olm (was tested with version 3.1.4)
+            in directory <code>lib/</code>
+        </li>
+        <li>start a local Matrix homeserver (on port 8008, or change the port in the code)</li>
+        <li>Serve this HTML file (e.g. <code>python3 -m http.server</code>) and go to it through your browser</li>
+        <li>
+            in the JS console, do:
+            <pre>
+aliceMatrixClient = await newMatrixClient("alice-"+randomHex());
+await aliceMatrixClient.exportDevice();
+await aliceMatrixClient.getAccessToken();
+            </pre>
+        </li>
+        <li>
+            copy the result of <code>exportDevice</code> and <code>getAccessToken</code> somewhere
+            (<strong>not</strong> in a JS variable as it will be destroyed when you refresh the page)
+        </li>
+        <li><strong>refresh the page (F5)</strong> to make sure the client is destroyed</li>
+        <li>
+            Do the following, replacing <code>ALICE_ID</code>
+            with the user ID of Alice (you can find it in the exported data)
+            <pre>
+bobMatrixClient = await newMatrixClient("bob-"+randomHex());
+roomId = await bobMatrixClient.createEncryptedRoom([ALICE_ID]);
+await bobMatrixClient.sendTextMessage('Hi Alice!', roomId);
+            </pre>
+        </li>
+        <li>Again, <strong>refresh the page (F5)</strong>. You may want to clear your console as well.</li>
+        <li>
+            Now do the following, using the exported data and the access token you saved previously:
+            <pre>
+aliceMatrixClient = await importMatrixClient(EXPORTED_DATA, ACCESS_TOKEN);
+            </pre>
+        </li>
+        <li>You should see the message sent by Bob printed in the console.</li>
+    </ul>
+
+    <script src="olm-device-export-import.js"></script>
+</body>
+</html>
@@ -0,0 +1,122 @@
+if (!Olm) {
+    console.error(
+        "global.Olm does not seem to be present."
+        + " Did you forget to add olm in the lib/ directory?"
+    );
+}
+
+const BASE_URL = 'http://localhost:8008';
+const ROOM_CRYPTO_CONFIG = { algorithm: 'm.megolm.v1.aes-sha2' };
+const PASSWORD = 'password';
+
+// useful to create new usernames
+window.randomHex = () => Math.floor(Math.random() * (10**6)).toString(16);
+
+window.newMatrixClient = async function (username) {
+    const registrationClient = matrixcs.createClient(BASE_URL);
+
+    const userRegisterResult = await registrationClient.register(
+      username,
+      PASSWORD,
+      null,
+      { type: 'm.login.dummy' }
+    );
+  
+    const matrixClient = matrixcs.createClient({
+      baseUrl: BASE_URL,
+      userId: userRegisterResult.user_id,
+      accessToken: userRegisterResult.access_token,
+      deviceId: userRegisterResult.device_id,
+      sessionStore: new matrixcs.WebStorageSessionStore(window.localStorage),
+      cryptoStore: new matrixcs.MemoryCryptoStore(),
+    });
+
+    extendMatrixClient(matrixClient);
+
+    await matrixClient.initCrypto();
+    await matrixClient.startClient();
+    return matrixClient;
+}
+
+window.importMatrixClient = async function (exportedDevice, accessToken) {
+    const matrixClient = matrixcs.createClient({
+      baseUrl: BASE_URL,
+      deviceToImport: exportedDevice,
+      accessToken,
+      sessionStore: new matrixcs.WebStorageSessionStore(window.localStorage),
+      cryptoStore: new matrixcs.MemoryCryptoStore(),
+    });
+
+    extendMatrixClient(matrixClient);
+
+    await matrixClient.initCrypto();
+    await matrixClient.startClient();
+    return matrixClient;
+}
+
+function extendMatrixClient(matrixClient) {
+    // automatic join
+    matrixClient.on('RoomMember.membership', async (event, member) => {
+        if (member.membership === 'invite' && member.userId === matrixClient.getUserId()) {
+            await matrixClient.joinRoom(member.roomId);
+            // setting up of room encryption seems to be triggered automatically
+            // but if we don't wait for it the first messages we send are unencrypted
+            await matrixClient.setRoomEncryption(member.roomId, { algorithm: 'm.megolm.v1.aes-sha2' })
+        }
+    });
+
+    matrixClient.onDecryptedMessage = message => {
+        console.log('Got encrypted message: ', message);
+    }
+
+    matrixClient.on('Event.decrypted', (event) => {
+        if (event.getType() === 'm.room.message'){
+            matrixClient.onDecryptedMessage(event.getContent().body);
+        } else {
+            console.log('decrypted an event of type', event.getType());
+            console.log(event);
+        }
+    });
+  
+    matrixClient.createEncryptedRoom = async function(usersToInvite) {
+        const {
+          room_id: roomId,
+        } = await this.createRoom({
+          visibility: 'private',
+          invite: usersToInvite,
+        });
+
+        // matrixClient.setRoomEncryption() only updates local state
+        // but does not send anything to the server
+        // (see https://github.com/matrix-org/matrix-js-sdk/issues/905)
+        // so we do it ourselves with 'sendStateEvent'
+        await this.sendStateEvent(
+          roomId, 'm.room.encryption', ROOM_CRYPTO_CONFIG,
+        );
+        await this.setRoomEncryption(
+          roomId, ROOM_CRYPTO_CONFIG,
+        );
+
+        // Marking all devices as verified
+        let room = this.getRoom(roomId);
+        let members = (await room.getEncryptionTargetMembers()).map(x => x["userId"])
+        let memberkeys = await this.downloadKeys(members);
+        for (const userId in memberkeys) {
+          for (const deviceId in memberkeys[userId]) {
+            await this.setDeviceVerified(userId, deviceId);
+          }
+        }
+
+        return roomId;
+    }
+
+    matrixClient.sendTextMessage = async function(message, roomId) {
+        return matrixClient.sendMessage(
+            roomId,
+            {
+                body: message,
+                msgtype: 'm.text',
+            }
+        )
+    }
+}
@@ -1,6 +1,6 @@
 {
  "name": "matrix-js-sdk",
-  "version": "4.0.0",
+  "version": "5.1.1-rc.1",
  "description": "Matrix Client-Server SDK for Javascript",
  "scripts": {
    "prepare": "yarn build",
@@ -78,7 +78,9 @@
    "eslint-plugin-babel": "^5.3.0",
    "eslint-plugin-jest": "^23.0.4",
    "exorcist": "^1.0.1",
+    "fake-indexeddb": "^3.0.0",
    "jest": "^24.9.0",
+    "jest-localstorage-mock": "^2.4.0",
    "jsdoc": "^3.5.5",
    "matrix-mock-request": "^1.2.3",
    "olm": "https://packages.matrix.org/npm/olm/olm-3.1.4.tgz",
@@ -296,7 +296,14 @@ rm "${latest_changes}"

 # Login and publish continues to use `npm`, as it seems to have more clearly
 # defined options and semantics than `yarn` for writing to the registry.
-npm publish
+# Tag both releases and prereleases as `next` so the last stable release remains
+# the default.
+npm publish --tag next
+if [ $prerelease -eq 0 ]; then
+    # For a release, also add the default `latest` tag.
+    package=$(cat package.json | jq -er .name)
+    npm dist-tag add "$package@$release" latest
+fi

 if [ -z "$skip_jsdoc" ]; then
    echo "generating jsdocs"
@@ -0,0 +1,247 @@
+/*
+Copyright 2020 The Matrix.org Foundation C.I.C.
+
+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.
+*/
+
+import '../../olm-loader';
+import {
+    CrossSigningInfo,
+    createCryptoStoreCacheCallbacks,
+} from '../../../src/crypto/CrossSigning';
+import {
+    IndexedDBCryptoStore,
+} from '../../../src/crypto/store/indexeddb-crypto-store';
+import {MemoryCryptoStore} from '../../../src/crypto/store/memory-crypto-store';
+import 'fake-indexeddb/auto';
+import 'jest-localstorage-mock';
+
+const userId = "@alice:example.com";
+
+// Private key for tests only
+const testKey = new Uint8Array([
+    0xda, 0x5a, 0x27, 0x60, 0xe3, 0x3a, 0xc5, 0x82,
+    0x9d, 0x12, 0xc3, 0xbe, 0xe8, 0xaa, 0xc2, 0xef,
+    0xae, 0xb1, 0x05, 0xc1, 0xe7, 0x62, 0x78, 0xa6,
+    0xd7, 0x1f, 0xf8, 0x2c, 0x51, 0x85, 0xf0, 0x1d,
+]);
+
+const types = [
+    { type: "master", shouldCache: false },
+    { type: "self_signing", shouldCache: true },
+    { type: "user_signing", shouldCache: true },
+    { type: "invalid", shouldCache: false },
+];
+
+const badKey = Uint8Array.from(testKey);
+badKey[0] ^= 1;
+
+const masterKeyPub = "nqOvzeuGWT/sRx3h7+MHoInYj3Uk2LD/unI9kDYcHwk";
+
+describe("CrossSigningInfo.getCrossSigningKey", function() {
+    if (!global.Olm) {
+        console.warn('Not running megolm backup unit tests: libolm not present');
+        return;
+    }
+
+    beforeAll(function() {
+        return global.Olm.init();
+    });
+
+    it("should throw if no callback is provided", async () => {
+        const info = new CrossSigningInfo(userId);
+        await expect(info.getCrossSigningKey("master")).rejects.toThrow();
+    });
+
+    it.each(types)("should throw if the callback returns falsey",
+                   async ({type, shouldCache}) => {
+        const info = new CrossSigningInfo(userId, {
+            getCrossSigningKey: () => false,
+        });
+        await expect(info.getCrossSigningKey(type)).rejects.toThrow("falsey");
+    });
+
+    it("should throw if the expected key doesn't come back", async () => {
+        const info = new CrossSigningInfo(userId, {
+            getCrossSigningKey: () => masterKeyPub,
+        });
+        await expect(info.getCrossSigningKey("master", "")).rejects.toThrow();
+    });
+
+    it("should return a key from its callback", async () => {
+        const info = new CrossSigningInfo(userId, {
+            getCrossSigningKey: () => testKey,
+        });
+        const [pubKey, ab] = await info.getCrossSigningKey("master", masterKeyPub);
+        expect(pubKey).toEqual(masterKeyPub);
+        expect(ab).toEqual({a: 106712, b: 106712});
+    });
+
+    it.each(types)("should request a key from the cache callback (if set)" +
+                   " and does not call app if one is found" +
+                   " %o",
+                   async ({ type, shouldCache }) => {
+        const getCrossSigningKey = jest.fn().mockImplementation(() => {
+            if (shouldCache) {
+                return Promise.reject(new Error("Regular callback called"));
+            } else {
+                return Promise.resolve(testKey);
+            }
+        });
+        const getCrossSigningKeyCache = jest.fn().mockResolvedValue(testKey);
+        const info = new CrossSigningInfo(
+            userId,
+            { getCrossSigningKey },
+            { getCrossSigningKeyCache },
+        );
+        const [pubKey] = await info.getCrossSigningKey(type, masterKeyPub);
+        expect(pubKey).toEqual(masterKeyPub);
+        expect(getCrossSigningKeyCache.mock.calls.length).toBe(shouldCache ? 1 : 0);
+        if (shouldCache) {
+            expect(getCrossSigningKeyCache.mock.calls[0][0]).toBe(type);
+        }
+    });
+
+    it.each(types)("should store a key with the cache callback (if set)",
+                   async ({ type, shouldCache }) => {
+        const getCrossSigningKey = jest.fn().mockResolvedValue(testKey);
+        const storeCrossSigningKeyCache = jest.fn().mockResolvedValue(undefined);
+        const info = new CrossSigningInfo(
+            userId,
+            { getCrossSigningKey },
+            { storeCrossSigningKeyCache },
+        );
+        const [pubKey] = await info.getCrossSigningKey(type, masterKeyPub);
+        expect(pubKey).toEqual(masterKeyPub);
+        expect(storeCrossSigningKeyCache.mock.calls.length).toEqual(shouldCache ? 1 : 0);
+        if (shouldCache) {
+            expect(storeCrossSigningKeyCache.mock.calls[0][0]).toBe(type);
+            expect(storeCrossSigningKeyCache.mock.calls[0][1]).toBe(testKey);
+        }
+    });
+
+    it.each(types)("does not store a bad key to the cache",
+                   async ({ type, shouldCache }) => {
+        const getCrossSigningKey = jest.fn().mockResolvedValue(badKey);
+        const storeCrossSigningKeyCache = jest.fn().mockResolvedValue(undefined);
+        const info = new CrossSigningInfo(
+            userId,
+            { getCrossSigningKey },
+            { storeCrossSigningKeyCache },
+        );
+        await expect(info.getCrossSigningKey(type, masterKeyPub)).rejects.toThrow();
+        expect(storeCrossSigningKeyCache.mock.calls.length).toEqual(0);
+    });
+
+    it.each(types)("does not store a value to the cache if it came from the cache",
+        async ({ type, shouldCache }) => {
+        const getCrossSigningKey = jest.fn().mockImplementation(() => {
+            if (shouldCache) {
+                return Promise.reject(new Error("Regular callback called"));
+            } else {
+                return Promise.resolve(testKey);
+            }
+        });
+        const getCrossSigningKeyCache = jest.fn().mockResolvedValue(testKey);
+        const storeCrossSigningKeyCache = jest.fn().mockRejectedValue(
+            new Error("Tried to store a value from cache"),
+        );
+        const info = new CrossSigningInfo(
+            userId,
+            { getCrossSigningKey },
+            { getCrossSigningKeyCache, storeCrossSigningKeyCache },
+        );
+        expect(storeCrossSigningKeyCache.mock.calls.length).toBe(0);
+        const [pubKey] = await info.getCrossSigningKey(type, masterKeyPub);
+        expect(pubKey).toEqual(masterKeyPub);
+    });
+
+    it.each(types)("requests a key from the cache callback (if set) and then calls app" +
+        " if one is not found", async ({ type, shouldCache }) => {
+        const getCrossSigningKey = jest.fn().mockResolvedValue(testKey);
+        const getCrossSigningKeyCache = jest.fn().mockResolvedValue(undefined);
+        const storeCrossSigningKeyCache = jest.fn();
+        const info = new CrossSigningInfo(
+            userId,
+            { getCrossSigningKey },
+            { getCrossSigningKeyCache, storeCrossSigningKeyCache },
+        );
+        const [pubKey] = await info.getCrossSigningKey(type, masterKeyPub);
+        expect(pubKey).toEqual(masterKeyPub);
+        expect(getCrossSigningKey.mock.calls.length).toBe(1);
+        expect(getCrossSigningKeyCache.mock.calls.length).toBe(shouldCache ? 1 : 0);
+
+        /* Also expect that the cache gets updated */
+        expect(storeCrossSigningKeyCache.mock.calls.length).toBe(shouldCache ? 1 : 0);
+    });
+
+    it.each(types)("requests a key from the cache callback (if set) and then" +
+        " calls app if that key doesn't match", async ({ type, shouldCache }) => {
+        const getCrossSigningKey = jest.fn().mockResolvedValue(testKey);
+        const getCrossSigningKeyCache = jest.fn().mockResolvedValue(badKey);
+        const storeCrossSigningKeyCache = jest.fn();
+        const info = new CrossSigningInfo(
+            userId,
+            { getCrossSigningKey },
+            { getCrossSigningKeyCache, storeCrossSigningKeyCache },
+        );
+        const [pubKey] = await info.getCrossSigningKey(type, masterKeyPub);
+        expect(pubKey).toEqual(masterKeyPub);
+        expect(getCrossSigningKey.mock.calls.length).toBe(1);
+        expect(getCrossSigningKeyCache.mock.calls.length).toBe(shouldCache ? 1 : 0);
+
+        /* Also expect that the cache gets updated */
+        expect(storeCrossSigningKeyCache.mock.calls.length).toBe(shouldCache ? 1 : 0);
+    });
+});
+
+/*
+ * Note that MemoryStore is weird.  It's only used for testing - as far as I can tell,
+ * it's not possible to get one in normal execution unless you hack as we do here.
+ */
+describe.each([
+    ["IndexedDBCryptoStore",
+     () => new IndexedDBCryptoStore(global.indexedDB, "tests")],
+    ["LocalStorageCryptoStore",
+     () => new IndexedDBCryptoStore(undefined, "tests")],
+    ["MemoryCryptoStore", () => {
+        const store = new IndexedDBCryptoStore(undefined, "tests");
+        store._backend = new MemoryCryptoStore();
+        return store;
+    }],
+])("CrossSigning > createCryptoStoreCacheCallbacks [%s]", function(name, dbFactory) {
+    let store;
+
+    beforeAll(() => {
+        store = dbFactory();
+    });
+
+    beforeEach(async () => {
+        await store.deleteAllData();
+    });
+
+    it("should cache data to the store and retrieve it", async () => {
+        await store.startup();
+        const { getCrossSigningKeyCache, storeCrossSigningKeyCache } =
+          createCryptoStoreCacheCallbacks(store);
+        await storeCrossSigningKeyCache("self_signing", testKey);
+
+        // If we've not saved anything, don't expect anything
+        // Definitely don't accidentally return the wrong key for the type
+        const nokey = await getCrossSigningKeyCache("self", "");
+        expect(nokey).toBeNull();
+
+        const key = await getCrossSigningKeyCache("self_signing", "");
+        expect(key).toEqual(testKey);
+    });
+});
@@ -320,14 +320,14 @@ describe("MegolmDecryption", function() {

            // this should have claimed a key for alice as it's starting a new session
            expect(mockBaseApis.claimOneTimeKeys).toHaveBeenCalledWith(
-                [['@alice:home.server', 'aliceDevice']], 'signed_curve25519',
+                [['@alice:home.server', 'aliceDevice']], 'signed_curve25519', 2000,
            );
            expect(mockCrypto.downloadKeys).toHaveBeenCalledWith(
                ['@alice:home.server'], false,
            );
            expect(mockBaseApis.sendToDevice).toHaveBeenCalled();
            expect(mockBaseApis.claimOneTimeKeys).toHaveBeenCalledWith(
-                [['@alice:home.server', 'aliceDevice']], 'signed_curve25519',
+                [['@alice:home.server', 'aliceDevice']], 'signed_curve25519', 2000,
            );

            mockBaseApis.claimOneTimeKeys.mockReset();
@@ -516,21 +516,22 @@ describe("MegolmDecryption", function() {
            };
        };

-        let run = false;
-        aliceClient.sendToDevice = async (msgtype, contentMap) => {
-            run = true;
-            expect(msgtype).toBe("org.matrix.room_key.withheld");
-            expect(contentMap).toStrictEqual({
-                '@bob:example.com': {
-                    bobdevice: {
-                        algorithm: "m.megolm.v1.aes-sha2",
-                        code: 'm.no_olm',
-                        reason: 'Unable to establish a secure channel.',
-                        sender_key: aliceDevice.deviceCurve25519Key,
+        const sendPromise = new Promise((resolve, reject) => {
+            aliceClient.sendToDevice = async (msgtype, contentMap) => {
+                expect(msgtype).toBe("org.matrix.room_key.withheld");
+                expect(contentMap).toStrictEqual({
+                    '@bob:example.com': {
+                        bobdevice: {
+                            algorithm: "m.megolm.v1.aes-sha2",
+                            code: 'm.no_olm',
+                            reason: 'Unable to establish a secure channel.',
+                            sender_key: aliceDevice.deviceCurve25519Key,
+                        },
                    },
-                },
-            });
-        };
+                });
+                resolve();
+            };
+        });

        const event = new MatrixEvent({
            type: "m.room.message",
@@ -540,8 +541,7 @@ describe("MegolmDecryption", function() {
            content: {},
        });
        await aliceClient._crypto.encryptEvent(event, aliceRoom);
-
-        expect(run).toBe(true);
+        await sendPromise;
    });

    it("throws an error describing why it doesn't have a key", async function() {
@@ -598,6 +598,7 @@ describe("MegolmDecryption", function() {
            aliceClient.initCrypto(),
            bobClient.initCrypto(),
        ]);
+        aliceClient._crypto.downloadKeys = async () => {};
        const bobDevice = bobClient._crypto._olmDevice;

        const roomId = "!someroom";
@@ -649,6 +650,7 @@ describe("MegolmDecryption", function() {
            bobClient.initCrypto(),
        ]);
        const bobDevice = bobClient._crypto._olmDevice;
+        aliceClient._crypto.downloadKeys = async () => {};

        const roomId = "!someroom";

@@ -41,7 +41,7 @@ async function setupSession(initiator, opponent) {
    return sid;
 }

-describe("OlmDecryption", function() {
+describe("OlmDevice", function() {
    if (!global.Olm) {
        logger.warn('Not running megolm unit tests: libolm not present');
        return;
@@ -81,6 +81,60 @@ describe("OlmDecryption", function() {
            );
        });

+        it('exports picked account and olm sessions', async function() {
+            const sessionId = await setupSession(aliceOlmDevice, bobOlmDevice);
+
+            const exported = await bobOlmDevice.export();
+            // At this moment only Alice (the “initiator” in setupSession) has a session
+            expect(exported.sessions).toEqual([]);
+
+            const MESSAGE = (
+                "The olm or proteus is an aquatic salamander"
+                + " in the family Proteidae"
+            );
+            const ciphertext = await aliceOlmDevice.encryptMessage(
+                bobOlmDevice.deviceCurve25519Key,
+                sessionId,
+                MESSAGE,
+            );
+
+            const bobRecreatedOlmDevice = makeOlmDevice();
+            bobRecreatedOlmDevice.init({ fromExportedDevice: exported });
+
+            const decrypted = await bobRecreatedOlmDevice.createInboundSession(
+                aliceOlmDevice.deviceCurve25519Key,
+                ciphertext.type,
+                ciphertext.body,
+            );
+            expect(decrypted.payload).toEqual(MESSAGE);
+
+            const exportedAgain = await bobRecreatedOlmDevice.export();
+            // this time we expect Bob to have a session to export
+            expect(exportedAgain.sessions).toHaveLength(1);
+
+            const MESSAGE_2 = (
+                "In contrast to most amphibians,"
+                + " the olm is entirely aquatic"
+            );
+            const ciphertext2 = await aliceOlmDevice.encryptMessage(
+                bobOlmDevice.deviceCurve25519Key,
+                sessionId,
+                MESSAGE_2,
+            );
+
+            const bobRecreatedAgainOlmDevice = makeOlmDevice();
+            bobRecreatedAgainOlmDevice.init({ fromExportedDevice: exportedAgain });
+
+            // Note: "decrypted_2" does not have the same structure as "decrypted"
+            const decrypted2 = await bobRecreatedAgainOlmDevice.decryptMessage(
+                aliceOlmDevice.deviceCurve25519Key,
+                decrypted.session_id,
+                ciphertext2.type,
+                ciphertext2.body,
+            );
+            expect(decrypted2).toEqual(MESSAGE_2);
+        });
+
        it("creates only one session at a time", async function() {
            // if we call ensureOlmSessionsForDevices multiple times, it should
            // only try to create one session at a time, even if the server is
@@ -174,7 +174,7 @@ describe("Cross Signing", function() {
            HttpResponse.PUSH_RULES_RESPONSE,
            {
                method: "POST",
-                path: "/keys/upload/Osborne2",
+                path: "/keys/upload",
                data: {
                    one_time_key_counts: {
                        curve25519: 100,
@@ -237,7 +237,7 @@ describe("Cross Signing", function() {
            },
            {
                method: "POST",
-                path: "/keys/upload/Osborne2",
+                path: "/keys/upload",
                data: {
                    one_time_key_counts: {
                        curve25519: 100,
@@ -429,7 +429,7 @@ describe("Cross Signing", function() {
            HttpResponse.PUSH_RULES_RESPONSE,
            {
                method: "POST",
-                path: "/keys/upload/Osborne2",
+                path: "/keys/upload",
                data: {
                    one_time_key_counts: {
                        curve25519: 100,
@@ -487,7 +487,7 @@ describe("Cross Signing", function() {
            },
            {
                method: "POST",
-                path: "/keys/upload/Osborne2",
+                path: "/keys/upload",
                data: {
                    one_time_key_counts: {
                        curve25519: 100,
@@ -34,6 +34,9 @@ async function makeTestClient(userInfo, options) {

    await client.initCrypto();

+    // No need to download keys for these tests
+    client._crypto.downloadKeys = async function() {};
+
    return client;
 }

@@ -0,0 +1,98 @@
+/*
+Copyright 2020 The Matrix.org Foundation C.I.C.
+
+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.
+*/
+import {InRoomChannel} from "../../../../src/crypto/verification/request/InRoomChannel";
+    "../../../../src/crypto/verification/request/ToDeviceChannel";
+import {MatrixEvent} from "../../../../src/models/event";
+
+describe("InRoomChannel tests", function() {
+    const ALICE = "@alice:hs.tld";
+    const BOB = "@bob:hs.tld";
+    const MALORY = "@malory:hs.tld";
+    const client = {
+        getUserId() { return ALICE; },
+    };
+
+    it("getEventType only returns .request for a message with a msgtype", function() {
+        const invalidEvent = new MatrixEvent({
+            type: "m.key.verification.request",
+        });
+        expect(InRoomChannel.getEventType(invalidEvent)).toStrictEqual("");
+        const validEvent = new MatrixEvent({
+            type: "m.room.message",
+            content: { msgtype: "m.key.verification.request" },
+        });
+        expect(InRoomChannel.getEventType(validEvent)).
+            toStrictEqual("m.key.verification.request");
+        const validFooEvent = new MatrixEvent({ type: "m.foo" });
+        expect(InRoomChannel.getEventType(validFooEvent)).
+            toStrictEqual("m.foo");
+    });
+
+    it("getEventType should return m.room.message for messages", function() {
+        const messageEvent = new MatrixEvent({
+            type: "m.room.message",
+            content: { msgtype: "m.text" },
+        });
+        // XXX: The event type doesn't matter too much, just as long as it's not a verification event
+        expect(InRoomChannel.getEventType(messageEvent)).
+            toStrictEqual("m.room.message");
+    });
+
+    it("getEventType should return actual type for non-message events", function() {
+        const event = new MatrixEvent({
+            type: "m.room.member",
+            content: { },
+        });
+        expect(InRoomChannel.getEventType(event)).
+            toStrictEqual("m.room.member");
+    });
+
+    it("getOtherPartyUserId should not return anything for a request not " +
+        "directed at me", function() {
+        const event = new MatrixEvent({
+            sender: BOB,
+            type: "m.room.message",
+            content: { msgtype: "m.key.verification.request", to: MALORY },
+        });
+        expect(InRoomChannel.getOtherPartyUserId(event, client)).toStrictEqual(undefined);
+    });
+
+    it("getOtherPartyUserId should not return anything an event that is not of a valid " +
+        "request type", function() {
+        // invalid because this should be a room message with msgtype
+        const invalidRequest = new MatrixEvent({
+            sender: BOB,
+            type: "m.key.verification.request",
+            content: { to: ALICE },
+        });
+        expect(InRoomChannel.getOtherPartyUserId(invalidRequest, client))
+            .toStrictEqual(undefined);
+        const startEvent = new MatrixEvent({
+            sender: BOB,
+            type: "m.key.verification.start",
+            content: { to: ALICE },
+        });
+        expect(InRoomChannel.getOtherPartyUserId(startEvent, client))
+            .toStrictEqual(undefined);
+        const fooEvent = new MatrixEvent({
+            sender: BOB,
+            type: "m.foo",
+            content: { to: ALICE },
+        });
+        expect(InRoomChannel.getOtherPartyUserId(fooEvent, client))
+            .toStrictEqual(undefined);
+    });
+});
@@ -16,8 +16,6 @@ limitations under the License.
 */
 import "../../../olm-loader";
 import {logger} from "../../../../src/logger";
-import {DeviceInfo} from "../../../../src/crypto/deviceinfo";
-import {ScanQRCode, ShowQRCode} from "../../../../src/crypto/verification/QRCode";

 const Olm = global.Olm;

@@ -31,124 +29,13 @@ describe("QR code verification", function() {
        return Olm.init();
    });

-    describe("showing", function() {
-        it("should emit an event to show a QR code", async function() {
-            const channel = {
-                send: jest.fn(),
-            };
-            const qrCode = new ShowQRCode(channel, {
-                getUserId: () => "@alice:example.com",
-                deviceId: "ABCDEFG",
-                getDeviceEd25519Key: function() {
-                    return "device+ed25519+key";
-                },
-            });
-            const spy = jest.fn((e) => {
-                qrCode.done();
-            });
-            qrCode.on("show_qr_code", spy);
-            await qrCode.verify();
-            expect(spy).toHaveBeenCalledWith({
-                url: "https://matrix.to/#/@alice:example.com?device=ABCDEFG"
-                    + "&action=verify&key_ed25519%3AABCDEFG=device%2Bed25519%2Bkey",
-            });
-        });
-    });
-
-    describe("scanning", function() {
-        const QR_CODE_URL = "https://matrix.to/#/@alice:example.com?device=ABCDEFG"
-              + "&action=verify&key_ed25519%3AABCDEFG=device%2Bed25519%2Bkey";
-        it("should verify when a QR code is sent", async function() {
-            const device = DeviceInfo.fromStorage(
-                {
-                    algorithms: [],
-                    keys: {
-                        "curve25519:ABCDEFG": "device+curve25519+key",
-                        "ed25519:ABCDEFG": "device+ed25519+key",
-                    },
-                    verified: false,
-                    known: false,
-                    unsigned: {},
-                },
-                "ABCDEFG",
-            );
-            const client = {
-                getStoredDevice: jest.fn().mockReturnValue(device),
-                setDeviceVerified: jest.fn(),
-            };
-            const channel = {
-                send: jest.fn(),
-            };
-            const qrCode = new ScanQRCode(channel, client);
-            qrCode.on("confirm_user_id", ({userId, confirm}) => {
-                if (userId === "@alice:example.com") {
-                    confirm();
-                } else {
-                    qrCode.cancel(new Error("Incorrect user"));
-                }
-            });
-            qrCode.on("scan", ({done}) => {
-                done(QR_CODE_URL);
-            });
-            await qrCode.verify();
-            expect(client.getStoredDevice)
-                .toHaveBeenCalledWith("@alice:example.com", "ABCDEFG");
-            expect(client.setDeviceVerified)
-                .toHaveBeenCalledWith("@alice:example.com", "ABCDEFG");
-        });
-
-        it("should error when the user ID doesn't match", async function() {
-            const client = {
-                getStoredDevice: jest.fn(),
-                setDeviceVerified: jest.fn(),
-            };
-            const channel = {
-                send: jest.fn(),
-            };
-            const qrCode = new ScanQRCode(channel, client, "@bob:example.com", "ABCDEFG");
-            qrCode.on("scan", ({done}) => {
-                done(QR_CODE_URL);
-            });
-            const spy = jest.fn();
-            await qrCode.verify().catch(spy);
-            expect(spy).toHaveBeenCalled();
-            expect(channel.send).toHaveBeenCalled();
-            expect(client.getStoredDevice).not.toHaveBeenCalled();
-            expect(client.setDeviceVerified).not.toHaveBeenCalled();
-        });
-
-        it("should error if the key doesn't match", async function() {
-            const device = DeviceInfo.fromStorage(
-                {
-                    algorithms: [],
-                    keys: {
-                        "curve25519:ABCDEFG": "device+curve25519+key",
-                        "ed25519:ABCDEFG": "a+different+device+ed25519+key",
-                    },
-                    verified: false,
-                    known: false,
-                    unsigned: {},
-                },
-                "ABCDEFG",
-            );
-            const client = {
-                getStoredDevice: jest.fn().mockReturnValue(device),
-                setDeviceVerified: jest.fn(),
-            };
-            const channel = {
-                send: jest.fn(),
-            };
-            const qrCode = new ScanQRCode(
-                channel, client, "@alice:example.com", "ABCDEFG");
-            qrCode.on("scan", ({done}) => {
-                done(QR_CODE_URL);
-            });
-            const spy = jest.fn();
-            await qrCode.verify().catch(spy);
-            expect(spy).toHaveBeenCalled();
-            expect(channel.send).toHaveBeenCalled();
-            expect(client.getStoredDevice).toHaveBeenCalled();
-            expect(client.setDeviceVerified).not.toHaveBeenCalled();
+    describe("reciprocate", () => {
+        it("should verify the secret", () => {
+            // TODO: Actually write a test for this.
+            // Tests are hard because we are running before the verification
+            // process actually begins, and are largely UI-driven rather than
+            // logic-driven (compared to something like SAS). In the interest
+            // of time, tests are currently excluded.
        });
    });
 });
@@ -18,20 +18,27 @@ import "../../../olm-loader";
 import {verificationMethods} from "../../../../src/crypto";
 import {logger} from "../../../../src/logger";
 import {SAS} from "../../../../src/crypto/verification/SAS";
-import {makeTestClients} from './util';
+import {makeTestClients, setupWebcrypto, teardownWebcrypto} from './util';

 const Olm = global.Olm;

-describe("verification request", function() {
+jest.useFakeTimers();
+
+describe("verification request integration tests with crypto layer", function() {
    if (!global.Olm) {
        logger.warn('Not running device verification unit tests: libolm not present');
        return;
    }

    beforeAll(function() {
+        setupWebcrypto();
        return Olm.init();
    });

+    afterAll(() => {
+        teardownWebcrypto();
+    });
+
    it("should request and accept a verification", async function() {
        const [alice, bob] = await makeTestClients(
            [
@@ -64,7 +71,9 @@ describe("verification request", function() {
            // XXX: Private function access (but it's a test, so we're okay)
            bobVerifier._endTimer();
        });
-        const aliceVerifier = await alice.client.requestVerification("@bob:example.com");
+        const aliceRequest = await alice.client.requestVerification("@bob:example.com");
+        await aliceRequest.waitFor(r => r.started);
+        const aliceVerifier = aliceRequest.verifier;
        expect(aliceVerifier).toBeInstanceOf(SAS);

        // XXX: Private function access (but it's a test, so we're okay)
@@ -15,7 +15,7 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 import "../../../olm-loader";
-import {makeTestClients} from './util';
+import {makeTestClients, setupWebcrypto, teardownWebcrypto} from './util';
 import {MatrixEvent} from "../../../../src/models/event";
 import {SAS} from "../../../../src/crypto/verification/SAS";
 import {DeviceInfo} from "../../../../src/crypto/deviceinfo";
@@ -35,9 +35,14 @@ describe("SAS verification", function() {
    }

    beforeAll(function() {
+        setupWebcrypto();
        return Olm.init();
    });

+    afterAll(() => {
+        teardownWebcrypto();
+    });
+
    it("should error on an unexpected event", async function() {
        const sas = new SAS({}, "@alice:example.com", "ABCDEFG");
        sas.handleEvent(new MatrixEvent({
@@ -117,8 +122,8 @@ describe("SAS verification", function() {
            bobSasEvent = null;

            bobPromise = new Promise((resolve, reject) => {
-                bob.client.on("crypto.verification.start", (verifier) => {
-                    verifier.on("show_sas", (e) => {
+                bob.client.on("crypto.verification.request", request => {
+                    request.verifier.on("show_sas", (e) => {
                        if (!e.sas.emoji || !e.sas.decimal) {
                            e.cancel();
                        } else if (!aliceSasEvent) {
@@ -134,7 +139,7 @@ describe("SAS verification", function() {
                            }
                        }
                    });
-                    resolve(verifier);
+                    resolve(request.verifier);
                });
            });

@@ -334,11 +339,11 @@ describe("SAS verification", function() {
        };

        const bobPromise = new Promise((resolve, reject) => {
-            bob.client.on("crypto.verification.start", (verifier) => {
-                verifier.on("show_sas", (e) => {
+            bob.client.on("crypto.verification.request", request => {
+                request.verifier.on("show_sas", (e) => {
                    e.mismatch();
                });
-                resolve(verifier);
+                resolve(request.verifier);
            });
        });

@@ -442,9 +447,11 @@ describe("SAS verification", function() {
                });
            });

-            aliceVerifier = await alice.client.requestVerificationDM(
-                bob.client.getUserId(), "!room_id", [verificationMethods.SAS],
+            const aliceRequest = await alice.client.requestVerificationDM(
+                bob.client.getUserId(), "!room_id",
            );
+            await aliceRequest.waitFor(r => r.started);
+            aliceVerifier = aliceRequest.verifier;
            aliceVerifier.on("show_sas", (e) => {
                if (!e.sas.emoji || !e.sas.decimal) {
                    e.cancel();
@@ -0,0 +1,104 @@
+/*
+Copyright 2020 The Matrix.org Foundation C.I.C.
+
+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.
+*/
+
+import {VerificationBase} from '../../../../src/crypto/verification/Base';
+import {CrossSigningInfo} from '../../../../src/crypto/CrossSigning';
+import {encodeBase64} from "../../../../src/crypto/olmlib";
+import {setupWebcrypto, teardownWebcrypto} from './util';
+
+jest.useFakeTimers();
+
+// Private key for tests only
+const testKey = new Uint8Array([
+    0xda, 0x5a, 0x27, 0x60, 0xe3, 0x3a, 0xc5, 0x82,
+    0x9d, 0x12, 0xc3, 0xbe, 0xe8, 0xaa, 0xc2, 0xef,
+    0xae, 0xb1, 0x05, 0xc1, 0xe7, 0x62, 0x78, 0xa6,
+    0xd7, 0x1f, 0xf8, 0x2c, 0x51, 0x85, 0xf0, 0x1d,
+]);
+const testKeyPub = "nqOvzeuGWT/sRx3h7+MHoInYj3Uk2LD/unI9kDYcHwk";
+
+describe("self-verifications", () => {
+    beforeAll(function() {
+        setupWebcrypto();
+        return global.Olm.init();
+    });
+
+    afterAll(() => {
+        teardownWebcrypto();
+    });
+
+    it("triggers a request for key sharing upon completion", async () => {
+        const userId = "@test:localhost";
+
+        const cacheCallbacks = {
+            getCrossSigningKeyCache: jest.fn().mockReturnValue(null),
+            storeCrossSigningKeyCache: jest.fn(),
+        };
+
+        const _crossSigningInfo = new CrossSigningInfo(
+            userId,
+            {},
+            cacheCallbacks,
+        );
+        _crossSigningInfo.keys = {
+            self_signing: { keys: { X: testKeyPub } },
+            user_signing: { keys: { X: testKeyPub } },
+        };
+
+        const _secretStorage = {
+            request: jest.fn().mockReturnValue({
+                promise: Promise.resolve(encodeBase64(testKey)),
+            }),
+        };
+
+        const client = {
+            _crypto: {
+                _crossSigningInfo,
+                _secretStorage,
+            },
+            getUserId: () => userId,
+        };
+
+        const request = {
+            onVerifierFinished: () => undefined,
+        };
+
+        const verification = new VerificationBase(
+            undefined, // channel
+            client, // baseApis
+            userId,
+            "ABC", // deviceId
+            undefined, // startEvent
+            request,
+        );
+        verification._resolve = () => undefined;
+
+        const result = await verification.done();
+
+        /* We should request, and store, two keys */
+        expect(cacheCallbacks.storeCrossSigningKeyCache.mock.calls.length).toBe(2);
+        expect(_secretStorage.request.mock.calls.length).toBe(2);
+
+        expect(cacheCallbacks.storeCrossSigningKeyCache.mock.calls[0][1])
+          .toEqual(testKey);
+        expect(cacheCallbacks.storeCrossSigningKeyCache.mock.calls[1][1])
+          .toEqual(testKey);
+
+        expect(result).toBeInstanceOf(Array);
+        expect(result[0][0]).toBe(testKeyPub);
+        expect(result[1][0]).toBe(testKeyPub);
+    });
+});
@@ -17,6 +17,7 @@ limitations under the License.

 import {TestClient} from '../../../TestClient';
 import {MatrixEvent} from "../../../../src/models/event";
+import nodeCrypto from "crypto";

 export async function makeTestClients(userInfos, options) {
    const clients = [];
@@ -33,15 +34,13 @@ export async function makeTestClients(userInfos, options) {
                            content: msg,
                        });
                        const client = clientMap[userId][deviceId];
-                        if (event.isEncrypted()) {
-                            event.attemptDecryption(client._crypto)
-                                .then(() => client.emit("toDeviceEvent", event));
-                        } else {
-                            setTimeout(
-                                () => client.emit("toDeviceEvent", event),
-                                0,
-                            );
-                        }
+                        const decryptionPromise = event.isEncrypted() ?
+                            event.attemptDecryption(client._crypto) :
+                            Promise.resolve();
+
+                        decryptionPromise.then(
+                            () => client.emit("toDeviceEvent", event),
+                        );
                    }
                }
            }
@@ -50,21 +49,33 @@ export async function makeTestClients(userInfos, options) {
    const sendEvent = function(room, type, content) {
        // make up a unique ID as the event ID
        const eventId = "$" + this.makeTxnId(); // eslint-disable-line babel/no-invalid-this
-        const event = new MatrixEvent({
+        const rawEvent = {
            sender: this.getUserId(), // eslint-disable-line babel/no-invalid-this
            type: type,
            content: content,
            room_id: room,
            event_id: eventId,
-        });
-        for (const tc of clients) {
-            setTimeout(
-                () => tc.client.emit("Room.timeline", event),
-                0,
-            );
-        }
+            origin_server_ts: Date.now(),
+        };
+        const event = new MatrixEvent(rawEvent);
+        const remoteEcho = new MatrixEvent(Object.assign({}, rawEvent, {
+            unsigned: {
+                transaction_id: this.makeTxnId(), // eslint-disable-line babel/no-invalid-this
+            },
+        }));

-        return {event_id: eventId};
+        setImmediate(() => {
+            for (const tc of clients) {
+                if (tc.client === this) { // eslint-disable-line babel/no-invalid-this
+                    console.log("sending remote echo!!");
+                    tc.client.emit("Room.timeline", remoteEcho);
+                } else {
+                    tc.client.emit("Room.timeline", event);
+                }
+            }
+        });
+
+        return Promise.resolve({event_id: eventId});
    };

    for (const userInfo of userInfos) {
@@ -92,3 +103,15 @@ export async function makeTestClients(userInfos, options) {

    return clients;
 }
+
+export function setupWebcrypto() {
+    global.crypto = {
+        getRandomValues: (buf) => {
+            return nodeCrypto.randomFillSync(buf);
+        },
+    };
+}
+
+export function teardownWebcrypto() {
+    global.crypto = undefined;
+}
@@ -0,0 +1,249 @@
+/*
+Copyright 2020 The Matrix.org Foundation C.I.C.
+
+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.
+*/
+import {VerificationRequest, READY_TYPE, START_TYPE, DONE_TYPE} from
+    "../../../../src/crypto/verification/request/VerificationRequest";
+import {InRoomChannel} from "../../../../src/crypto/verification/request/InRoomChannel";
+import {ToDeviceChannel} from
+    "../../../../src/crypto/verification/request/ToDeviceChannel";
+import {MatrixEvent} from "../../../../src/models/event";
+import {setupWebcrypto, teardownWebcrypto} from "./util";
+
+function makeMockClient(userId, deviceId) {
+    let counter = 1;
+    let events = [];
+    const deviceEvents = {};
+    return {
+        getUserId() { return userId; },
+        getDeviceId() { return deviceId; },
+
+        sendEvent(roomId, type, content) {
+            counter = counter + 1;
+            const eventId = `$${userId}-${deviceId}-${counter}`;
+            events.push(new MatrixEvent({
+                sender: userId,
+                event_id: eventId,
+                room_id: roomId,
+                type,
+                content,
+                origin_server_ts: Date.now(),
+            }));
+            return Promise.resolve({event_id: eventId});
+        },
+
+        sendToDevice(type, msgMap) {
+            for (const userId of Object.keys(msgMap)) {
+                const deviceMap = msgMap[userId];
+                for (const deviceId of Object.keys(deviceMap)) {
+                    const content = deviceMap[deviceId];
+                    const event = new MatrixEvent({content, type});
+                    deviceEvents[userId] = deviceEvents[userId] || {};
+                    deviceEvents[userId][deviceId] = deviceEvents[userId][deviceId] || [];
+                    deviceEvents[userId][deviceId].push(event);
+                }
+            }
+            return Promise.resolve();
+        },
+
+        popEvents() {
+            const e = events;
+            events = [];
+            return e;
+        },
+
+        popDeviceEvents(userId, deviceId) {
+            const forDevice = deviceEvents[userId];
+            const events = forDevice && forDevice[deviceId];
+            const result = events || [];
+            if (events) {
+                delete forDevice[deviceId];
+            }
+            return result;
+        },
+    };
+}
+
+const MOCK_METHOD = "mock-verify";
+class MockVerifier {
+    constructor(channel, client, userId, deviceId, startEvent) {
+        this._channel = channel;
+        this._startEvent = startEvent;
+    }
+
+    get events() {
+        return [DONE_TYPE];
+    }
+
+    async start() {
+        if (this._startEvent) {
+            await this._channel.send(DONE_TYPE, {});
+        } else {
+            await this._channel.send(START_TYPE, {method: MOCK_METHOD});
+        }
+    }
+
+    async handleEvent(event) {
+        if (event.getType() === DONE_TYPE && !this._startEvent) {
+            await this._channel.send(DONE_TYPE, {});
+        }
+    }
+
+    canSwitchStartEvent() {
+        return false;
+    }
+}
+
+function makeRemoteEcho(event) {
+    return new MatrixEvent(Object.assign({}, event.event, {
+        unsigned: {
+            transaction_id: "abc",
+        },
+    }));
+}
+
+async function distributeEvent(ownRequest, theirRequest, event) {
+    await ownRequest.channel.handleEvent(
+            makeRemoteEcho(event), ownRequest, true);
+    await theirRequest.channel.handleEvent(event, theirRequest, true);
+}
+
+describe("verification request unit tests", function() {
+    beforeAll(function() {
+        setupWebcrypto();
+    });
+
+    afterAll(() => {
+        teardownWebcrypto();
+    });
+
+    it("transition from UNSENT to DONE through happy path", async function() {
+        const alice = makeMockClient("@alice:matrix.tld", "device1");
+        const bob = makeMockClient("@bob:matrix.tld", "device1");
+        const aliceRequest = new VerificationRequest(
+            new InRoomChannel(alice, "!room", bob.getUserId()),
+            new Map([[MOCK_METHOD, MockVerifier]]), alice);
+        const bobRequest = new VerificationRequest(
+            new InRoomChannel(bob, "!room"),
+            new Map([[MOCK_METHOD, MockVerifier]]), bob);
+        expect(aliceRequest.invalid).toBe(true);
+        expect(bobRequest.invalid).toBe(true);
+
+        await aliceRequest.sendRequest();
+        const [requestEvent] = alice.popEvents();
+        expect(requestEvent.getType()).toBe("m.room.message");
+        await distributeEvent(aliceRequest, bobRequest, requestEvent);
+        expect(aliceRequest.requested).toBe(true);
+        expect(bobRequest.requested).toBe(true);
+
+        await bobRequest.accept();
+        const [readyEvent] = bob.popEvents();
+        expect(readyEvent.getType()).toBe(READY_TYPE);
+        await distributeEvent(bobRequest, aliceRequest, readyEvent);
+        expect(bobRequest.ready).toBe(true);
+        expect(aliceRequest.ready).toBe(true);
+
+        const verifier = aliceRequest.beginKeyVerification(MOCK_METHOD);
+        await verifier.start();
+        const [startEvent] = alice.popEvents();
+        expect(startEvent.getType()).toBe(START_TYPE);
+        await distributeEvent(aliceRequest, bobRequest, startEvent);
+        expect(aliceRequest.started).toBe(true);
+        expect(aliceRequest.verifier).toBeInstanceOf(MockVerifier);
+        expect(bobRequest.started).toBe(true);
+        expect(bobRequest.verifier).toBeInstanceOf(MockVerifier);
+
+        await bobRequest.verifier.start();
+        const [bobDoneEvent] = bob.popEvents();
+        expect(bobDoneEvent.getType()).toBe(DONE_TYPE);
+        await distributeEvent(bobRequest, aliceRequest, bobDoneEvent);
+        const [aliceDoneEvent] = alice.popEvents();
+        expect(aliceDoneEvent.getType()).toBe(DONE_TYPE);
+        await distributeEvent(aliceRequest, bobRequest, aliceDoneEvent);
+        expect(aliceRequest.done).toBe(true);
+        expect(bobRequest.done).toBe(true);
+    });
+
+    it("methods only contains common methods", async function() {
+        const alice = makeMockClient("@alice:matrix.tld", "device1");
+        const bob = makeMockClient("@bob:matrix.tld", "device1");
+        const aliceRequest = new VerificationRequest(
+            new InRoomChannel(alice, "!room", bob.getUserId()),
+            new Map([["c", function() {}], ["a", function() {}]]), alice);
+        const bobRequest = new VerificationRequest(
+            new InRoomChannel(bob, "!room"),
+            new Map([["c", function() {}], ["b", function() {}]]), bob);
+        await aliceRequest.sendRequest();
+        const [requestEvent] = alice.popEvents();
+        await distributeEvent(aliceRequest, bobRequest, requestEvent);
+        await bobRequest.accept();
+        const [readyEvent] = bob.popEvents();
+        await distributeEvent(bobRequest, aliceRequest, readyEvent);
+        expect(aliceRequest.methods).toStrictEqual(["c"]);
+        expect(bobRequest.methods).toStrictEqual(["c"]);
+    });
+
+    it("other client accepting request puts it in observeOnly mode", async function() {
+        const alice = makeMockClient("@alice:matrix.tld", "device1");
+        const bob1 = makeMockClient("@bob:matrix.tld", "device1");
+        const bob2 = makeMockClient("@bob:matrix.tld", "device2");
+        const aliceRequest = new VerificationRequest(
+            new InRoomChannel(alice, "!room", bob1.getUserId()), new Map(), alice);
+        await aliceRequest.sendRequest();
+        const [requestEvent] = alice.popEvents();
+        const bob1Request = new VerificationRequest(
+            new InRoomChannel(bob1, "!room"), new Map(), bob1);
+        const bob2Request = new VerificationRequest(
+            new InRoomChannel(bob2, "!room"), new Map(), bob2);
+
+        await bob1Request.channel.handleEvent(requestEvent, bob1Request, true);
+        await bob2Request.channel.handleEvent(requestEvent, bob2Request, true);
+
+        await bob1Request.accept();
+        const [readyEvent] = bob1.popEvents();
+        expect(bob2Request.observeOnly).toBe(false);
+        await bob2Request.channel.handleEvent(readyEvent, bob2Request, true);
+        expect(bob2Request.observeOnly).toBe(true);
+    });
+
+    it("verify own device with to_device messages", async function() {
+        const bob1 = makeMockClient("@bob:matrix.tld", "device1");
+        const bob2 = makeMockClient("@bob:matrix.tld", "device2");
+        const bob1Request = new VerificationRequest(
+            new ToDeviceChannel(bob1, bob1.getUserId(), ["device1", "device2"],
+                ToDeviceChannel.makeTransactionId(), "device2"),
+            new Map([[MOCK_METHOD, MockVerifier]]), bob1);
+        const to = {userId: "@bob:matrix.tld", deviceId: "device2"};
+        const verifier = bob1Request.beginKeyVerification(MOCK_METHOD, to);
+        expect(verifier).toBeInstanceOf(MockVerifier);
+        await verifier.start();
+        const [startEvent] = bob1.popDeviceEvents(to.userId, to.deviceId);
+        expect(startEvent.getType()).toBe(START_TYPE);
+        const bob2Request = new VerificationRequest(
+            new ToDeviceChannel(bob2, bob2.getUserId(), ["device1"]),
+            new Map([[MOCK_METHOD, MockVerifier]]), bob2);
+
+        await bob2Request.channel.handleEvent(startEvent, bob2Request, true);
+        await bob2Request.verifier.start();
+        const [doneEvent1] = bob2.popDeviceEvents("@bob:matrix.tld", "device1");
+        expect(doneEvent1.getType()).toBe(DONE_TYPE);
+        await bob1Request.channel.handleEvent(doneEvent1, bob1Request, true);
+        const [doneEvent2] = bob1.popDeviceEvents("@bob:matrix.tld", "device2");
+        expect(doneEvent2.getType()).toBe(DONE_TYPE);
+        await bob2Request.channel.handleEvent(doneEvent2, bob2Request, true);
+
+        expect(bob1Request.done).toBe(true);
+        expect(bob2Request.done).toBe(true);
+    });
+});
@@ -617,15 +617,10 @@ describe("Room", function() {
                }, event: true,
            })]);
        };
-        const setAliases = function(aliases, stateKey) {
-            if (!stateKey) {
-                stateKey = aliases.length
-                    ? aliases[0].split(':').splice(1).join(':') // domain+port
-                    : 'fibble';
-            }
+        const setAltAliases = function(aliases) {
            room.addLiveEvents([utils.mkEvent({
-                type: "m.room.aliases", room: roomId, skey: stateKey, content: {
-                    aliases: aliases,
+                type: "m.room.canonical_alias", room: roomId, skey: "", content: {
+                    alt_aliases: aliases,
                }, event: true,
            })]);
        };
@@ -862,7 +857,7 @@ describe("Room", function() {
            "(invite join_rules) rooms if a room name doesn't exist.", function() {
                const alias = "#room_alias:here";
                setJoinRule("invite");
-                setAliases([alias, "#another:here"]);
+                setAltAliases([alias, "#another:here"]);
                room.recalculate();
                const name = room.name;
                expect(name).toEqual(alias);
@@ -872,7 +867,7 @@ describe("Room", function() {
            "(public join_rules) rooms if a room name doesn't exist.", function() {
                const alias = "#room_alias:here";
                setJoinRule("public");
-                setAliases([alias, "#another:here"]);
+                setAltAliases([alias, "#another:here"]);
                room.recalculate();
                const name = room.name;
                expect(name).toEqual(alias);
@@ -98,6 +98,12 @@ function keyFromRecoverySession(session, decryptionKey) {
 *
 * @param {string} opts.userId The user ID for this user.
 *
+ * @param {Object} opts.deviceToImport Device data exported with
+ *     "exportDevice" method that must be imported to recreate this device.
+ *     Should only be useful for devices with end-to-end crypto enabled.
+ *     If provided, opts.deviceId and opts.userId should **NOT** be provided
+ *     (they are present in the exported data).
+ *
 * @param {IdentityServerProvider} [opts.identityServer]
 * Optional. A provider object with one function `getAccessToken`, which is a
 * callback that returns a Promise<String> of an identity access token to supply
@@ -215,6 +221,7 @@ function keyFromRecoverySession(session, decryptionKey) {
 *               pubkey: {UInt8Array}
 *           }
 *       }
+ *   {string} name the name of the value we want to read out of SSSS, for UI purposes.
 *
 * @param {function} [opts.cryptoCallbacks.onSecretRequested]
 * Optional. Function called when a request for a secret is received from another
@@ -248,6 +255,29 @@ export function MatrixClient(opts) {
        userId: userId,
    };

+    if (opts.deviceToImport) {
+        if (this.deviceId) {
+            logger.warn(
+                'not importing device because'
+                + ' device ID is provided to constructor'
+                + ' independently of exported data',
+            );
+        } else if (this.credentials.userId) {
+            logger.warn(
+                'not importing device because'
+                + ' user ID is provided to constructor'
+                + ' independently of exported data',
+            );
+        } else if (!(opts.deviceToImport.deviceId)) {
+            logger.warn('not importing device because no device ID in exported data');
+        } else {
+            this.deviceId = opts.deviceToImport.deviceId;
+            this.credentials.userId = opts.deviceToImport.userId;
+            // will be used during async initialization of the crypto
+            this._exportedOlmDeviceToImport = opts.deviceToImport.olmDevice;
+        }
+    }
+
    this.scheduler = opts.scheduler;
    if (this.scheduler) {
        const self = this;
@@ -391,6 +421,18 @@ export function MatrixClient(opts) {
 utils.inherits(MatrixClient, EventEmitter);
 utils.extend(MatrixClient.prototype, MatrixBaseApis.prototype);

+MatrixClient.prototype.exportDevice = async function() {
+    if (!(this._crypto)) {
+        logger.warn('not exporting device if crypto is not enabled');
+        return;
+    }
+    return {
+        userId: this.credentials.userId,
+        deviceId: this.deviceId,
+        olmDevice: await this._crypto._olmDevice.export(),
+    };
+};
+
 /**
 * Clear any data out of the persistent stores used by the client.
 *
@@ -507,7 +549,7 @@ MatrixClient.prototype.isInitialSyncComplete = function() {
    if (!state) {
        return false;
    }
-    return state === "PREPAED" || state === "SYNCING";
+    return state === "PREPARED" || state === "SYNCING";
 };

 /**
@@ -570,7 +612,7 @@ MatrixClient.prototype.setNotifTimelineSet = function(notifTimelineSet) {
 * Gets the capabilities of the homeserver. Always returns an object of
 * capability keys and their options, which may be empty.
 * @param {boolean} fresh True to ignore any cached values.
- * @return {module:client.Promise} Resolves to the capabilities of the homeserver
+ * @return {Promise} Resolves to the capabilities of the homeserver
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 */
 MatrixClient.prototype.getCapabilities = function(fresh=false) {
@@ -643,6 +685,9 @@ MatrixClient.prototype.initCrypto = async function() {
        throw new Error(`Cannot enable encryption: no cryptoStore provided`);
    }

+    logger.log("Crypto: Starting up crypto store...");
+    await this._cryptoStore.startup();
+
    // initialise the list of encrypted rooms (whether or not crypto is enabled)
    logger.log("Crypto: initialising roomlist...");
    await this._roomList.init();
@@ -684,7 +729,10 @@ MatrixClient.prototype.initCrypto = async function() {
    ]);

    logger.log("Crypto: initialising crypto object...");
-    await crypto.init();
+    await crypto.init({
+        exportedOlmDevice: this._exportedOlmDeviceToImport,
+    });
+    delete this._exportedOlmDeviceToImport;

    this.olmVersion = Crypto.getOlmVersion();

@@ -718,6 +766,19 @@ MatrixClient.prototype.getDeviceEd25519Key = function() {
    return this._crypto.getDeviceEd25519Key();
 };

+/**
+ * Get the Curve25519 key for this device
+ *
+ * @return {?string} base64-encoded curve25519 key. Null if crypto is
+ *    disabled.
+ */
+MatrixClient.prototype.getDeviceCurve25519Key = function() {
+    if (!this._crypto) {
+        return null;
+    }
+    return this._crypto.getDeviceCurve25519Key();
+};
+
 /**
 * Upload the device keys to the homeserver.
 * @return {object} A promise that will resolve when the keys are uploaded.
@@ -751,7 +812,7 @@ MatrixClient.prototype.downloadKeys = function(userIds, forceDownload) {
 *
 * @param {string} userId the user to list keys for.
 *
- * @return {Promise<module:crypto-deviceinfo[]>} list of devices
+ * @return {Promise<module:crypto/deviceinfo[]>} list of devices
 */
 MatrixClient.prototype.getStoredDevicesForUser = async function(userId) {
    if (this._crypto === null) {
@@ -766,7 +827,7 @@ MatrixClient.prototype.getStoredDevicesForUser = async function(userId) {
 * @param {string} userId the user to list keys for.
 * @param {string} deviceId unique identifier for the device
 *
- * @return {Promise<?module:crypto-deviceinfo>} device or null
+ * @return {Promise<?module:crypto/deviceinfo>} device or null
 */
 MatrixClient.prototype.getStoredDevice = async function(userId, deviceId) {
    if (this._crypto === null) {
@@ -862,52 +923,46 @@ async function _setDeviceVerification(
 *
 * @param {string} userId the user to request verification with
 * @param {string} roomId the room to use for verification
- * @param {Array} methods array of verification methods to use.  Defaults to
- *    all known methods
 *
- * @returns {Promise<module:crypto/verification/Base>} resolves to a verifier
- *    when the request is accepted by the other user
+ * @returns {Promise<module:crypto/verification/request/VerificationRequest>} resolves to a VerificationRequest
+ *    when the request has been sent to the other party.
 */
-MatrixClient.prototype.requestVerificationDM = function(userId, roomId, methods) {
+MatrixClient.prototype.requestVerificationDM = function(userId, roomId) {
    if (this._crypto === null) {
        throw new Error("End-to-end encryption disabled");
    }
-    return this._crypto.requestVerificationDM(userId, roomId, methods);
+    return this._crypto.requestVerificationDM(userId, roomId);
 };

 /**
- * Accept a key verification request from a DM.
+ * Finds a DM verification request that is already in progress for the given room id
 *
- * @param {module:models/event~MatrixEvent} event the verification request
- * that is accepted
- * @param {string} method the verification mmethod to use
+ * @param {string} roomId the room to use for verification
 *
- * @returns {module:crypto/verification/Base} a verifier
+ * @returns {module:crypto/verification/request/VerificationRequest?} the VerificationRequest that is in progress, if any
 */
-MatrixClient.prototype.acceptVerificationDM = function(event, method) {
+MatrixClient.prototype.findVerificationRequestDMInProgress = function(roomId) {
    if (this._crypto === null) {
        throw new Error("End-to-end encryption disabled");
    }
-    return this._crypto.acceptVerificationDM(event, method);
+    return this._crypto.findVerificationRequestDMInProgress(roomId);
 };

 /**
 * Request a key verification from another user.
 *
 * @param {string} userId the user to request verification with
- * @param {Array} methods array of verification methods to use.  Defaults to
- *    all known methods
 * @param {Array} devices array of device IDs to send requests to.  Defaults to
 *    all devices owned by the user
 *
- * @returns {Promise<module:crypto/verification/Base>} resolves to a verifier
- *    when the request is accepted by the other user
+ * @returns {Promise<module:crypto/verification/request/VerificationRequest>} resolves to a VerificationRequest
+ *    when the request has been sent to the other party.
 */
-MatrixClient.prototype.requestVerification = function(userId, methods, devices) {
+MatrixClient.prototype.requestVerification = function(userId, devices) {
    if (this._crypto === null) {
        throw new Error("End-to-end encryption disabled");
    }
-    return this._crypto.requestVerification(userId, methods, devices);
+    return this._crypto.requestVerification(userId, devices);
 };

 /**
@@ -1336,7 +1391,7 @@ MatrixClient.prototype.forceDiscardSession = function(roomId) {
 *
 * This should be encrypted before returning it to the user.
 *
- * @return {module:client.Promise} a promise which resolves to a list of
+ * @return {Promise} a promise which resolves to a list of
 *    session export objects
 */
 MatrixClient.prototype.exportRoomKeys = function() {
@@ -1351,7 +1406,7 @@ MatrixClient.prototype.exportRoomKeys = function() {
 *
 * @param {Object[]} keys a list of session export objects
 *
- * @return {module:client.Promise} a promise which resolves when the keys
+ * @return {Promise} a promise which resolves when the keys
 *    have been imported
 */
 MatrixClient.prototype.importRoomKeys = function(keys) {
@@ -1616,7 +1671,7 @@ MatrixClient.prototype._makeKeyBackupPath = function(roomId, sessionId, version)
 * @param {string} sessionId ID of the session that the keys are for Optional.
 * @param {integer} version backup version Optional.
 * @param {object} data Object keys to send
- * @return {module:client.Promise} a promise that will resolve when the keys
+ * @return {Promise} a promise that will resolve when the keys
 * are uploaded
 */
 MatrixClient.prototype.sendKeyBackup = function(roomId, sessionId, version, data) {
@@ -1842,7 +1897,7 @@ MatrixClient.prototype.getGroups = function() {
 /**
 * Get the config for the media repository.
 * @param {module:client.callback} callback Optional.
- * @return {module:client.Promise} Resolves with an object containing the config.
+ * @return {Promise} Resolves with an object containing the config.
 */
 MatrixClient.prototype.getMediaConfig = function(callback) {
    return this._http.authedRequest(
@@ -1932,7 +1987,7 @@ MatrixClient.prototype.getUsers = function() {
 * @param {string} eventType The event type
 * @param {Object} contents the contents object for the event
 * @param {module:client.callback} callback Optional.
- * @return {module:client.Promise} Resolves: TODO
+ * @return {Promise} Resolves: TODO
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 */
 MatrixClient.prototype.setAccountData = function(eventType, contents, callback) {
@@ -1959,7 +2014,7 @@ MatrixClient.prototype.getAccountData = function(eventType) {
 * gets account data directly from the homeserver if the local store is not
 * ready, which can be useful very early in startup before the initial sync.
 * @param {string} eventType The event type
- * @return {module:client.Promise} Resolves: The contents of the given account
+ * @return {Promise} Resolves: The contents of the given account
 * data event.
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 */
@@ -1996,7 +2051,7 @@ MatrixClient.prototype.getIgnoredUsers = function() {
 * Sets the users that the current user should ignore.
 * @param {string[]} userIds the user IDs to ignore
 * @param {module:client.callback} [callback] Optional.
- * @return {module:client.Promise} Resolves: Account data event
+ * @return {Promise} Resolves: Account data event
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 */
 MatrixClient.prototype.setIgnoredUsers = function(userIds, callback) {
@@ -2029,7 +2084,7 @@ MatrixClient.prototype.isUserIgnored = function(userId) {
 * @param {string[]} opts.viaServers The server names to try and join through in
 *                                   addition to those that are automatically chosen.
 * @param {module:client.callback} callback Optional.
- * @return {module:client.Promise} Resolves: Room object.
+ * @return {Promise} Resolves: Room object.
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 */
 MatrixClient.prototype.joinRoom = function(roomIdOrAlias, opts, callback) {
@@ -2097,7 +2152,7 @@ MatrixClient.prototype.joinRoom = function(roomIdOrAlias, opts, callback) {
 * @param {MatrixEvent} event The event to resend.
 * @param {Room} room Optional. The room the event is in. Will update the
 * timeline entry if provided.
- * @return {module:client.Promise} Resolves: TODO
+ * @return {Promise} Resolves: TODO
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 */
 MatrixClient.prototype.resendEvent = function(event, room) {
@@ -2131,7 +2186,7 @@ MatrixClient.prototype.cancelPendingEvent = function(event) {
 * @param {string} roomId
 * @param {string} name
 * @param {module:client.callback} callback Optional.
- * @return {module:client.Promise} Resolves: TODO
+ * @return {Promise} Resolves: TODO
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 */
 MatrixClient.prototype.setRoomName = function(roomId, name, callback) {
@@ -2143,7 +2198,7 @@ MatrixClient.prototype.setRoomName = function(roomId, name, callback) {
 * @param {string} roomId
 * @param {string} topic
 * @param {module:client.callback} callback Optional.
- * @return {module:client.Promise} Resolves: TODO
+ * @return {Promise} Resolves: TODO
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 */
 MatrixClient.prototype.setRoomTopic = function(roomId, topic, callback) {
@@ -2154,7 +2209,7 @@ MatrixClient.prototype.setRoomTopic = function(roomId, topic, callback) {
 /**
 * @param {string} roomId
 * @param {module:client.callback} callback Optional.
- * @return {module:client.Promise} Resolves: TODO
+ * @return {Promise} Resolves: TODO
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 */
 MatrixClient.prototype.getRoomTags = function(roomId, callback) {
@@ -2172,7 +2227,7 @@ MatrixClient.prototype.getRoomTags = function(roomId, callback) {
 * @param {string} tagName name of room tag to be set
 * @param {object} metadata associated with that tag to be stored
 * @param {module:client.callback} callback Optional.
- * @return {module:client.Promise} Resolves: TODO
+ * @return {Promise} Resolves: TODO
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 */
 MatrixClient.prototype.setRoomTag = function(roomId, tagName, metadata, callback) {
@@ -2190,7 +2245,7 @@ MatrixClient.prototype.setRoomTag = function(roomId, tagName, metadata, callback
 * @param {string} roomId
 * @param {string} tagName name of room tag to be removed
 * @param {module:client.callback} callback Optional.
- * @return {module:client.Promise} Resolves: TODO
+ * @return {Promise} Resolves: TODO
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 */
 MatrixClient.prototype.deleteRoomTag = function(roomId, tagName, callback) {
@@ -2209,7 +2264,7 @@ MatrixClient.prototype.deleteRoomTag = function(roomId, tagName, callback) {
 * @param {string} eventType event type to be set
 * @param {object} content event content
 * @param {module:client.callback} callback Optional.
- * @return {module:client.Promise} Resolves: TODO
+ * @return {Promise} Resolves: TODO
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 */
 MatrixClient.prototype.setRoomAccountData = function(roomId, eventType,
@@ -2231,7 +2286,7 @@ MatrixClient.prototype.setRoomAccountData = function(roomId, eventType,
 * @param {Number} powerLevel
 * @param {MatrixEvent} event
 * @param {module:client.callback} callback Optional.
- * @return {module:client.Promise} Resolves: TODO
+ * @return {Promise} Resolves: TODO
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 */
 MatrixClient.prototype.setPowerLevel = function(roomId, userId, powerLevel,
@@ -2259,7 +2314,7 @@ MatrixClient.prototype.setPowerLevel = function(roomId, userId, powerLevel,
 * @param {Object} content
 * @param {string} txnId Optional.
 * @param {module:client.callback} callback Optional.
- * @return {module:client.Promise} Resolves: TODO
+ * @return {Promise} Resolves: TODO
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 */
 MatrixClient.prototype.sendEvent = function(roomId, eventType, content, txnId,
@@ -2274,7 +2329,7 @@ MatrixClient.prototype.sendEvent = function(roomId, eventType, content, txnId,
 * @param {object} eventObject An object with the partial structure of an event, to which event_id, user_id, room_id and origin_server_ts will be added.
 * @param {string} txnId the txnId.
 * @param {module:client.callback} callback Optional.
- * @return {module:client.Promise} Resolves: TODO
+ * @return {Promise} Resolves: TODO
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 */
 MatrixClient.prototype._sendCompleteEvent = function(roomId, eventObject, txnId,
@@ -2356,7 +2411,7 @@ function _sendEvent(client, room, event, callback) {
        let promise;
        // this event may be queued
        if (client.scheduler) {
-            // if this returns a promsie then the scheduler has control now and will
+            // if this returns a promise then the scheduler has control now and will
            // resolve/reject when it is done. Internally, the scheduler will invoke
            // processFn which is set to this._sendEventHttpRequest so the same code
            // path is executed regardless.
@@ -2414,7 +2469,7 @@ function _sendEvent(client, room, event, callback) {
 * @param {module:models/room?} room destination room. Null if the destination
 *     is not a room we have seen over the sync pipe.
 *
- * @return {module:client.Promise?} Promise which resolves when the event has been
+ * @return {Promise?} Promise which resolves when the event has been
 *     encrypted, or null if nothing was needed
 */

@@ -2523,7 +2578,7 @@ function _sendEventHttpRequest(client, event) {
 * @param {string} [txnId]  transaction id. One will be made up if not
 *    supplied.
 * @param {module:client.callback} callback Optional.
- * @return {module:client.Promise} Resolves: TODO
+ * @return {Promise} Resolves: TODO
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 */
 MatrixClient.prototype.redactEvent = function(roomId, eventId, txnId, callback) {
@@ -2539,7 +2594,7 @@ MatrixClient.prototype.redactEvent = function(roomId, eventId, txnId, callback)
 * @param {Object} content
 * @param {string} txnId Optional.
 * @param {module:client.callback} callback Optional.
- * @return {module:client.Promise} Resolves: TODO
+ * @return {Promise} Resolves: TODO
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 */
 MatrixClient.prototype.sendMessage = function(roomId, content, txnId, callback) {
@@ -2556,7 +2611,7 @@ MatrixClient.prototype.sendMessage = function(roomId, content, txnId, callback)
 * @param {string} body
 * @param {string} txnId Optional.
 * @param {module:client.callback} callback Optional.
- * @return {module:client.Promise} Resolves: TODO
+ * @return {Promise} Resolves: TODO
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 */
 MatrixClient.prototype.sendTextMessage = function(roomId, body, txnId, callback) {
@@ -2569,7 +2624,7 @@ MatrixClient.prototype.sendTextMessage = function(roomId, body, txnId, callback)
 * @param {string} body
 * @param {string} txnId Optional.
 * @param {module:client.callback} callback Optional.
- * @return {module:client.Promise} Resolves: TODO
+ * @return {Promise} Resolves: TODO
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 */
 MatrixClient.prototype.sendNotice = function(roomId, body, txnId, callback) {
@@ -2582,7 +2637,7 @@ MatrixClient.prototype.sendNotice = function(roomId, body, txnId, callback) {
 * @param {string} body
 * @param {string} txnId Optional.
 * @param {module:client.callback} callback Optional.
- * @return {module:client.Promise} Resolves: TODO
+ * @return {Promise} Resolves: TODO
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 */
 MatrixClient.prototype.sendEmoteMessage = function(roomId, body, txnId, callback) {
@@ -2596,7 +2651,7 @@ MatrixClient.prototype.sendEmoteMessage = function(roomId, body, txnId, callback
 * @param {Object} info
 * @param {string} text
 * @param {module:client.callback} callback Optional.
- * @return {module:client.Promise} Resolves: TODO
+ * @return {Promise} Resolves: TODO
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 */
 MatrixClient.prototype.sendImageMessage = function(roomId, url, info, text, callback) {
@@ -2621,7 +2676,7 @@ MatrixClient.prototype.sendImageMessage = function(roomId, url, info, text, call
 * @param {Object} info
 * @param {string} text
 * @param {module:client.callback} callback Optional.
- * @return {module:client.Promise} Resolves: TODO
+ * @return {Promise} Resolves: TODO
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 */
 MatrixClient.prototype.sendStickerMessage = function(roomId, url, info, text, callback) {
@@ -2646,7 +2701,7 @@ MatrixClient.prototype.sendStickerMessage = function(roomId, url, info, text, ca
 * @param {string} body
 * @param {string} htmlBody
 * @param {module:client.callback} callback Optional.
- * @return {module:client.Promise} Resolves: TODO
+ * @return {Promise} Resolves: TODO
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 */
 MatrixClient.prototype.sendHtmlMessage = function(roomId, body, htmlBody, callback) {
@@ -2659,7 +2714,7 @@ MatrixClient.prototype.sendHtmlMessage = function(roomId, body, htmlBody, callba
 * @param {string} body
 * @param {string} htmlBody
 * @param {module:client.callback} callback Optional.
- * @return {module:client.Promise} Resolves: TODO
+ * @return {Promise} Resolves: TODO
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 */
 MatrixClient.prototype.sendHtmlNotice = function(roomId, body, htmlBody, callback) {
@@ -2672,7 +2727,7 @@ MatrixClient.prototype.sendHtmlNotice = function(roomId, body, htmlBody, callbac
 * @param {string} body
 * @param {string} htmlBody
 * @param {module:client.callback} callback Optional.
- * @return {module:client.Promise} Resolves: TODO
+ * @return {Promise} Resolves: TODO
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 */
 MatrixClient.prototype.sendHtmlEmote = function(roomId, body, htmlBody, callback) {
@@ -2686,7 +2741,7 @@ MatrixClient.prototype.sendHtmlEmote = function(roomId, body, htmlBody, callback
 * @param {string} receiptType The kind of receipt e.g. "m.read"
 * @param {object} opts Additional content to send alongside the receipt.
 * @param {module:client.callback} callback Optional.
- * @return {module:client.Promise} Resolves: TODO
+ * @return {Promise} Resolves: TODO
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 */
 MatrixClient.prototype.sendReceipt = function(event, receiptType, opts, callback) {
@@ -2723,7 +2778,7 @@ MatrixClient.prototype.sendReceipt = function(event, receiptType, opts, callback
 * other users and homeservers. Default false (send to everyone). <b>This
 * property is unstable and may change in the future.</b>
 * @param {module:client.callback} callback Optional.
- * @return {module:client.Promise} Resolves: TODO
+ * @return {Promise} Resolves: TODO
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 */
 MatrixClient.prototype.sendReadReceipt = async function(event, opts, callback) {
@@ -2759,7 +2814,7 @@ MatrixClient.prototype.sendReadReceipt = async function(event, opts, callback) {
 * @param {object} opts Options for the read markers
 * @param {object} opts.hidden True to hide the receipt from other users and homeservers.
 * <b>This property is unstable and may change in the future.</b>
- * @return {module:client.Promise} Resolves: the empty object, {}.
+ * @return {Promise} Resolves: the empty object, {}.
 */
 MatrixClient.prototype.setRoomReadMarkers = async function(
    roomId, rmEventId, rrEvent, opts,
@@ -2795,7 +2850,7 @@ MatrixClient.prototype.setRoomReadMarkers = async function(
 * recent one preceding this timestamp if available, or failing that the next
 * most recent available preview.
 * @param {module:client.callback} callback Optional.
- * @return {module:client.Promise} Resolves: Object of OG metadata.
+ * @return {Promise} Resolves: Object of OG metadata.
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 * May return synthesized attributes if the URL lacked OG meta.
 */
@@ -2826,7 +2881,7 @@ MatrixClient.prototype.getUrlPreview = function(url, ts, callback) {
 * @param {boolean} isTyping
 * @param {Number} timeoutMs
 * @param {module:client.callback} callback Optional.
- * @return {module:client.Promise} Resolves: TODO
+ * @return {Promise} Resolves: TODO
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 */
 MatrixClient.prototype.sendTyping = function(roomId, isTyping, timeoutMs, callback) {
@@ -2934,7 +2989,7 @@ MatrixClient.prototype.getRoomUpgradeHistory = function(roomId, verifyLinks=fals
 * @param {string} roomId
 * @param {string} userId
 * @param {module:client.callback} callback Optional.
- * @return {module:client.Promise} Resolves: TODO
+ * @return {Promise} Resolves: TODO
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 */
 MatrixClient.prototype.invite = function(roomId, userId, callback) {
@@ -2947,7 +3002,7 @@ MatrixClient.prototype.invite = function(roomId, userId, callback) {
 * @param {string} roomId The room to invite the user to.
 * @param {string} email The email address to invite.
 * @param {module:client.callback} callback Optional.
- * @return {module:client.Promise} Resolves: TODO
+ * @return {Promise} Resolves: TODO
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 */
 MatrixClient.prototype.inviteByEmail = function(roomId, email, callback) {
@@ -2962,7 +3017,7 @@ MatrixClient.prototype.inviteByEmail = function(roomId, email, callback) {
 * @param {string} medium The medium to invite the user e.g. "email".
 * @param {string} address The address for the specified medium.
 * @param {module:client.callback} callback Optional.
- * @return {module:client.Promise} Resolves: TODO
+ * @return {Promise} Resolves: TODO
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 */
 MatrixClient.prototype.inviteByThreePid = async function(
@@ -3006,7 +3061,7 @@ MatrixClient.prototype.inviteByThreePid = async function(
 /**
 * @param {string} roomId
 * @param {module:client.callback} callback Optional.
- * @return {module:client.Promise} Resolves: TODO
+ * @return {Promise} Resolves: TODO
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 */
 MatrixClient.prototype.leave = function(roomId, callback) {
@@ -3022,7 +3077,7 @@ MatrixClient.prototype.leave = function(roomId, callback) {
 * @param {string} roomId The room ID to start leaving at
 * @param {boolean} includeFuture If true, the whole chain (past and future) of
 * upgraded rooms will be left.
- * @return {module:client.Promise} Resolves when completed with an object keyed
+ * @return {Promise} Resolves when completed with an object keyed
 * by room ID and value of the error encountered when leaving or null.
 */
 MatrixClient.prototype.leaveRoomChain = function(roomId, includeFuture=true) {
@@ -3063,7 +3118,7 @@ MatrixClient.prototype.leaveRoomChain = function(roomId, includeFuture=true) {
 * @param {string} userId
 * @param {string} reason Optional.
 * @param {module:client.callback} callback Optional.
- * @return {module:client.Promise} Resolves: TODO
+ * @return {Promise} Resolves: TODO
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 */
 MatrixClient.prototype.ban = function(roomId, userId, reason, callback) {
@@ -3076,7 +3131,7 @@ MatrixClient.prototype.ban = function(roomId, userId, reason, callback) {
 * @param {boolean} deleteRoom True to delete the room from the store on success.
 * Default: true.
 * @param {module:client.callback} callback Optional.
- * @return {module:client.Promise} Resolves: TODO
+ * @return {Promise} Resolves: TODO
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 */
 MatrixClient.prototype.forget = function(roomId, deleteRoom, callback) {
@@ -3100,7 +3155,7 @@ MatrixClient.prototype.forget = function(roomId, deleteRoom, callback) {
 * @param {string} roomId
 * @param {string} userId
 * @param {module:client.callback} callback Optional.
- * @return {module:client.Promise} Resolves: Object (currently empty)
+ * @return {Promise} Resolves: Object (currently empty)
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 */
 MatrixClient.prototype.unban = function(roomId, userId, callback) {
@@ -3125,7 +3180,7 @@ MatrixClient.prototype.unban = function(roomId, userId, callback) {
 * @param {string} userId
 * @param {string} reason Optional.
 * @param {module:client.callback} callback Optional.
- * @return {module:client.Promise} Resolves: TODO
+ * @return {Promise} Resolves: TODO
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 */
 MatrixClient.prototype.kick = function(roomId, userId, reason, callback) {
@@ -3142,7 +3197,7 @@ MatrixClient.prototype.kick = function(roomId, userId, reason, callback) {
 * @param {string} membershipValue
 * @param {string} reason
 * @param {module:client.callback} callback Optional.
- * @return {module:client.Promise} Resolves: TODO
+ * @return {Promise} Resolves: TODO
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 */
 function _setMembershipState(client, roomId, userId, membershipValue, reason,
@@ -3170,7 +3225,7 @@ function _setMembershipState(client, roomId, userId, membershipValue, reason,
 * @param {string} membership
 * @param {string} reason
 * @param {module:client.callback} callback Optional.
- * @return {module:client.Promise} Resolves: TODO
+ * @return {Promise} Resolves: TODO
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 */
 function _membershipChange(client, roomId, userId, membership, reason, callback) {
@@ -3210,7 +3265,7 @@ MatrixClient.prototype.getPushActionsForEvent = function(event) {
 * @param {string} info The kind of info to set (e.g. 'avatar_url')
 * @param {Object} data The JSON object to set.
 * @param {module:client.callback} callback Optional.
- * @return {module:client.Promise} Resolves: TODO
+ * @return {Promise} Resolves: TODO
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 */
 MatrixClient.prototype.setProfileInfo = function(info, data, callback) {
@@ -3226,7 +3281,7 @@ MatrixClient.prototype.setProfileInfo = function(info, data, callback) {
 /**
 * @param {string} name
 * @param {module:client.callback} callback Optional.
- * @return {module:client.Promise} Resolves: TODO
+ * @return {Promise} Resolves: TODO
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 */
 MatrixClient.prototype.setDisplayName = function(name, callback) {
@@ -3238,7 +3293,7 @@ MatrixClient.prototype.setDisplayName = function(name, callback) {
 /**
 * @param {string} url
 * @param {module:client.callback} callback Optional.
- * @return {module:client.Promise} Resolves: TODO
+ * @return {Promise} Resolves: TODO
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 */
 MatrixClient.prototype.setAvatarUrl = function(url, callback) {
@@ -3271,7 +3326,7 @@ MatrixClient.prototype.mxcUrlToHttp =
 * Sets a new status message for the user. The message may be null/falsey
 * to clear the message.
 * @param {string} newMessage The new message to set.
- * @return {module:client.Promise} Resolves: to nothing
+ * @return {Promise} Resolves: to nothing
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 */
 MatrixClient.prototype._unstable_setStatusMessage = function(newMessage) {
@@ -3298,7 +3353,7 @@ MatrixClient.prototype._unstable_setStatusMessage = function(newMessage) {
 * @param {string} opts.presence One of "online", "offline" or "unavailable"
 * @param {string} opts.status_msg The status message to attach.
 * @param {module:client.callback} callback Optional.
- * @return {module:client.Promise} Resolves: TODO
+ * @return {Promise} Resolves: TODO
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 * @throws If 'presence' isn't a valid presence enum value.
 */
@@ -3330,7 +3385,7 @@ function _presenceList(callback, client, opts, method) {
 /**
 * Retrieve current user presence list.
 * @param {module:client.callback} callback Optional.
-* @return {module:client.Promise} Resolves: TODO
+* @return {Promise} Resolves: TODO
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 */
 MatrixClient.prototype.getPresenceList = function(callback) {
@@ -3341,7 +3396,7 @@ MatrixClient.prototype.getPresenceList = function(callback) {
 * Add users to the current user presence list.
 * @param {module:client.callback} callback Optional.
 * @param {string[]} userIds
-* @return {module:client.Promise} Resolves: TODO
+* @return {Promise} Resolves: TODO
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 */
 MatrixClient.prototype.inviteToPresenceList = function(callback, userIds) {
@@ -3353,7 +3408,7 @@ MatrixClient.prototype.inviteToPresenceList = function(callback, userIds) {
 * Drop users from the current user presence list.
 * @param {module:client.callback} callback Optional.
 * @param {string[]} userIds
-* @return {module:client.Promise} Resolves: TODO
+* @return {Promise} Resolves: TODO
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 **/
 MatrixClient.prototype.dropFromPresenceList = function(callback, userIds) {
@@ -3373,7 +3428,7 @@ MatrixClient.prototype.dropFromPresenceList = function(callback, userIds) {
 * @param {Integer} limit Optional. The maximum number of previous events to
 * pull in. Default: 30.
 * @param {module:client.callback} callback Optional.
- * @return {module:client.Promise} Resolves: Room. If you are at the beginning
+ * @return {Promise} Resolves: Room. If you are at the beginning
 * of the timeline, <code>Room.oldState.paginationToken</code> will be
 * <code>null</code>.
 * @return {module:http-api.MatrixError} Rejects: with an error response.
@@ -3456,7 +3511,7 @@ MatrixClient.prototype.scrollback = function(room, limit, callback) {
 * @param {EventTimelineSet} timelineSet  The timelineSet to look for the event in
 * @param {string} eventId  The ID of the event to look for
 *
- * @return {module:client.Promise} Resolves:
+ * @return {Promise} Resolves:
 *    {@link module:models/event-timeline~EventTimeline} including the given
 *    event
 */
@@ -3586,7 +3641,7 @@ function(roomId, fromToken, limit, dir, timelineFilter = undefined) {
 *    false to go forwards
 * @param {number}   [opts.limit = 30]         number of events to request
 *
- * @return {module:client.Promise} Resolves to a boolean: false if there are no
+ * @return {Promise} Resolves to a boolean: false if there are no
 *    events and we reached either end of the timeline; else true.
 */
 MatrixClient.prototype.paginateEventTimeline = function(eventTimeline, opts) {
@@ -3738,7 +3793,7 @@ MatrixClient.prototype.resetNotifTimelineSet = function() {
 * Peek into a room and receive updates about the room. This only works if the
 * history visibility for the room is world_readable.
 * @param {String} roomId The room to attempt to peek into.
- * @return {module:client.Promise} Resolves: Room object
+ * @return {Promise} Resolves: Room object
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 */
 MatrixClient.prototype.peekInRoom = function(roomId) {
@@ -3769,7 +3824,7 @@ MatrixClient.prototype.stopPeeking = function() {
 * @param {boolean} opts.allowRead True to set history visibility to
 * be world_readable. This gives guests read access *from this point forward*.
 * If false or not given, history visibility is not modified.
- * @return {module:client.Promise} Resolves: TODO
+ * @return {Promise} Resolves: TODO
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 */
 MatrixClient.prototype.setGuestAccess = function(roomId, opts) {
@@ -3802,7 +3857,7 @@ MatrixClient.prototype.setGuestAccess = function(roomId, opts) {
 * @param {string} clientSecret As requestEmailToken
 * @param {number} sendAttempt As requestEmailToken
 * @param {string} nextLink As requestEmailToken
- * @return {module:client.Promise} Resolves: As requestEmailToken
+ * @return {Promise} Resolves: As requestEmailToken
 */
 MatrixClient.prototype.requestRegisterEmailToken = function(email, clientSecret,
                                                    sendAttempt, nextLink) {
@@ -3829,7 +3884,7 @@ MatrixClient.prototype.requestRegisterEmailToken = function(email, clientSecret,
 * @param {string} clientSecret As requestEmailToken
 * @param {number} sendAttempt As requestEmailToken
 * @param {string} nextLink As requestEmailToken
- * @return {module:client.Promise} Resolves: As requestEmailToken
+ * @return {Promise} Resolves: As requestEmailToken
 */
 MatrixClient.prototype.requestRegisterMsisdnToken = function(phoneCountry, phoneNumber,
                                                    clientSecret, sendAttempt, nextLink) {
@@ -3860,7 +3915,7 @@ MatrixClient.prototype.requestRegisterMsisdnToken = function(phoneCountry, phone
 * @param {string} clientSecret As requestEmailToken
 * @param {number} sendAttempt As requestEmailToken
 * @param {string} nextLink As requestEmailToken
- * @return {module:client.Promise} Resolves: As requestEmailToken
+ * @return {Promise} Resolves: As requestEmailToken
 */
 MatrixClient.prototype.requestAdd3pidEmailToken = function(email, clientSecret,
                                                    sendAttempt, nextLink) {
@@ -3887,7 +3942,7 @@ MatrixClient.prototype.requestAdd3pidEmailToken = function(email, clientSecret,
 * @param {string} clientSecret As requestEmailToken
 * @param {number} sendAttempt As requestEmailToken
 * @param {string} nextLink As requestEmailToken
- * @return {module:client.Promise} Resolves: As requestEmailToken
+ * @return {Promise} Resolves: As requestEmailToken
 */
 MatrixClient.prototype.requestAdd3pidMsisdnToken = function(phoneCountry, phoneNumber,
                                                    clientSecret, sendAttempt, nextLink) {
@@ -3920,7 +3975,7 @@ MatrixClient.prototype.requestAdd3pidMsisdnToken = function(phoneCountry, phoneN
 * @param {number} sendAttempt As requestEmailToken
 * @param {string} nextLink As requestEmailToken
 * @param {module:client.callback} callback Optional. As requestEmailToken
- * @return {module:client.Promise} Resolves: As requestEmailToken
+ * @return {Promise} Resolves: As requestEmailToken
 */
 MatrixClient.prototype.requestPasswordEmailToken = function(email, clientSecret,
                                                    sendAttempt, nextLink) {
@@ -3946,7 +4001,7 @@ MatrixClient.prototype.requestPasswordEmailToken = function(email, clientSecret,
 * @param {string} clientSecret As requestEmailToken
 * @param {number} sendAttempt As requestEmailToken
 * @param {string} nextLink As requestEmailToken
- * @return {module:client.Promise} Resolves: As requestEmailToken
+ * @return {Promise} Resolves: As requestEmailToken
 */
 MatrixClient.prototype.requestPasswordMsisdnToken = function(phoneCountry, phoneNumber,
                                                    clientSecret, sendAttempt, nextLink) {
@@ -3968,7 +4023,7 @@ MatrixClient.prototype.requestPasswordMsisdnToken = function(phoneCountry, phone
 *
 * @param {string} endpoint The endpoint to send the request to
 * @param {object} params Parameters for the POST request
- * @return {module:client.Promise} Resolves: As requestEmailToken
+ * @return {Promise} Resolves: As requestEmailToken
 */
 MatrixClient.prototype._requestTokenFromEndpoint = async function(endpoint, params) {
    const postParams = Object.assign({}, params);
@@ -4033,7 +4088,7 @@ MatrixClient.prototype.getRoomPushRule = function(scope, roomId) {
 * @param {string} scope "global" or device-specific.
 * @param {string} roomId the id of the room.
 * @param {string} mute the mute state.
- * @return {module:client.Promise} Resolves: result object
+ * @return {Promise} Resolves: result object
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 */
 MatrixClient.prototype.setRoomMutePushRule = function(scope, roomId, mute) {
@@ -4113,7 +4168,7 @@ MatrixClient.prototype.setRoomMutePushRule = function(scope, roomId, mute) {
 * @param {string=} opts.keys The keys to search on. Defaults to all keys. One
 * of "content.body", "content.name", "content.topic".
 * @param {module:client.callback} callback Optional.
- * @return {module:client.Promise} Resolves: TODO
+ * @return {Promise} Resolves: TODO
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 */
 MatrixClient.prototype.searchMessageText = function(opts, callback) {
@@ -4151,7 +4206,7 @@ MatrixClient.prototype.searchMessageText = function(opts, callback) {
 * @param {Object} opts
 * @param {string} opts.term     the term to search for
 * @param {Object} opts.filter   a JSON filter object to pass in the request
- * @return {module:client.Promise} Resolves: result object
+ * @return {Promise} Resolves: result object
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 */
 MatrixClient.prototype.searchRoomEvents = function(opts) {
@@ -4187,7 +4242,7 @@ MatrixClient.prototype.searchRoomEvents = function(opts) {
 * Take a result from an earlier searchRoomEvents call, and backfill results.
 *
 * @param  {object} searchResults  the results object to be updated
- * @return {module:client.Promise} Resolves: updated result object
+ * @return {Promise} Resolves: updated result object
 * @return {Error} Rejects: with an error response.
 */
 MatrixClient.prototype.backPaginateRoomEventsSearch = function(searchResults) {
@@ -4257,7 +4312,7 @@ MatrixClient.prototype._processRoomEventsSearch = function(searchResults, respon

 /**
 * Populate the store with rooms the user has left.
- * @return {module:client.Promise} Resolves: TODO - Resolved when the rooms have
+ * @return {Promise} Resolves: TODO - Resolved when the rooms have
 * been added to the data store.
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 */
@@ -4316,7 +4371,7 @@ MatrixClient.prototype.createFilter = function(content) {
 * @param {string} filterId The filter ID to retrieve
 * @param {boolean} allowCached True to allow cached filters to be returned.
 * Default: True.
- * @return {module:client.Promise} Resolves: TODO
+ * @return {Promise} Resolves: TODO
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 */
 MatrixClient.prototype.getFilter = function(userId, filterId, allowCached) {
@@ -4415,7 +4470,7 @@ MatrixClient.prototype.getOrCreateFilter = function(filterName, filter) {
 * Gets a bearer token from the Home Server that the user can
 * present to a third party in order to prove their ownership
 * of the Matrix account they are logged into.
- * @return {module:client.Promise} Resolves: Token object
+ * @return {Promise} Resolves: Token object
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 */
 MatrixClient.prototype.getOpenIdToken = function() {
@@ -4434,7 +4489,7 @@ MatrixClient.prototype.getOpenIdToken = function() {

 /**
 * @param {module:client.callback} callback Optional.
- * @return {module:client.Promise} Resolves: TODO
+ * @return {Promise} Resolves: TODO
 * @return {module:http-api.MatrixError} Rejects: with an error response.
 */
 MatrixClient.prototype.turnServer = function(callback) {
@@ -4691,6 +4746,7 @@ MatrixClient.prototype.isVersionSupported = async function(version) {
 */
 MatrixClient.prototype.doesServerSupportLazyLoading = async function() {
    const response = await this.getVersions();
+    if (!response) return false;

    const versions = response["versions"];
    const unstableFeatures = response["unstable_features"];
@@ -4706,6 +4762,7 @@ MatrixClient.prototype.doesServerSupportLazyLoading = async function() {
 */
 MatrixClient.prototype.doesServerRequireIdServerParam = async function() {
    const response = await this.getVersions();
+    if (!response) return true;

    const versions = response["versions"];

@@ -4715,6 +4772,7 @@ MatrixClient.prototype.doesServerRequireIdServerParam = async function() {
    }

    const unstableFeatures = response["unstable_features"];
+    if (!unstableFeatures) return true;
    if (unstableFeatures["m.require_identity_server"] === undefined) {
        return true;
    } else {
@@ -4730,10 +4788,10 @@ MatrixClient.prototype.doesServerRequireIdServerParam = async function() {
 */
 MatrixClient.prototype.doesServerAcceptIdentityAccessToken = async function() {
    const response = await this.getVersions();
+    if (!response) return false;

    const versions = response["versions"];
    const unstableFeatures = response["unstable_features"];
-
    return (versions && versions.includes("r0.6.0"))
        || (unstableFeatures && unstableFeatures["m.id_access_token"]);
 };
@@ -4746,6 +4804,7 @@ MatrixClient.prototype.doesServerAcceptIdentityAccessToken = async function() {
 */
 MatrixClient.prototype.doesServerSupportSeparateAddAndBind = async function() {
    const response = await this.getVersions();
+    if (!response) return false;

    const versions = response["versions"];
    const unstableFeatures = response["unstable_features"];
@@ -4754,6 +4813,19 @@ MatrixClient.prototype.doesServerSupportSeparateAddAndBind = async function() {
        || (unstableFeatures && unstableFeatures["m.separate_add_and_bind"]);
 };

+/**
+ * Query the server to see if it lists support for an unstable feature
+ * in the /versions response
+ * @param {string} feature the feature name
+ * @return {Promise<boolean>} true if the feature is supported
+ */
+MatrixClient.prototype.doesServerSupportUnstableFeature = async function(feature) {
+    const response = await this.getVersions();
+    if (!response) return false;
+    const unstableFeatures = response["unstable_features"];
+    return unstableFeatures && !!unstableFeatures[feature];
+};
+
 /**
 * Get if lazy loading members is being used.
 * @return {boolean} Whether or not members are lazy loaded by this client
@@ -5109,6 +5181,15 @@ MatrixClient.prototype.getEventMapper = function() {
    return _PojoToMatrixEventMapper(this);
 };

+/**
+ * The app may wish to see if we have a key cached without
+ * triggering a user interaction.
+ * @return {object}
+ */
+MatrixClient.prototype.getCrossSigningCacheCallbacks = function() {
+    return this._crypto && this._crypto._crossSigningInfo.getCacheCallbacks();
+};
+
 // Identity Server Operations
 // ==========================

@@ -5425,13 +5506,6 @@ MatrixClient.prototype.generateClientSecret = function() {
 *     reject the key verification.
 */

-/**
- * Fires when a key verification started message is received.
- * @event module:client~MatrixClient#"crypto.verification.start"
- * @param {module:crypto/verification/Base} verifier a verifier object to
- *     perform the key verification
- */
-
 /**
 * Fires when a secret request has been cancelled.  If the client is prompting
 * the user to ask whether they want to share a secret, the prompt can be
@@ -5530,14 +5604,3 @@ MatrixClient.prototype.generateClientSecret = function() {
 * @param {Object} err The error value, the "rejected" value or null.
 * @param {Object} data The data returned, the "resolved" value.
 */
-
- /**
-  * {@link https://github.com/kriskowal/q|A promise implementation (Q)}. Functions
-  * which return this will specify 2 return arguments. These arguments map to the
-  * "onFulfilled" and "onRejected" values of the Promise.
-  * @typedef {Object} Promise
-  * @static
-  * @property {Function} then promise.then(onFulfilled, onRejected, onProgress)
-  * @property {Function} catch promise.catch(onRejected)
-  * @property {Function} finally promise.finally(callback)
-  */
@@ -23,6 +23,7 @@ limitations under the License.
 import {decodeBase64, encodeBase64, pkSign, pkVerify} from './olmlib';
 import {EventEmitter} from 'events';
 import {logger} from '../logger';
+import {IndexedDBCryptoStore} from '../crypto/store/indexeddb-crypto-store';

 function publicKeyFromKeyInfo(keyInfo) {
    // `keys` is an object with { [`ed25519:${pubKey}`]: pubKey }
@@ -40,8 +41,9 @@ export class CrossSigningInfo extends EventEmitter {
     * @param {string} userId the user that the information is about
     * @param {object} callbacks Callbacks used to interact with the app
     *     Requires getCrossSigningKey and saveCrossSigningKeys
+     * @param {object} cacheCallbacks Callbacks used to interact with the cache
     */
-    constructor(userId, callbacks) {
+    constructor(userId, callbacks, cacheCallbacks) {
        super();

        // you can't change the userId
@@ -50,6 +52,7 @@ export class CrossSigningInfo extends EventEmitter {
            value: userId,
        });
        this._callbacks = callbacks || {};
+        this._cacheCallbacks = cacheCallbacks || {};
        this.keys = {};
        this.firstUse = true;
    }
@@ -62,6 +65,8 @@ export class CrossSigningInfo extends EventEmitter {
     * @returns {Array} An array with [ public key, Olm.PkSigning ]
     */
    async getCrossSigningKey(type, expectedPubkey) {
+        const shouldCache = ["self_signing", "user_signing"].indexOf(type) >= 0;
+
        if (!this._callbacks.getCrossSigningKey) {
            throw new Error("No getCrossSigningKey callback supplied");
        }
@@ -70,22 +75,47 @@ export class CrossSigningInfo extends EventEmitter {
            expectedPubkey = this.getId(type);
        }

-        const privkey = await this._callbacks.getCrossSigningKey(type, expectedPubkey);
+        function validateKey(key) {
+            if (!key) return;
+            const signing = new global.Olm.PkSigning();
+            const gotPubkey = signing.init_with_seed(key);
+            if (gotPubkey === expectedPubkey) {
+                return [gotPubkey, signing];
+            }
+            signing.free();
+        }
+
+        let privkey;
+        if (this._cacheCallbacks.getCrossSigningKeyCache && shouldCache) {
+            privkey = await this._cacheCallbacks
+              .getCrossSigningKeyCache(type, expectedPubkey);
+        }
+
+        const cacheresult = validateKey(privkey);
+        if (cacheresult) {
+            return cacheresult;
+        }
+
+        privkey = await this._callbacks.getCrossSigningKey(type, expectedPubkey);
+        const result = validateKey(privkey);
+        if (result) {
+            if (this._cacheCallbacks.storeCrossSigningKeyCache && shouldCache) {
+                await this._cacheCallbacks.storeCrossSigningKeyCache(type, privkey);
+            }
+            return result;
+        }
+
+        /* No keysource even returned a key */
        if (!privkey) {
            throw new Error(
                "getCrossSigningKey callback for " + type + " returned falsey",
            );
        }
-        const signing = new global.Olm.PkSigning();
-        const gotPubkey = signing.init_with_seed(privkey);
-        if (gotPubkey !== expectedPubkey) {
-            signing.free();
-            throw new Error(
-                "Key type " + type + " from getCrossSigningKey callback did not match",
-            );
-        } else {
-            return [gotPubkey, signing];
-        }
+
+        /* We got some keys from the keysource, but none of them were valid */
+        throw new Error(
+            "Key type " + type + " from getCrossSigningKey callback did not match",
+        );
    }

    static fromStorage(obj, userId) {
@@ -348,6 +378,7 @@ export class CrossSigningInfo extends EventEmitter {

    async signUser(key) {
        if (!this.keys.user_signing) {
+            logger.info("No user signing key: not signing user");
            return;
        }
        return this.signObject(key.keys.master, "user_signing");
@@ -360,6 +391,7 @@ export class CrossSigningInfo extends EventEmitter {
            );
        }
        if (!this.keys.self_signing) {
+            logger.info("No self signing key: not signing device");
            return;
        }
        return this.signObject(
@@ -441,6 +473,13 @@ export class CrossSigningInfo extends EventEmitter {
            return new DeviceTrustLevel(false, false, localTrust);
        }
    }
+
+    /**
+     * @returns {object} Cache callbacks
+     */
+    getCacheCallbacks() {
+        return this._cacheCallbacks;
+    }
 }

 function deviceToObject(device, userId) {
@@ -537,3 +576,28 @@ export class DeviceTrustLevel {
        return this._tofu;
    }
 }
+
+export function createCryptoStoreCacheCallbacks(store) {
+    return {
+        getCrossSigningKeyCache: function(type, _expectedPublicKey) {
+            return new Promise((resolve) => {
+                return store.doTxn(
+                    'readonly',
+                    [IndexedDBCryptoStore.STORE_ACCOUNT],
+                    (txn) => {
+                        store.getCrossSigningPrivateKey(txn, resolve, type);
+                    },
+                );
+            });
+        },
+        storeCrossSigningKeyCache: function(type, key) {
+            return store.doTxn(
+                'readwrite',
+                [IndexedDBCryptoStore.STORE_ACCOUNT],
+                (txn) => {
+                    store.storeCrossSigningPrivateKey(txn, type, key);
+                },
+            );
+        },
+    };
+}
@@ -197,16 +197,16 @@ export class DeviceList extends EventEmitter {
            const resolveSavePromise = this._resolveSavePromise;
            this._savePromiseTime = targetTime;
            this._saveTimer = setTimeout(() => {
-                logger.log('Saving device tracking data at token ' + this._syncToken);
+                logger.log('Saving device tracking data', this._syncToken);
+
                // null out savePromise now (after the delay but before the write),
                // otherwise we could return the existing promise when the save has
-                // actually already happened. Likewise for the dirty flag.
+                // actually already happened.
                this._savePromiseTime = null;
                this._saveTimer = null;
                this._savePromise = null;
                this._resolveSavePromise = null;

-                this._dirty = false;
                this._cryptoStore.doTxn(
                    'readwrite', [IndexedDBCryptoStore.STORE_DEVICE_DATA], (txn) => {
                        this._cryptoStore.storeEndToEndDeviceData({
@@ -217,7 +217,13 @@ export class DeviceList extends EventEmitter {
                        }, txn);
                    },
                ).then(() => {
+                    // The device list is considered dirty until the write
+                    // completes.
+                    this._dirty = false;
                    resolveSavePromise();
+                }, err => {
+                    logger.error('Failed to save device tracking data', this._syncToken);
+                    logger.error(err);
                });
            }, delay);
        }
@@ -594,7 +600,7 @@ export class DeviceList extends EventEmitter {
     *
     * @param {String[]} users  list of userIds
     *
-     * @return {module:client.Promise} resolves when all the users listed have
+     * @return {Promise} resolves when all the users listed have
     *     been updated. rejects if there was a problem updating any of the
     *     users.
     */
@@ -699,7 +705,7 @@ class DeviceListUpdateSerialiser {
     * @param {String} syncToken sync token to pass in the query request, to
     *     help the HS give the most recent results
     *
-     * @return {module:client.Promise} resolves when all the users listed have
+     * @return {Promise} resolves when all the users listed have
     *     been updated. rejects if there was a problem updating any of the
     *     users.
     */
@@ -111,16 +111,52 @@ export function OlmDevice(cryptoStore) {
 * Initialise the OlmAccount. This must be called before any other operations
 * on the OlmDevice.
 *
+ * Data from an exported Olm device can be provided
+ * in order to re-create this device.
+ *
 * Attempts to load the OlmAccount from the crypto store, or creates one if none is
 * found.
 *
 * Reads the device keys from the OlmAccount object.
+ *
+ * @param {object} opts
+ * @param {object} opts.fromExportedDevice (Optional) data from exported device
+ *     that must be re-created.
+ *     If present, opts.pickleKey is ignored
+ *     (exported data already provides a pickle key)
+ * @param {object} opts.pickleKey (Optional) pickle key to set instead of default one
 */
-OlmDevice.prototype.init = async function() {
+OlmDevice.prototype.init = async function(opts = {}) {
    let e2eKeys;
    const account = new global.Olm.Account();
+
+    const { pickleKey, fromExportedDevice } = opts;
+
    try {
-        await _initialiseAccount(this._cryptoStore, this._pickleKey, account);
+        if (fromExportedDevice) {
+            if (pickleKey) {
+                console.warn(
+                    'ignoring opts.pickleKey'
+                    + ' because opts.fromExportedDevice is present.',
+                );
+            }
+            this._pickleKey = fromExportedDevice.pickleKey;
+            await _initialiseFromExportedDevice(
+                fromExportedDevice,
+                this._cryptoStore,
+                this._pickleKey,
+                account,
+            );
+        } else {
+            if (pickleKey) {
+                this._pickleKey = pickleKey;
+            }
+            await _initialiseAccount(
+                this._cryptoStore,
+                this._pickleKey,
+                account,
+            );
+        }
        e2eKeys = JSON.parse(account.identity_keys());

        this._maxOneTimeKeys = account.max_number_of_one_time_keys();
@@ -132,18 +168,67 @@ OlmDevice.prototype.init = async function() {
    this.deviceEd25519Key = e2eKeys.ed25519;
 };

-async function _initialiseAccount(cryptoStore, pickleKey, account) {
-    await cryptoStore.doTxn('readwrite', [IndexedDBCryptoStore.STORE_ACCOUNT], (txn) => {
-        cryptoStore.getAccount(txn, (pickledAccount) => {
-            if (pickledAccount !== null) {
-                account.unpickle(pickleKey, pickledAccount);
-            } else {
-                account.create();
-                pickledAccount = account.pickle(pickleKey);
-                cryptoStore.storeAccount(txn, pickledAccount);
-            }
-        });
+/**
+ * Populates the crypto store using data that was exported from an existing device.
+ * Note that for now only the “account” and “sessions” stores are populated;
+ * Other stores will be as with a new device.
+ *
+ * @param {Object} exportedData Data exported from another device
+ *     through the “export” method.
+ * @param {module:crypto/store/base~CryptoStore} cryptoStore storage for the crypto layer
+ * @param {string} pickleKey the key that was used to pickle the exported data
+ * @param {Olm.Account} account an olm account to initialize
+ */
+async function _initialiseFromExportedDevice(
+    exportedData,
+    cryptoStore,
+    pickleKey,
+    account,
+) {
+    await cryptoStore.doTxn(
+        'readwrite',
+        [
+            IndexedDBCryptoStore.STORE_ACCOUNT,
+            IndexedDBCryptoStore.STORE_SESSIONS,
+        ],
+        (txn) => {
+            cryptoStore.storeAccount(txn, exportedData.pickledAccount);
+            exportedData.sessions.forEach((session) => {
+                const {
+                    deviceKey,
+                    sessionId,
+                } = session;
+                const sessionInfo = {
+                    session: session.session,
+                    lastReceivedMessageTs: session.lastReceivedMessageTs,
+                };
+                cryptoStore.storeEndToEndSession(
+                    deviceKey,
+                    sessionId,
+                    sessionInfo,
+                    txn,
+                );
+            });
    });
+    account.unpickle(pickleKey, exportedData.pickledAccount);
+}
+
+async function _initialiseAccount(cryptoStore, pickleKey, account) {
+    await cryptoStore.doTxn(
+        'readwrite',
+        [IndexedDBCryptoStore.STORE_ACCOUNT],
+        (txn) => {
+            cryptoStore.getAccount(txn, (pickledAccount) => {
+                if (pickledAccount !== null) {
+                    account.unpickle(pickleKey, pickledAccount);
+                } else {
+                    account.create();
+                    pickledAccount = account.pickle(pickleKey);
+                    cryptoStore.storeAccount(txn, pickledAccount);
+                }
+            });
+        },
+    );
 }

 /**
@@ -191,6 +276,38 @@ OlmDevice.prototype._storeAccount = function(txn, account) {
    this._cryptoStore.storeAccount(txn, account.pickle(this._pickleKey));
 };

+/**
+ * Export data for re-creating the Olm device later.
+ * TODO export data other than just account and (P2P) sessions.
+ *
+ * @return {Promise<object>} The exported data
+*/
+OlmDevice.prototype.export = async function() {
+    const result = {
+        pickleKey: this._pickleKey,
+    };
+    await this._cryptoStore.doTxn(
+        'readonly',
+        [
+            IndexedDBCryptoStore.STORE_ACCOUNT,
+            IndexedDBCryptoStore.STORE_SESSIONS,
+        ],
+        (txn) => {
+            this._cryptoStore.getAccount(txn, (pickledAccount) => {
+                result.pickledAccount = pickledAccount;
+            });
+            result.sessions = [];
+            // Note that the pickledSession object we get in the callback
+            // is not exactly the same thing you get in method _getSession
+            // see documentation of IndexedDBCryptoStore.getAllEndToEndSessions
+            this._cryptoStore.getAllEndToEndSessions(txn, (pickledSession) => {
+                result.sessions.push(pickledSession);
+            });
+        },
+    );
+    return result;
+};
+
 /**
 * extract an OlmSession from the session store and call the given function
 * The session is useable only within the callback passed to this
@@ -1110,7 +1227,7 @@ OlmDevice.prototype.decryptGroupMessage = async function(
 *
 * @param {string} roomId    room in which the message was received
 * @param {string} senderKey base64-encoded curve25519 key of the sender
- * @param {sring} sessionId session identifier
+ * @param {string} sessionId session identifier
 *
 * @returns {Promise<boolean>} true if we have the keys to this session
 */
@@ -253,12 +253,41 @@ export class SecretStorage extends EventEmitter {
     */
    storePassthrough(name, keyId) {
        return this._baseApis.setAccountData(name, {
-            [keyId]: {
-                passthrough: true,
+            encrypted: {
+                [keyId]: {
+                    passthrough: true,
+                },
            },
        });
    }

+    /**
+     * Temporary method to fix up existing accounts where secrets
+     * are incorrectly stored without the 'encrypted' level
+     *
+     * @param {string} name The name of the secret
+     * @param {object} secretInfo The account data object
+     * @returns {object} The fixed object or null if no fix was performed
+     */
+    async _fixupStoredSecret(name, secretInfo) {
+        // We assume the secret was only stored passthrough for 1
+        // key - this was all the broken code supported.
+        const keys = Object.keys(secretInfo);
+        if (
+            keys.length === 1 && keys[0] !== 'encrypted' &&
+            secretInfo[keys[0]].passthrough
+        ) {
+            const hasKey = await this.hasKey(keys[0]);
+            if (hasKey) {
+                console.log("Fixing up passthrough secret: " + name);
+                await this.storePassthrough(name, keys[0]);
+                const newData = await this._baseApis.getAccountDataFromServer(name);
+                return newData;
+            }
+        }
+        return null;
+    }
+
    /**
     * Get a secret from storage.
     *
@@ -267,12 +296,16 @@ export class SecretStorage extends EventEmitter {
     * @return {string} the contents of the secret
     */
    async get(name) {
-        const secretInfo = await this._baseApis.getAccountDataFromServer(name);
+        let secretInfo = await this._baseApis.getAccountDataFromServer(name);
        if (!secretInfo) {
            return;
        }
        if (!secretInfo.encrypted) {
-            throw new Error("Content is not encrypted!");
+            // try to fix it up
+            secretInfo = await this._fixupStoredSecret(name, secretInfo);
+            if (!secretInfo || !secretInfo.encrypted) {
+                throw new Error("Content is not encrypted!");
+            }
        }

        // get possible keys to decrypt
@@ -285,8 +318,12 @@ export class SecretStorage extends EventEmitter {
            const encInfo = secretInfo.encrypted[keyId];
            switch (keyInfo.algorithm) {
            case SECRET_STORAGE_ALGORITHM_V1:
-                if (keyInfo.pubkey && encInfo.ciphertext && encInfo.mac
-                    && encInfo.ephemeral) {
+                if (
+                    keyInfo.pubkey && (
+                        (encInfo.ciphertext && encInfo.mac && encInfo.ephemeral) ||
+                        encInfo.passthrough
+                    )
+                ) {
                    keys[keyId] = keyInfo;
                }
                break;
@@ -299,7 +336,7 @@ export class SecretStorage extends EventEmitter {
        let decryption;
        try {
            // fetch private key from app
-            [keyId, decryption] = await this._getSecretStorageKey(keys);
+            [keyId, decryption] = await this._getSecretStorageKey(keys, name);

            const encInfo = secretInfo.encrypted[keyId];

@@ -329,9 +366,14 @@ export class SecretStorage extends EventEmitter {
     */
    async isStored(name, checkKey) {
        // check if secret exists
-        const secretInfo = await this._baseApis.getAccountDataFromServer(name);
-        if (!secretInfo || !secretInfo.encrypted) {
-            return false;
+        let secretInfo = await this._baseApis.getAccountDataFromServer(name);
+        if (!secretInfo) return false;
+        if (!secretInfo.encrypted) {
+            // try to fix it up
+            secretInfo = await this._fixupStoredSecret(name, secretInfo);
+            if (!secretInfo || !secretInfo.encrypted) {
+                return false;
+            }
        }

        if (checkKey === undefined) checkKey = true;
@@ -352,6 +394,11 @@ export class SecretStorage extends EventEmitter {
                    this._crossSigningInfo.userId,
                );
            }
+
+            // We don't actually need the decryption object if it's a passthrough
+            // since we just want to return the key itself.
+            if (encInfo.passthrough) return true;
+
            switch (keyInfo.algorithm) {
            case SECRET_STORAGE_ALGORITHM_V1:
                if (keyInfo.pubkey && encInfo.ciphertext && encInfo.mac
@@ -540,12 +587,12 @@ export class SecretStorage extends EventEmitter {
        }
    }

-    async _getSecretStorageKey(keys) {
+    async _getSecretStorageKey(keys, name) {
        if (!this._cryptoCallbacks.getSecretStorageKey) {
            throw new Error("No getSecretStorageKey callback supplied");
        }

-        const returned = await this._cryptoCallbacks.getSecretStorageKey({ keys });
+        const returned = await this._cryptoCallbacks.getSecretStorageKey({ keys }, name);

        if (!returned) {
            throw new Error("getSecretStorageKey callback returned falsey");
@@ -60,6 +60,15 @@ export class EncryptionAlgorithm {
        this._roomId = params.roomId;
    }

+    /**
+     * Perform any background tasks that can be done before a message is ready to
+     * send, in order to speed up sending of the message.
+     *
+     * @param {module:models/room} room the room the event is in
+     */
+    prepareToEncrypt(room) {
+    }
+
    /**
     * Encrypt a message event
     *
@@ -70,7 +79,7 @@ export class EncryptionAlgorithm {
     * @param {string} eventType
     * @param {object} plaintext event content
     *
-     * @return {module:client.Promise} Promise which resolves to the new event body
+     * @return {Promise} Promise which resolves to the new event body
     */

    /**
@@ -186,14 +186,12 @@ utils.inherits(MegolmEncryption, EncryptionAlgorithm);
 * @param {Object} devicesInRoom The devices in this room, indexed by user ID
 * @param {Object} blocked The devices that are blocked, indexed by user ID
 *
- * @return {module:client.Promise} Promise which resolves to the
+ * @return {Promise} Promise which resolves to the
 *    OutboundSessionInfo when setup is complete.
 */
 MegolmEncryption.prototype._ensureOutboundSession = async function(
    devicesInRoom, blocked,
 ) {
-    const self = this;
-
    let session;

    // takes the previous OutboundSessionInfo, and considers whether to create
@@ -201,12 +199,12 @@ MegolmEncryption.prototype._ensureOutboundSession = async function(
    // Updates `session` to hold the final OutboundSessionInfo.
    //
    // returns a promise which resolves once the keyshare is successful.
-    async function prepareSession(oldSession) {
+    const prepareSession = async (oldSession) => {
        session = oldSession;

        // need to make a brand new session?
-        if (session && session.needsRotation(self._sessionRotationPeriodMsgs,
-                                             self._sessionRotationPeriodMs)
+        if (session && session.needsRotation(this._sessionRotationPeriodMsgs,
+                                             this._sessionRotationPeriodMs)
           ) {
            logger.log("Starting new megolm session because we need to rotate.");
            session = null;
@@ -218,32 +216,20 @@ MegolmEncryption.prototype._ensureOutboundSession = async function(
        }

        if (!session) {
-            logger.log(`Starting new megolm session for room ${self._roomId}`);
-            session = await self._prepareNewSession();
+            logger.log(`Starting new megolm session for room ${this._roomId}`);
+            session = await this._prepareNewSession();
            logger.log(`Started new megolm session ${session.sessionId} ` +
-                       `for room ${self._roomId}`);
-            self._outboundSessions[session.sessionId] = session;
+                       `for room ${this._roomId}`);
+            this._outboundSessions[session.sessionId] = session;
        }

        // now check if we need to share with any devices
        const shareMap = {};

-        for (const userId in devicesInRoom) {
-            if (!devicesInRoom.hasOwnProperty(userId)) {
-                continue;
-            }
-
-            const userDevices = devicesInRoom[userId];
-
-            for (const deviceId in userDevices) {
-                if (!userDevices.hasOwnProperty(deviceId)) {
-                    continue;
-                }
-
-                const deviceInfo = userDevices[deviceId];
-
+        for (const [userId, userDevices] of Object.entries(devicesInRoom)) {
+            for (const [deviceId, deviceInfo] of Object.entries(userDevices)) {
                const key = deviceInfo.getIdentityKey();
-                if (key == self._olmDevice.deviceCurve25519Key) {
+                if (key == this._olmDevice.deviceCurve25519Key) {
                    // don't bother sending to ourself
                    continue;
                }
@@ -258,51 +244,102 @@ MegolmEncryption.prototype._ensureOutboundSession = async function(
            }
        }

-        const errorDevices = [];
-
-        await self._shareKeyWithDevices(
-            session, shareMap, errorDevices,
+        const key = this._olmDevice.getOutboundGroupSessionKey(session.sessionId);
+        const payload = {
+            type: "m.room_key",
+            content: {
+                algorithm: olmlib.MEGOLM_ALGORITHM,
+                room_id: this._roomId,
+                session_id: session.sessionId,
+                session_key: key.key,
+                chain_index: key.chain_index,
+            },
+        };
+        const [devicesWithoutSession, olmSessions] = await olmlib.getExistingOlmSessions(
+            this._olmDevice, this._baseApis, shareMap,
        );

-        // are there any new blocked devices that we need to notify?
-        const blockedMap = {};
-        for (const userId in blocked) {
-            if (!blocked.hasOwnProperty(userId)) {
-                continue;
-            }
+        await Promise.all([
+            (async () => {
+                // share keys with devices that we already have a session for
+                await this._shareKeyWithOlmSessions(
+                    session, key, payload, olmSessions,
+                );
+            })(),
+            (async () => {
+                const errorDevices = [];

-            const userBlockedDevices = blocked[userId];
+                // meanwhile, establish olm sessions for devices that we don't
+                // already have a session for, and share keys with them.  Use a
+                // shorter timeout when fetching one-time keys.
+                await this._shareKeyWithDevices(
+                    session, key, payload, devicesWithoutSession, errorDevices, 2000,
+                );

-            for (const deviceId in userBlockedDevices) {
-                if (!userBlockedDevices.hasOwnProperty(deviceId)) {
-                    continue;
+                (async () => {
+                    // Retry sending keys to devices that we were unable to establish
+                    // an olm session for.  This time, we use a longer timeout, but we
+                    // do this in the background and don't block anything else while we
+                    // do this.
+                    const retryDevices = {};
+                    for (const {userId, deviceInfo} of errorDevices) {
+                        retryDevices[userId] = retryDevices[userId] || [];
+                        retryDevices[userId].push(deviceInfo);
+                    }
+
+                    const failedDevices = [];
+                    await this._shareKeyWithDevices(
+                        session, key, payload, retryDevices, failedDevices,
+                    );
+
+                    const blockedMap = {};
+                    const filteredFailedDevices =
+                        await this._olmDevice.filterOutNotifiedErrorDevices(
+                            failedDevices,
+                        );
+                    for (const {userId, deviceInfo} of filteredFailedDevices) {
+                        blockedMap[userId] = blockedMap[userId] || {};
+                        // we use a similar format to what
+                        // olmlib.ensureOlmSessionsForDevices returns, so that
+                        // we can use the same function to split
+                        blockedMap[userId][deviceInfo.deviceId] = {
+                            device: {
+                                code: "m.no_olm",
+                                reason: WITHHELD_MESSAGES["m.no_olm"],
+                                deviceInfo,
+                            },
+                        };
+
+                        const deviceId = deviceInfo.deviceId;
+
+                        // mark this device as "handled" because we don't want to try
+                        // to claim a one-time-key for dead devices on every message.
+                        session.markSharedWithDevice(userId, deviceId, key.chain_index);
+                    }
+
+                    // notify devices that we couldn't get an olm session
+                    await this._notifyBlockedDevices(session, blockedMap);
+                })();
+            })(),
+            (async () => {
+                // also, notify blocked devices that they're blocked
+                const blockedMap = {};
+                for (const [userId, userBlockedDevices] of Object.entries(blocked)) {
+                    for (const [deviceId, device] of Object.entries(userBlockedDevices)) {
+                        if (
+                            !session.blockedDevicesNotified[userId] ||
+                            session.blockedDevicesNotified[userId][deviceId] === undefined
+                        ) {
+                            blockedMap[userId] = blockedMap[userId] || {};
+                            blockedMap[userId][deviceId] = {device};
+                        }
+                    }
                }

-                if (
-                    !session.blockedDevicesNotified[userId] ||
-                        session.blockedDevicesNotified[userId][deviceId] === undefined
-                ) {
-                    blockedMap[userId] = blockedMap[userId] || [];
-                    blockedMap[userId].push(userBlockedDevices[deviceId]);
-                }
-            }
-        }
-
-
-        const filteredErrorDevices =
-              await self._olmDevice.filterOutNotifiedErrorDevices(errorDevices);
-        for (const {userId, deviceInfo} of filteredErrorDevices) {
-            blockedMap[userId] = blockedMap[userId] || [];
-            blockedMap[userId].push({
-                code: "m.no_olm",
-                reason: WITHHELD_MESSAGES["m.no_olm"],
-                deviceInfo,
-            });
-        }
-
-        // notify blocked devices that they're blocked
-        await self._notifyBlockedDevices(session, blockedMap);
-    }
+                await this._notifyBlockedDevices(session, blockedMap);
+            })(),
+        ]);
+    };

    // helper which returns the session prepared by prepareSession
    function returnSession() {
@@ -349,96 +386,47 @@ MegolmEncryption.prototype._prepareNewSession = async function() {
 };

 /**
- * Splits the user device map into multiple chunks to reduce the number of
- * devices we encrypt to per API call. Also filters out devices we don't have
- * a session with.
+ * Determines what devices in devicesByUser don't have an olm session as given
+ * in devicemap.
 *
 * @private
 *
- * @param {module:crypto/algorithms/megolm.OutboundSessionInfo} session
+ * @param {object} devicemap the devices that have olm sessions, as returned by
+ *     olmlib.ensureOlmSessionsForDevices.
+ * @param {object} devicesByUser a map of user IDs to array of deviceInfo
+ * @param {array} [noOlmDevices] an array to fill with devices that don't have
+ *     olm sessions
 *
- * @param {number} chainIndex current chain index
- *
- * @param {object<userId, deviceId>} devicemap
- *   mapping from userId to deviceId to {@link module:crypto~OlmSessionResult}
- *
- * @param {object<string, module:crypto/deviceinfo[]>} devicesByUser
- *    map from userid to list of devices
- *
- * @param {array<object>} errorDevices
- *    array that will be populated with the devices that can't get an
- *    olm session for
- *
- * @return {array<object<userid, deviceInfo>>}
+ * @return {array} an array of devices that don't have olm sessions.  If
+ *     noOlmDevices is specified, then noOlmDevices will be returned.
 */
-MegolmEncryption.prototype._splitUserDeviceMap = function(
-    session, chainIndex, devicemap, devicesByUser, errorDevices,
+MegolmEncryption.prototype._getDevicesWithoutSessions = function(
+    devicemap, devicesByUser, noOlmDevices,
 ) {
-    const maxUsersPerRequest = 20;
+    noOlmDevices = noOlmDevices || [];

-    // use an array where the slices of a content map gets stored
-    const mapSlices = [];
-    let currentSliceId = 0; // start inserting in the first slice
-    let entriesInCurrentSlice = 0;
-
-    for (const userId of Object.keys(devicesByUser)) {
-        const devicesToShareWith = devicesByUser[userId];
+    for (const [userId, devicesToShareWith] of Object.entries(devicesByUser)) {
        const sessionResults = devicemap[userId];

-        for (let i = 0; i < devicesToShareWith.length; i++) {
-            const deviceInfo = devicesToShareWith[i];
+        for (const deviceInfo of devicesToShareWith) {
            const deviceId = deviceInfo.deviceId;

            const 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.

-                // mark this device as "handled" because we don't want to try
-                // to claim a one-time-key for dead devices on every message.
-                session.markSharedWithDevice(userId, deviceId, chainIndex);
-
-                errorDevices.push({userId, deviceInfo});
+                noOlmDevices.push({userId, deviceInfo});
+                delete sessionResults[deviceId];

                // ensureOlmSessionsForUsers has already done the logging,
                // so just skip it.
                continue;
            }
-
-            logger.log(
-                "share keys with device " + userId + ":" + deviceId,
-            );
-
-            if (!mapSlices[currentSliceId]) {
-                mapSlices[currentSliceId] = [];
-            }
-
-            mapSlices[currentSliceId].push({
-                userId: userId,
-                deviceInfo: deviceInfo,
-            });
-
-            entriesInCurrentSlice++;
-        }
-
-        // We do this in the per-user loop as we prefer that all messages to the
-        // same user end up in the same API call to make it easier for the
-        // server (e.g. only have to send one EDU if a remote user, etc). This
-        // does mean that if a user has many devices we may go over the desired
-        // limit, but its not a hard limit so that is fine.
-        if (entriesInCurrentSlice > maxUsersPerRequest) {
-            // the current slice is filled up. Start inserting into the next slice
-            entriesInCurrentSlice = 0;
-            currentSliceId++;
        }
    }
-    return mapSlices;
+
+    return noOlmDevices;
 };

 /**
@@ -451,20 +439,18 @@ MegolmEncryption.prototype._splitUserDeviceMap = function(
 *
 * @return {array<array<object>>} the blocked devices, split into chunks
 */
-MegolmEncryption.prototype._splitBlockedDevices = function(devicesByUser) {
-    const maxUsersPerRequest = 20;
+MegolmEncryption.prototype._splitDevices = function(devicesByUser) {
+    const maxDevicesPerRequest = 20;

    // use an array where the slices of a content map gets stored
    let currentSlice = [];
    const mapSlices = [currentSlice];

-    for (const userId of Object.keys(devicesByUser)) {
-        const userBlockedDevicesToShareWith = devicesByUser[userId];
-
-        for (const blockedInfo of userBlockedDevicesToShareWith) {
+    for (const [userId, userDevices] of Object.entries(devicesByUser)) {
+        for (const deviceInfo of Object.values(userDevices)) {
            currentSlice.push({
                userId: userId,
-                blockedInfo: blockedInfo,
+                deviceInfo: deviceInfo.device,
            });
        }

@@ -473,7 +459,7 @@ MegolmEncryption.prototype._splitBlockedDevices = function(devicesByUser) {
        // server (e.g. only have to send one EDU if a remote user, etc). This
        // does mean that if a user has many devices we may go over the desired
        // limit, but its not a hard limit so that is fine.
-        if (currentSlice.length > maxUsersPerRequest) {
+        if (currentSlice.length > maxDevicesPerRequest) {
            // the current slice is filled up. Start inserting into the next slice
            currentSlice = [];
            mapSlices.push(currentSlice);
@@ -497,7 +483,7 @@ MegolmEncryption.prototype._splitBlockedDevices = function(devicesByUser) {
 *
 * @param {object} payload fields to include in the encrypted payload
 *
- * @return {module:client.Promise} Promise which resolves once the key sharing
+ * @return {Promise} Promise which resolves once the key sharing
 *     for the given userDeviceMap is generated and has been sent.
 */
 MegolmEncryption.prototype._encryptAndSendKeysToDevices = function(
@@ -558,7 +544,7 @@ MegolmEncryption.prototype._encryptAndSendKeysToDevices = function(
 *
 * @param {object} payload fields to include in the notification payload
 *
- * @return {module:client.Promise} Promise which resolves once the notifications
+ * @return {Promise} Promise which resolves once the notifications
 *     for the given userDeviceMap is generated and has been sent.
 */
 MegolmEncryption.prototype._sendBlockedNotificationsToDevices = async function(
@@ -568,7 +554,7 @@ MegolmEncryption.prototype._sendBlockedNotificationsToDevices = async function(

    for (const val of userDeviceMap) {
        const userId = val.userId;
-        const blockedInfo = val.blockedInfo;
+        const blockedInfo = val.deviceInfo;
        const deviceInfo = blockedInfo.deviceInfo;
        const deviceId = deviceInfo.deviceId;

@@ -688,37 +674,41 @@ MegolmEncryption.prototype.reshareKeyWithDevice = async function(
 };

 /**
+ * @private
+ *
 * @param {module:crypto/algorithms/megolm.OutboundSessionInfo} session
 *
+ * @param {object} key the session key as returned by
+ *    OlmDevice.getOutboundGroupSessionKey
+ *
+ * @param {object} payload the base to-device message payload for sharing keys
+ *
 * @param {object<string, module:crypto/deviceinfo[]>} devicesByUser
 *    map from userid to list of devices
 *
 * @param {array<object>} errorDevices
 *    array that will be populated with the devices that we can't get an
 *    olm session for
+ *
+ * @param {Number} [otkTimeout] The timeout in milliseconds when requesting
+ *     one-time keys for establishing new olm sessions.
 */
 MegolmEncryption.prototype._shareKeyWithDevices = async function(
-    session, devicesByUser, errorDevices,
+    session, key, payload, devicesByUser, errorDevices, otkTimeout,
 ) {
-    const key = this._olmDevice.getOutboundGroupSessionKey(session.sessionId);
-    const payload = {
-        type: "m.room_key",
-        content: {
-            algorithm: olmlib.MEGOLM_ALGORITHM,
-            room_id: this._roomId,
-            session_id: session.sessionId,
-            session_key: key.key,
-            chain_index: key.chain_index,
-        },
-    };
-
    const devicemap = await olmlib.ensureOlmSessionsForDevices(
-        this._olmDevice, this._baseApis, devicesByUser,
+        this._olmDevice, this._baseApis, devicesByUser, otkTimeout,
    );

-    const userDeviceMaps = this._splitUserDeviceMap(
-        session, key.chain_index, devicemap, devicesByUser, errorDevices,
-    );
+    this._getDevicesWithoutSessions(devicemap, devicesByUser, errorDevices);
+
+    await this._shareKeyWithOlmSessions(session, key, payload, devicemap);
+};
+
+MegolmEncryption.prototype._shareKeyWithOlmSessions = async function(
+    session, key, payload, devicemap,
+) {
+    const userDeviceMaps = this._splitDevices(devicemap);

    for (let i = 0; i < userDeviceMaps.length; i++) {
        try {
@@ -754,7 +744,7 @@ MegolmEncryption.prototype._notifyBlockedDevices = async function(
        sender_key: this._olmDevice.deviceCurve25519Key,
    };

-    const userDeviceMaps = this._splitBlockedDevices(devicesByUser);
+    const userDeviceMaps = this._splitDevices(devicesByUser);

    for (let i = 0; i < userDeviceMaps.length; i++) {
        try {
@@ -772,6 +762,38 @@ MegolmEncryption.prototype._notifyBlockedDevices = async function(
    }
 };

+/**
+ * Perform any background tasks that can be done before a message is ready to
+ * send, in order to speed up sending of the message.
+ *
+ * @param {module:models/room} room the room the event is in
+ */
+MegolmEncryption.prototype.prepareToEncrypt = function(room) {
+    logger.debug(`Preparing to encrypt events for ${this._roomId}`);
+
+    if (this.encryptionPreparation) {
+        // We're already preparing something, so don't do anything else.
+        // FIXME: check if we need to restart
+        // (https://github.com/matrix-org/matrix-js-sdk/issues/1255)
+        return;
+    }
+
+    this.encryptionPreparation = (async () => {
+        const [devicesInRoom, blocked] = await this._getDevicesInRoom(room);
+
+        if (this._crypto.getGlobalErrorOnUnknownDevices()) {
+            // Drop unknown devices for now.  When the message gets sent, we'll
+            // throw an error, but we'll still be prepared to send to the known
+            // devices.
+            this._removeUnknownDevices(devicesInRoom);
+        }
+
+        await this._ensureOutboundSession(devicesInRoom, blocked);
+
+        delete this.encryptionPreparation;
+    })();
+};
+
 /**
 * @inheritdoc
 *
@@ -779,41 +801,51 @@ MegolmEncryption.prototype._notifyBlockedDevices = async function(
 * @param {string} eventType
 * @param {object} content plaintext event content
 *
- * @return {module:client.Promise} Promise which resolves to the new event body
+ * @return {Promise} Promise which resolves to the new event body
 */
 MegolmEncryption.prototype.encryptMessage = async function(room, eventType, content) {
-    const self = this;
    logger.log(`Starting to encrypt event for ${this._roomId}`);

+    if (this.encryptionPreparation) {
+        // If we started sending keys, wait for it to be done.
+        // FIXME: check if we need to cancel
+        // (https://github.com/matrix-org/matrix-js-sdk/issues/1255)
+        try {
+            await this.encryptionPreparation;
+        } catch (e) {
+            // ignore any errors -- if the preparation failed, we'll just
+            // restart everything here
+        }
+    }
+
    const [devicesInRoom, blocked] = await this._getDevicesInRoom(room);

    // check if any of these devices are not yet known to the user.
    // if so, warn the user so they can verify or ignore.
    if (this._crypto.getGlobalErrorOnUnknownDevices()) {
-        self._checkForUnknownDevices(devicesInRoom);
+        this._checkForUnknownDevices(devicesInRoom);
    }

-    const session = await self._ensureOutboundSession(devicesInRoom, blocked);
+    const session = await this._ensureOutboundSession(devicesInRoom, blocked);
    const payloadJson = {
-        room_id: self._roomId,
+        room_id: this._roomId,
        type: eventType,
        content: content,
    };

-    const ciphertext = self._olmDevice.encryptGroupMessage(
+    const ciphertext = this._olmDevice.encryptGroupMessage(
        session.sessionId, JSON.stringify(payloadJson),
    );
-
    const encryptedContent = {
        algorithm: olmlib.MEGOLM_ALGORITHM,
-        sender_key: self._olmDevice.deviceCurve25519Key,
+        sender_key: this._olmDevice.deviceCurve25519Key,
        ciphertext: ciphertext,
        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.
        // XXX: Do we still need this now that m.new_device messages
        // no longer exist since #483?
-        device_id: self._deviceId,
+        device_id: this._deviceId,
    };

    session.useCount++;
@@ -861,12 +893,33 @@ MegolmEncryption.prototype._checkForUnknownDevices = function(devicesInRoom) {
    }
 };

+/**
+ * Remove unknown devices from a set of devices.  The devicesInRoom parameter
+ * will be modified.
+ *
+ * @param {Object} devicesInRoom userId -> {deviceId -> object}
+ *   devices we should shared the session with.
+ */
+MegolmEncryption.prototype._removeUnknownDevices = function(devicesInRoom) {
+    for (const [userId, userDevices] of Object.entries(devicesInRoom)) {
+        for (const [deviceId, device] of Object.entries(userDevices)) {
+            if (device.isUnverified() && !device.isKnown()) {
+                delete userDevices[deviceId];
+            }
+        }
+
+        if (Object.keys(userDevices).length === 0) {
+            delete devicesInRoom[userId];
+        }
+    }
+};
+
 /**
 * Get the list of unblocked devices for all users in the room
 *
 * @param {module:models/room} room
 *
- * @return {module:client.Promise} Promise which resolves to an array whose
+ * @return {Promise} Promise which resolves to an array whose
 *     first element is a map from userId to deviceId to deviceInfo indicating
 *     the devices that messages should be encrypted to, and whose second
 *     element is a map from userId to deviceId to data indicating the devices
@@ -1247,6 +1300,9 @@ MegolmDecryption.prototype.onRoomKeyWithheldEvent = async function(event) {

    if (content.code === "m.no_olm") {
        const sender = event.getSender();
+        logger.warn(
+            `${sender}:${senderKey} was unable to establish an olm session with us`,
+        );
        // if the sender says that they haven't been able to establish an olm
        // session, let's proactively establish one

@@ -1258,21 +1314,30 @@ MegolmDecryption.prototype.onRoomKeyWithheldEvent = async function(event) {
        if (await this._olmDevice.getSessionIdForDevice(senderKey)) {
            // a session has already been established, so we don't need to
            // create a new one.
+            logger.debug("New session already created.  Not creating a new one.");
            await this._olmDevice.recordSessionProblem(senderKey, "no_olm", true);
            this.retryDecryptionFromSender(senderKey);
            return;
        }
-        const device = this._crypto._deviceList.getDeviceByIdentityKey(
+        let device = this._crypto._deviceList.getDeviceByIdentityKey(
            content.algorithm, senderKey,
        );
        if (!device) {
-            logger.info(
-                "Couldn't find device for identity key " + senderKey +
-                    ": not establishing session",
+            // if we don't know about the device, fetch the user's devices again
+            // and retry before giving up
+            await this._crypto.downloadKeys([sender], false);
+            device = this._crypto._deviceList.getDeviceByIdentityKey(
+                content.algorithm, senderKey,
            );
-            await this._olmDevice.recordSessionProblem(senderKey, "no_olm", false);
-            this.retryDecryptionFromSender(senderKey);
-            return;
+            if (!device) {
+                logger.info(
+                    "Couldn't find device for identity key " + senderKey +
+                        ": not establishing session",
+                );
+                await this._olmDevice.recordSessionProblem(senderKey, "no_olm", false);
+                this.retryDecryptionFromSender(senderKey);
+                return;
+            }
        }
        await olmlib.ensureOlmSessionsForDevices(
            this._olmDevice, this._baseApis, {[sender]: [device]}, false,
@@ -1481,7 +1546,6 @@ MegolmDecryption.prototype._retryDecryption = async function(senderKey, sessionI

 MegolmDecryption.prototype.retryDecryptionFromSender = async function(senderKey) {
    const senderPendingEvents = this._pendingEvents[senderKey];
-    logger.warn(senderPendingEvents);
    if (!senderPendingEvents) {
        return true;
    }
@@ -1491,7 +1555,6 @@ MegolmDecryption.prototype.retryDecryptionFromSender = async function(senderKey)
    await Promise.all([...senderPendingEvents].map(async ([_sessionId, pending]) => {
        await Promise.all([...pending].map(async (ev) => {
            try {
-                logger.warn(ev.getId());
                await ev.attemptDecryption(this._crypto);
            } catch (e) {
                // don't die if something goes wrong
@@ -54,7 +54,7 @@ utils.inherits(OlmEncryption, EncryptionAlgorithm);
 * @private

 * @param {string[]} roomMembers list of currently-joined users in the room
- * @return {module:client.Promise} Promise which resolves when setup is complete
+ * @return {Promise} Promise which resolves when setup is complete
 */
 OlmEncryption.prototype._ensureSession = function(roomMembers) {
    if (this._prepPromise) {
@@ -85,7 +85,7 @@ OlmEncryption.prototype._ensureSession = function(roomMembers) {
 * @param {string} eventType
 * @param {object} content plaintext event content
 *
- * @return {module:client.Promise} Promise which resolves to the new event body
+ * @return {Promise} Promise which resolves to the new event body
 */
 OlmEncryption.prototype.encryptMessage = async function(room, eventType, content) {
    // pick the list of recipients based on the membership list.
@@ -37,33 +37,43 @@ import {
    CrossSigningLevel,
    DeviceTrustLevel,
    UserTrustLevel,
+    createCryptoStoreCacheCallbacks,
 } from './CrossSigning';
 import {SECRET_STORAGE_ALGORITHM_V1, SecretStorage} from './SecretStorage';
 import {OutgoingRoomKeyRequestManager} from './OutgoingRoomKeyRequestManager';
 import {IndexedDBCryptoStore} from './store/indexeddb-crypto-store';
-import {ScanQRCode, ShowQRCode} from './verification/QRCode';
+import {
+    ReciprocateQRCode,
+    SCAN_QR_CODE_METHOD,
+    SHOW_QR_CODE_METHOD,
+} from './verification/QRCode';
 import {SAS} from './verification/SAS';
 import {keyFromPassphrase} from './key_passphrase';
 import {encodeRecoveryKey} from './recoverykey';
 import {VerificationRequest} from "./verification/request/VerificationRequest";
-import {InRoomChannel} from "./verification/request/InRoomChannel";
-import {ToDeviceChannel} from "./verification/request/ToDeviceChannel";
+import {InRoomChannel, InRoomRequests} from "./verification/request/InRoomChannel";
+import {ToDeviceChannel, ToDeviceRequests} from "./verification/request/ToDeviceChannel";
 import * as httpApi from "../http-api";
+import {IllegalMethod} from "./verification/IllegalMethod";

 const DeviceVerification = DeviceInfo.DeviceVerification;

 const defaultVerificationMethods = {
-    [ScanQRCode.NAME]: ScanQRCode,
-    [ShowQRCode.NAME]: ShowQRCode,
+    [ReciprocateQRCode.NAME]: ReciprocateQRCode,
    [SAS.NAME]: SAS,
+
+    // These two can't be used for actual verification, but we do
+    // need to be able to define them here for the verification flows
+    // to start.
+    [SHOW_QR_CODE_METHOD]: IllegalMethod,
+    [SCAN_QR_CODE_METHOD]: IllegalMethod,
 };

 /**
 * verification method names
 */
 export const verificationMethods = {
-    QR_CODE_SCAN: ScanQRCode.NAME,
-    QR_CODE_SHOW: ShowQRCode.NAME,
+    RECIPROCATE_QR_CODE: ReciprocateQRCode.NAME,
    SAS: SAS.NAME,
 };

@@ -117,8 +127,8 @@ export function Crypto(baseApis, sessionStore, userId, deviceId,
    this._clientStore = clientStore;
    this._cryptoStore = cryptoStore;
    this._roomList = roomList;
-    this._verificationMethods = new Map();
    if (verificationMethods) {
+        this._verificationMethods = new Map();
        for (const method of verificationMethods) {
            if (typeof method === "string") {
                if (defaultVerificationMethods[method]) {
@@ -132,10 +142,13 @@ export function Crypto(baseApis, sessionStore, userId, deviceId,
                    method.NAME,
                    method,
                );
+            } else {
+                console.warn(`Excluding unknown verification method ${method}`);
            }
        }
+    } else {
+        this._verificationMethods = defaultVerificationMethods;
    }
-
    // track whether this device's megolm keys are being backed up incrementally
    // to the server or not.
    // XXX: this should probably have a single source of truth from OlmAccount
@@ -204,12 +217,17 @@ export function Crypto(baseApis, sessionStore, userId, deviceId,
    // }
    this._lastNewSessionForced = {};

-    this._toDeviceVerificationRequests = new Map();
-    this._inRoomVerificationRequests = new Map();
+    this._toDeviceVerificationRequests = new ToDeviceRequests();
+    this._inRoomVerificationRequests = new InRoomRequests();

    const cryptoCallbacks = this._baseApis._cryptoCallbacks || {};
+    const cacheCallbacks = createCryptoStoreCacheCallbacks(cryptoStore);

-    this._crossSigningInfo = new CrossSigningInfo(userId, cryptoCallbacks);
+    this._crossSigningInfo = new CrossSigningInfo(
+        userId,
+        cryptoCallbacks,
+        cacheCallbacks,
+    );

    this._secretStorage = new SecretStorage(
        baseApis, cryptoCallbacks, this._crossSigningInfo,
@@ -228,12 +246,24 @@ utils.inherits(Crypto, EventEmitter);
 * Initialise the crypto module so that it is ready for use
 *
 * Returns a promise which resolves once the crypto module is ready for use.
+ *
+ * @param {Object} opts keyword arguments.
+ * @param {string} opts.exportedOlmDevice (Optional) data from exported device
+ *     that must be re-created.
 */
-Crypto.prototype.init = async function() {
+Crypto.prototype.init = async function(opts) {
+    const {
+        exportedOlmDevice,
+    } = opts || {};
+
    logger.log("Crypto: initialising Olm...");
    await global.Olm.init();
-    logger.log("Crypto: initialising Olm device...");
-    await this._olmDevice.init();
+    logger.log(
+        exportedOlmDevice
+            ? "Crypto: initialising Olm device from exported device..."
+            : "Crypto: initialising Olm device...",
+    );
+    await this._olmDevice.init({ fromExportedDevice: exportedOlmDevice });
    logger.log("Crypto: loading device list...");
    await this._deviceList.load();

@@ -336,6 +366,10 @@ Crypto.prototype.createRecoveryKeyFromPassphrase = async function(password) {
 * called to await a secret storage key creation flow.
 * @param {object} [opts.keyBackupInfo] The current key backup object. If passed,
 * the passphrase and recovery key from this backup will be used.
+ * @param {bool} [opts.setupNewKeyBackup] If true, a new key backup version will be
+ * created and the private key stored in the new SSSS store. Ignored if keyBackupInfo
+ * is supplied.
+ * @param {bool} [opts.setupNewSecretStorage] Optional. Reset even if keys already exist.
 * Returns:
 *     {Promise} A promise which resolves to key creation data for
 *     SecretStorage#addKey: an object with `passphrase` and/or `pubkey` fields.
@@ -344,6 +378,8 @@ Crypto.prototype.bootstrapSecretStorage = async function({
    authUploadDeviceSigningKeys,
    createSecretStorageKey = async () => { },
    keyBackupInfo,
+    setupNewKeyBackup,
+    setupNewSecretStorage,
 } = {}) {
    logger.log("Bootstrapping Secure Secret Storage");

@@ -351,7 +387,7 @@ Crypto.prototype.bootstrapSecretStorage = async function({
    // key with the cross-signing master key. The cross-signing master key is also used
    // to verify the signature on the SSSS default key when adding secrets, so we
    // effectively need it for both reading and writing secrets.
-    let crossSigningPrivateKeys = {};
+    const crossSigningPrivateKeys = {};

    // If we happen to reset cross-signing keys here, then we want access to the
    // cross-signing private keys, but only for the scope of this method, so we
@@ -359,7 +395,7 @@ Crypto.prototype.bootstrapSecretStorage = async function({
    const appCallbacks = Object.assign({}, this._baseApis._cryptoCallbacks);

    try {
-        const inStorage =
+        const inStorage = !setupNewSecretStorage &&
            await this._crossSigningInfo.isStoredInSecretStorage(this._secretStorage);
        if (!this._crossSigningInfo.getId() || !inStorage) {
            logger.log(
@@ -375,7 +411,7 @@ Crypto.prototype.bootstrapSecretStorage = async function({
                    "creating new keys",
                );
                this._baseApis._cryptoCallbacks.saveCrossSigningKeys =
-                    keys => crossSigningPrivateKeys = keys;
+                    keys => Object.assign(crossSigningPrivateKeys, keys);
                this._baseApis._cryptoCallbacks.getCrossSigningKey =
                    name => crossSigningPrivateKeys[name];
                await this.resetCrossSigningKeys(
@@ -389,7 +425,7 @@ Crypto.prototype.bootstrapSecretStorage = async function({

        // Check if Secure Secret Storage has a default key. If we don't have one, create
        // the default key (which will also be signed by the cross-signing master key).
-        if (!await this.hasSecretStorageKey()) {
+        if (setupNewSecretStorage || !await this.hasSecretStorageKey()) {
            let newKeyId;
            if (keyBackupInfo) {
                logger.log("Secret storage default key not found, using key backup key");
@@ -467,8 +503,24 @@ Crypto.prototype.bootstrapSecretStorage = async function({
                );
            }
        }
+
+        if (setupNewKeyBackup && !keyBackupInfo) {
+            const info = await this._baseApis.prepareKeyBackupVersion(
+                null /* random key */,
+                { secureSecretStorage: true },
+            );
+            await this._baseApis.createKeyBackupVersion(info);
+        }
    } finally {
-        this._baseApis._cryptoCallbacks = appCallbacks;
+        // Restore the original callbacks. NB. we must do this by manipulating
+        // the same object since the CrossSigning class has a reference to the
+        // object, so if we assign the object here then our callbacks will change
+        // but the instances of the CrossSigning class will be left with our
+        // random, otherwise dead closures.
+        for (const cb of Object.keys(this._baseApis._cryptoCallbacks)) {
+            delete this._baseApis._cryptoCallbacks[cb];
+        }
+        Object.assign(this._baseApis._cryptoCallbacks, appCallbacks);
    }

    logger.log("Secure Secret Storage ready");
@@ -609,49 +661,65 @@ Crypto.prototype.resetCrossSigningKeys = async function(level, {
 * verifications, etc.
 */
 Crypto.prototype._afterCrossSigningLocalKeyChange = async function() {
+    logger.info("Starting cross-signing key change post-processing");
+
    // sign the current device with the new key, and upload to the server
    const device = this._deviceList.getStoredDevice(this._userId, this._deviceId);
    const signedDevice = await this._crossSigningInfo.signDevice(this._userId, device);
-    await this._baseApis.uploadKeySignatures({
+    logger.info(`Starting background key sig upload for ${this._deviceId}`);
+    this._baseApis.uploadKeySignatures({
        [this._userId]: {
            [this._deviceId]: signedDevice,
        },
+    }).then(() => {
+        logger.info(`Finished background key sig upload for ${this._deviceId}`);
+    }).catch(e => {
+        logger.error(`Error during background key sig upload for ${this._deviceId}`, e);
    });

-    // check all users for signatures
-    // FIXME: do this in batches
-    const users = {};
-    for (const [userId, crossSigningInfo]
-         of Object.entries(this._deviceList._crossSigningInfo)) {
-        const upgradeInfo = await this._checkForDeviceVerificationUpgrade(
-            userId, CrossSigningInfo.fromStorage(crossSigningInfo, userId),
-        );
-        if (upgradeInfo) {
-            users[userId] = upgradeInfo;
-        }
-    }
-
    const shouldUpgradeCb = (
        this._baseApis._cryptoCallbacks.shouldUpgradeDeviceVerifications
    );
-    if (Object.keys(users).length > 0 && shouldUpgradeCb) {
-        try {
-            const usersToUpgrade = await shouldUpgradeCb({users: users});
-            if (usersToUpgrade) {
-                for (const userId of usersToUpgrade) {
-                    if (userId in users) {
-                        await this._baseApis.setDeviceVerified(
-                            userId, users[userId].crossSigningInfo.getId(),
-                        );
+    if (shouldUpgradeCb) {
+        logger.info("Starting device verification upgrade");
+
+        // Check all users for signatures if upgrade callback present
+        // FIXME: do this in batches
+        const users = {};
+        for (const [userId, crossSigningInfo]
+            of Object.entries(this._deviceList._crossSigningInfo)) {
+            const upgradeInfo = await this._checkForDeviceVerificationUpgrade(
+                userId, CrossSigningInfo.fromStorage(crossSigningInfo, userId),
+            );
+            if (upgradeInfo) {
+                users[userId] = upgradeInfo;
+            }
+        }
+
+        if (Object.keys(users).length > 0) {
+            logger.info(`Found ${Object.keys(users).length} verif users to upgrade`);
+            try {
+                const usersToUpgrade = await shouldUpgradeCb({ users: users });
+                if (usersToUpgrade) {
+                    for (const userId of usersToUpgrade) {
+                        if (userId in users) {
+                            await this._baseApis.setDeviceVerified(
+                                userId, users[userId].crossSigningInfo.getId(),
+                            );
+                        }
                    }
                }
+            } catch (e) {
+                logger.log(
+                    "shouldUpgradeDeviceVerifications threw an error: not upgrading", e,
+                );
            }
-        } catch (e) {
-            logger.log(
-                "shouldUpgradeDeviceVerifications threw an error: not upgrading", e,
-            );
        }
+
+        logger.info("Finished device verification upgrade");
    }
+
+    logger.info("Finished cross-signing key change post-processing");
 };

 /**
@@ -762,6 +830,18 @@ Crypto.prototype.checkUserTrust = function(userId) {
 */
 Crypto.prototype.checkDeviceTrust = function(userId, deviceId) {
    const device = this._deviceList.getStoredDevice(userId, deviceId);
+    return this._checkDeviceInfoTrust(userId, device);
+};
+
+/**
+ * Check whether a given deviceinfo is trusted.
+ *
+ * @param {string} userId The ID of the user whose devices is to be checked.
+ * @param {module:crypto/deviceinfo?} device The device info object to check
+ *
+ * @returns {DeviceTrustLevel}
+ */
+Crypto.prototype._checkDeviceInfoTrust = function(userId, device) {
    const trustedLocally = device && device.isVerified();

    const userCrossSigning = this._deviceList.getStoredCrossSigningForUser(userId);
@@ -811,6 +891,10 @@ Crypto.prototype._onDeviceListUserCrossSigningUpdated = async function(userId) {
 Crypto.prototype.checkOwnCrossSigningTrust = async function() {
    const userId = this._userId;

+    // Before proceeding, ensure our cross-signing public keys have been
+    // downloaded via the device list.
+    await this.downloadKeys([this._userId]);
+
    // If we see an update to our own master key, check it against the master
    // key we have and, if it matches, mark it as verified

@@ -850,13 +934,7 @@ Crypto.prototype.checkOwnCrossSigningTrust = async function() {
    const oldUserSigningId = this._crossSigningInfo.getId("user_signing");

    // Update the version of our keys in our cross-signing object and the local store
-    this._crossSigningInfo.setKeys(newCrossSigning.keys);
-    await this._cryptoStore.doTxn(
-        'readwrite', [IndexedDBCryptoStore.STORE_ACCOUNT],
-        (txn) => {
-            this._cryptoStore.storeCrossSigningKeys(txn, this._crossSigningInfo.keys);
-        },
-    );
+    this._storeTrustedSelfKeys(newCrossSigning.keys);

    const keySignatures = {};

@@ -879,8 +957,14 @@ Crypto.prototype.checkOwnCrossSigningTrust = async function() {
            = this._crossSigningInfo.keys.master;
    }

-    if (Object.keys(keySignatures).length) {
-        await this._baseApis.uploadKeySignatures({[this._userId]: keySignatures});
+    const keysToUpload = Object.keys(keySignatures);
+    if (keysToUpload.length) {
+        logger.info(`Starting background key sig upload for ${keysToUpload}`);
+        this._baseApis.uploadKeySignatures({ [this._userId]: keySignatures }).then(() => {
+            logger.info(`Finished background key sig upload for ${keysToUpload}`);
+        }).catch(e => {
+            logger.error(`Error during background key sig upload for ${keysToUpload}`, e);
+        });
    }

    this.emit("userTrustStatusChanged", userId, this.checkUserTrust(userId));
@@ -896,6 +980,21 @@ Crypto.prototype.checkOwnCrossSigningTrust = async function() {
    // the backup with the new key (if not already signed)?
 };

+/**
+ * Store a set of keys as our own, trusted, cross-signing keys.
+ *
+ * @param {object} keys The new trusted set of keys
+ */
+Crypto.prototype._storeTrustedSelfKeys = async function(keys) {
+    this._crossSigningInfo.setKeys(keys);
+    await this._cryptoStore.doTxn(
+        'readwrite', [IndexedDBCryptoStore.STORE_ACCOUNT],
+        (txn) => {
+            this._cryptoStore.storeCrossSigningKeys(txn, this._crossSigningInfo.keys);
+        },
+    );
+};
+
 /**
 * Check if the master key is signed by a verified device, and if so, prompt
 * the application to mark it as verified.
@@ -903,16 +1002,21 @@ Crypto.prototype.checkOwnCrossSigningTrust = async function() {
 * @param {string} userId the user ID whose key should be checked
 */
 Crypto.prototype._checkDeviceVerifications = async function(userId) {
+    const shouldUpgradeCb = (
+        this._baseApis._cryptoCallbacks.shouldUpgradeDeviceVerifications
+    );
+    if (!shouldUpgradeCb) {
+        // Upgrading skipped when callback is not present.
+        return;
+    }
+    logger.info(`Starting device verification upgrade for ${userId}`);
    if (this._crossSigningInfo.keys.user_signing) {
        const crossSigningInfo = this._deviceList.getStoredCrossSigningForUser(userId);
        if (crossSigningInfo) {
            const upgradeInfo = await this._checkForDeviceVerificationUpgrade(
                userId, crossSigningInfo,
            );
-            const shouldUpgradeCb = (
-                this._baseApis._cryptoCallbacks.shouldUpgradeDeviceVerifications
-            );
-            if (upgradeInfo && shouldUpgradeCb) {
+            if (upgradeInfo) {
                const usersToUpgrade = await shouldUpgradeCb({
                    users: {
                        [userId]: upgradeInfo,
@@ -926,6 +1030,7 @@ Crypto.prototype._checkDeviceVerifications = async function(userId) {
            }
        }
    }
+    logger.info(`Finished device verification upgrade for ${userId}`);
 };

 /**
@@ -1147,17 +1252,13 @@ Crypto.prototype.registerEventHandlers = function(eventEmitter) {
        }
    });

-    eventEmitter.on("toDeviceEvent", function(event) {
-        crypto._onToDeviceEvent(event);
-    });
+    eventEmitter.on("toDeviceEvent", crypto._onToDeviceEvent.bind(crypto));

-    eventEmitter.on("Room.timeline", function(event) {
-        crypto._onTimelineEvent(event);
-    });
+    const timelineHandler = crypto._onTimelineEvent.bind(crypto);

-    eventEmitter.on("Event.decrypted", function(event) {
-        crypto._onTimelineEvent(event);
-    });
+    eventEmitter.on("Room.timeline", timelineHandler);
+
+    eventEmitter.on("Event.decrypted", timelineHandler);
 };


@@ -1188,6 +1289,15 @@ Crypto.prototype.getDeviceEd25519Key = function() {
    return this._olmDevice.deviceEd25519Key;
 };

+/**
+ * Get the Curve25519 key for this device
+ *
+ * @return {string} base64-encoded curve25519 key.
+ */
+Crypto.prototype.getDeviceCurve25519Key = function() {
+    return this._olmDevice.deviceCurve25519Key;
+};
+
 /**
 * Set the global override for whether the client should ever send encrypted
 * messages to unverified devices.  This provides the default for rooms which
@@ -1248,10 +1358,6 @@ Crypto.prototype.uploadDeviceKeys = function() {
    return crypto._signObject(deviceKeys).then(() => {
        return crypto._baseApis.uploadKeysRequest({
            device_keys: deviceKeys,
-        }, {
-            // for now, we set the device id explicitly, as we may not be using the
-            // same one as used in login.
-            device_id: deviceId,
        });
    });
 };
@@ -1348,9 +1454,7 @@ function _maybeUploadOneTimeKeys(crypto) {
            return Promise.resolve(crypto._oneTimeKeyCount);
        }
        // ask the server how many keys we have
-        return crypto._baseApis.uploadKeysRequest({}, {
-            device_id: crypto._deviceId,
-        }).then((res) => {
+        return crypto._baseApis.uploadKeysRequest({}).then((res) => {
            return res.one_time_key_counts.signed_curve25519 || 0;
        });
    }).then((keyCount) => {
@@ -1390,10 +1494,6 @@ async function _uploadOneTimeKeys(crypto) {

    const res = await crypto._baseApis.uploadKeysRequest({
        one_time_keys: oneTimeJson,
-    }, {
-        // for now, we set the device id explicitly, as we may not be using the
-        // same one as used in login.
-        device_id: crypto._deviceId,
    });

    await crypto._olmDevice.markKeysAsPublished();
@@ -1492,17 +1592,32 @@ Crypto.prototype.setDeviceVerification = async function(
        if (!verified) {
            throw new Error("Cannot set a cross-signing key as unverified");
        }
-        const device = await this._crossSigningInfo.signUser(xsk);
-        if (device) {
-            await this._baseApis.uploadKeySignatures({
-                [userId]: {
-                    [deviceId]: device,
-                },
-            });
-            // This will emit events when it comes back down the sync
-            // (we could do local echo to speed things up)
+
+        if (!this._crossSigningInfo.getId() && userId === this._crossSigningInfo.userId) {
+            this._storeTrustedSelfKeys(xsk.keys);
+        }
+
+        // Now sign the master key with our user signing key (unless it's ourself)
+        if (userId !== this._userId) {
+            logger.info(
+                "Master key " + xsk.getId() + " for " + userId +
+                " marked verified. Signing...",
+            );
+            const device = await this._crossSigningInfo.signUser(xsk);
+            if (device) {
+                logger.info("Uploading signature for " + userId + "...");
+                await this._baseApis.uploadKeySignatures({
+                    [userId]: {
+                        [deviceId]: device,
+                    },
+                });
+                // This will emit events when it comes back down the sync
+                // (we could do local echo to speed things up)
+            }
+            return device;
+        } else {
+            return xsk;
        }
-        return device;
    }

    const devices = this._deviceList.getRawStoredDevicesForUser(userId);
@@ -1539,10 +1654,12 @@ Crypto.prototype.setDeviceVerification = async function(

    // do cross-signing
    if (verified && userId === this._userId) {
+        logger.info("Own device " + deviceId + " marked verified: signing");
        const device = await this._crossSigningInfo.signDevice(
            userId, DeviceInfo.fromStorage(dev, deviceId),
        );
        if (device) {
+            logger.info("Uploading signature for " + deviceId);
            await this._baseApis.uploadKeySignatures({
                [userId]: {
                    [deviceId]: device,
@@ -1557,98 +1674,79 @@ Crypto.prototype.setDeviceVerification = async function(
    return deviceObj;
 };

-Crypto.prototype.requestVerificationDM = async function(userId, roomId, methods) {
+Crypto.prototype.findVerificationRequestDMInProgress = function(roomId) {
+    return this._inRoomVerificationRequests.findRequestInProgress(roomId);
+};
+
+Crypto.prototype.requestVerificationDM = function(userId, roomId) {
+    const existingRequest = this._inRoomVerificationRequests.
+        findRequestInProgress(roomId);
+    if (existingRequest) {
+        return Promise.resolve(existingRequest);
+    }
    const channel = new InRoomChannel(this._baseApis, roomId, userId);
-    const request = await this._requestVerificationWithChannel(
+    return this._requestVerificationWithChannel(
        userId,
-        methods,
        channel,
        this._inRoomVerificationRequests,
    );
-    return await request.waitForVerifier();
 };

-Crypto.prototype.acceptVerificationDM = function(event, method) {
-    if(!InRoomChannel.validateEvent(event, this._baseApis)) {
-        return;
-    }
-
-    const sender = event.getSender();
-    const requestsByTxnId = this._inRoomVerificationRequests.get(sender);
-    if (!requestsByTxnId) {
-        return;
-    }
-    const transactionId = InRoomChannel.getTransactionId(event);
-    const request = requestsByTxnId.get(transactionId);
-    if (!request) {
-        return;
-    }
-
-    return request.beginKeyVerification(method);
-};
-
-Crypto.prototype.requestVerification = async function(userId, methods, devices) {
+Crypto.prototype.requestVerification = function(userId, devices) {
    if (!devices) {
        devices = Object.keys(this._deviceList.getRawStoredDevicesForUser(userId));
    }
+    const existingRequest = this._toDeviceVerificationRequests
+        .findRequestInProgress(userId, devices);
+    if (existingRequest) {
+        return Promise.resolve(existingRequest);
+    }
    const channel = new ToDeviceChannel(this._baseApis, userId, devices);
-    const request = await this._requestVerificationWithChannel(
+    return this._requestVerificationWithChannel(
        userId,
-        methods,
        channel,
        this._toDeviceVerificationRequests,
    );
-    return await request.waitForVerifier();
 };

 Crypto.prototype._requestVerificationWithChannel = async function(
-    userId, methods, channel, requestsMap,
+    userId, channel, requestsMap,
 ) {
-    if (!methods) {
-        // .keys() returns an iterator, so we need to explicitly turn it into an array
-        methods = [...this._verificationMethods.keys()];
-    }
-    // TODO: filter by given methods
-    const request = new VerificationRequest(
-        channel, this._verificationMethods, userId, this._baseApis);
+    let request = new VerificationRequest(
+        channel, this._verificationMethods, this._baseApis);
    await request.sendRequest();
-
-    let requestsByTxnId = requestsMap.get(userId);
-    if (!requestsByTxnId) {
-        requestsByTxnId = new Map();
-        requestsMap.set(userId, requestsByTxnId);
+    // don't replace the request created by a racing remote echo
+    const racingRequest = requestsMap.getRequestByChannel(channel);
+    if (racingRequest) {
+        request = racingRequest;
+    } else {
+        logger.log(`Crypto: adding new request to ` +
+            `requestsByTxnId with id ${channel.transactionId} ${channel.roomId}`);
+        requestsMap.setRequestByChannel(channel, request);
    }
-    // TODO: we're only adding the request to the map once it has been sent
-    // but if the other party is really fast they could potentially respond to the
-    // request before the server tells us the event got sent, and we would probably
-    // create a new request object
-    requestsByTxnId.set(channel.transactionId, request);
-
    return request;
 };

 Crypto.prototype.beginKeyVerification = function(
    method, userId, deviceId, transactionId = null,
 ) {
-    let requestsByTxnId = this._toDeviceVerificationRequests.get(userId);
-    if (!requestsByTxnId) {
-        requestsByTxnId = new Map();
-        this._toDeviceVerificationRequests.set(userId, requestsByTxnId);
-    }
    let request;
    if (transactionId) {
-        request = requestsByTxnId.get(transactionId);
+        request = this._toDeviceVerificationRequests.getRequestBySenderAndTxnId(
+            userId, transactionId);
+        if (!request) {
+            throw new Error(
+                `No request found for user ${userId} with ` +
+                `transactionId ${transactionId}`);
+        }
    } else {
        transactionId = ToDeviceChannel.makeTransactionId();
        const channel = new ToDeviceChannel(
            this._baseApis, userId, [deviceId], transactionId, deviceId);
        request = new VerificationRequest(
-            channel, this._verificationMethods, userId, this._baseApis);
-        requestsByTxnId.set(transactionId, request);
-    }
-    if (!request) {
-        throw new Error(
-            `No request found for user ${userId} with transactionId ${transactionId}`);
+            channel, this._verificationMethods, this._baseApis);
+        this._toDeviceVerificationRequests.setRequestBySenderAndTxnId(
+            userId, transactionId, request);
    }
    return request.beginKeyVerification(method, {userId, deviceId});
 };
@@ -1899,7 +1997,7 @@ Crypto.prototype.trackRoomDevices = function(roomId) {
 *
 * @param {string[]} users list of user ids
 *
- * @return {module:client.Promise} resolves once the sessions are complete, to
+ * @return {Promise} resolves once the sessions are complete, to
 *    an Object mapping from userId to deviceId to
 *    {@link module:crypto~OlmSessionResult}
 */
@@ -1962,7 +2060,7 @@ Crypto.prototype.exportRoomKeys = async function() {
 * Import a list of room keys previously exported by exportRoomKeys
 *
 * @param {Object[]} keys a list of session export objects
- * @return {module:client.Promise} a promise which resolves once the keys have been imported
+ * @return {Promise} a promise which resolves once the keys have been imported
 */
 Crypto.prototype.importRoomKeys = function(keys) {
    return Promise.all(keys.map((key) => {
@@ -2073,11 +2171,12 @@ Crypto.prototype._backupPendingKeys = async function(limit) {
        const device = this._deviceList.getDeviceByIdentityKey(
            olmlib.MEGOLM_ALGORITHM, session.senderKey,
        );
+        const verified = this._checkDeviceInfoTrust(this._userId, device).isVerified();

        data[roomId]['sessions'][session.sessionId] = {
            first_message_index: firstKnownIndex,
            forwarded_count: forwardedCount,
-            is_verified: !!(device && device.isVerified()),
+            is_verified: verified,
            session_data: encrypted,
        };
    }
@@ -2158,7 +2257,7 @@ Crypto.prototype.flagAllGroupSessionsForBackup = async function() {
 *
 * @param {module:models/room} room destination room.
 *
- * @return {module:client.Promise?} Promise which resolves when the event has been
+ * @return {Promise?} Promise which resolves when the event has been
 *     encrypted, or null if nothing was needed
 */
 /* eslint-enable valid-jsdoc */
@@ -2534,7 +2633,6 @@ Crypto.prototype._onKeyVerificationMessage = function(event) {
    if (!ToDeviceChannel.validateEvent(event, this._baseApis)) {
        return;
    }
-    const transactionId = ToDeviceChannel.getTransactionId(event);
    const createRequest = event => {
        if (!ToDeviceChannel.canCreateRequest(ToDeviceChannel.getEventType(event))) {
            return;
@@ -2551,10 +2649,13 @@ Crypto.prototype._onKeyVerificationMessage = function(event) {
            [deviceId],
        );
        return new VerificationRequest(
-            channel, this._verificationMethods, userId, this._baseApis);
+            channel, this._verificationMethods, this._baseApis);
    };
-    this._handleVerificationEvent(event, transactionId,
-        this._toDeviceVerificationRequests, createRequest);
+    this._handleVerificationEvent(
+        event,
+        this._toDeviceVerificationRequests,
+        createRequest,
+    );
 };

 /**
@@ -2562,65 +2663,60 @@ Crypto.prototype._onKeyVerificationMessage = function(event) {
 *
 * @private
 * @param {module:models/event.MatrixEvent} event the timeline event
+ * @param {module:models/Room} room not used
+ * @param {bool} atStart not used
+ * @param {bool} removed not used
+ * @param {bool} data.liveEvent whether this is a live event
 */
-Crypto.prototype._onTimelineEvent = function(event) {
+Crypto.prototype._onTimelineEvent = function(
+    event, room, atStart, removed, {liveEvent} = {},
+) {
    if (!InRoomChannel.validateEvent(event, this._baseApis)) {
        return;
    }
-    const transactionId = InRoomChannel.getTransactionId(event);
    const createRequest = event => {
-        if (!InRoomChannel.canCreateRequest(InRoomChannel.getEventType(event))) {
-            return;
-        }
-        const userId = event.getSender();
        const channel = new InRoomChannel(
            this._baseApis,
            event.getRoomId(),
-            userId,
        );
        return new VerificationRequest(
-            channel, this._verificationMethods, userId, this._baseApis);
+            channel, this._verificationMethods, this._baseApis);
    };
-    this._handleVerificationEvent(event, transactionId,
-        this._inRoomVerificationRequests, createRequest);
+    this._handleVerificationEvent(
+        event,
+        this._inRoomVerificationRequests,
+        createRequest,
+        liveEvent,
+    );
 };

 Crypto.prototype._handleVerificationEvent = async function(
-    event, transactionId, requestsMap, createRequest,
+    event, requestsMap, createRequest, isLiveEvent = true,
 ) {
-    const sender = event.getSender();
-    let requestsByTxnId = requestsMap.get(sender);
+    let request = requestsMap.getRequest(event);
    let isNewRequest = false;
-    let request = requestsByTxnId && requestsByTxnId.get(transactionId);
    if (!request) {
        request = createRequest(event);
        // a request could not be made from this event, so ignore event
        if (!request) {
+            logger.log(`Crypto: could not find VerificationRequest for ` +
+                `${event.getType()}, and could not create one, so ignoring.`);
            return;
        }
        isNewRequest = true;
-        if (!requestsByTxnId) {
-            requestsByTxnId = new Map();
-            requestsMap.set(sender, requestsByTxnId);
-        }
-        requestsByTxnId.set(transactionId, request);
+        requestsMap.setRequest(event, request);
    }
+    event.setVerificationRequest(request);
    try {
-        const hadVerifier = !!request.verifier;
-        await request.channel.handleEvent(event, request);
-        // emit start event when verifier got set
-        if (!hadVerifier && request.verifier) {
-            this._baseApis.emit("crypto.verification.start", request.verifier);
-        }
+        await request.channel.handleEvent(event, request, isLiveEvent);
    } catch (err) {
-        console.error("error while handling verification event", event, err);
+        logger.error("error while handling verification event: " + err.message);
    }
-    if (!request.pending) {
-        requestsByTxnId.delete(transactionId);
-        if (requestsByTxnId.size === 0) {
-            requestsMap.delete(sender);
-        }
-    } else if (isNewRequest && !request.initiatedByMe) {
+    const shouldEmit = isNewRequest &&
+                       !request.initiatedByMe &&
+                       !request.invalid && // check it has enough events to pass the UNSENT stage
+                       !request.observeOnly;
+    if (shouldEmit) {
        this._baseApis.emit("crypto.verification.request", request);
    }
 };
@@ -2669,15 +2765,21 @@ Crypto.prototype._onToDeviceBadEncrypted = async function(event) {
    // on a current session.
    // Note that an undecryptable message from another device could easily be spoofed -
    // is there anything we can do to mitigate this?
-    const device = this._deviceList.getDeviceByIdentityKey(algorithm, deviceKey);
+    let device = this._deviceList.getDeviceByIdentityKey(algorithm, deviceKey);
    if (!device) {
-        logger.info(
-            "Couldn't find device for identity key " + deviceKey +
-            ": not re-establishing session",
-        );
-        await this._olmDevice.recordSessionProblem(deviceKey, "wedged", false);
-        retryDecryption();
-        return;
+        // if we don't know about the device, fetch the user's devices again
+        // and retry before giving up
+        await this.downloadKeys([sender], false);
+        device = this._deviceList.getDeviceByIdentityKey(algorithm, deviceKey);
+        if (!device) {
+            logger.info(
+                "Couldn't find device for identity key " + deviceKey +
+                    ": not re-establishing session",
+            );
+            await this._olmDevice.recordSessionProblem(deviceKey, "wedged", false);
+            retryDecryption();
+            return;
+        }
    }
    const devicesByUser = {};
    devicesByUser[sender] = [device];
@@ -2904,9 +3006,8 @@ Crypto.prototype._processReceivedRoomKeyRequest = async function(req) {
        decryptor.shareKeysWithDevice(req);
    };

-    // if the device is is verified already, share the keys
-    const device = this._deviceList.getStoredDevice(userId, deviceId);
-    if (device && device.isVerified()) {
+    // if the device is verified already, share the keys
+    if (this.checkDeviceTrust(userId, deviceId).isVerified()) {
        logger.log('device is already verified: sharing keys');
        req.share();
        return;
@@ -113,6 +113,57 @@ export async function encryptMessageForDevice(
    );
 }

+/**
+ * Get the existing olm sessions for the given devices, and the devices that
+ * don't have olm sessions.
+ *
+ * @param {module:crypto/OlmDevice} olmDevice
+ *
+ * @param {module:base-apis~MatrixBaseApis} baseApis
+ *
+ * @param {object<string, module:crypto/deviceinfo[]>} devicesByUser
+ *    map from userid to list of devices to ensure sessions for
+ *
+ * @return {Promise} resolves to an array.  The first element of the array is a
+ *    a map of user IDs to arrays of deviceInfo, representing the devices that
+ *    don't have established olm sessions.  The second element of the array is
+ *    a map from userId to deviceId to {@link module:crypto~OlmSessionResult}
+ */
+export async function getExistingOlmSessions(
+    olmDevice, baseApis, devicesByUser,
+) {
+    const devicesWithoutSession = {};
+    const sessions = {};
+
+    const promises = [];
+
+    for (const [userId, devices] of Object.entries(devicesByUser)) {
+        for (const deviceInfo of devices) {
+            const deviceId = deviceInfo.deviceId;
+            const key = deviceInfo.getIdentityKey();
+            promises.push((async () => {
+                const sessionId = await olmDevice.getSessionIdForDevice(
+                    key, true,
+                );
+                if (sessionId === null) {
+                    devicesWithoutSession[userId] = devicesWithoutSession[userId] || [];
+                    devicesWithoutSession[userId].push(deviceInfo);
+                } else {
+                    sessions[userId] = sessions[userId] || {};
+                    sessions[userId][deviceId] = {
+                        device: deviceInfo,
+                        sessionId: sessionId,
+                    };
+                }
+            })());
+        }
+    }
+
+    await Promise.all(promises);
+
+    return [devicesWithoutSession, sessions];
+}
+
 /**
 * Try to make sure we have established olm sessions for the given devices.
 *
@@ -123,30 +174,33 @@ export async function encryptMessageForDevice(
 * @param {object<string, module:crypto/deviceinfo[]>} devicesByUser
 *    map from userid to list of devices to ensure sessions for
 *
- * @param {bolean} force If true, establish a new session even if one already exists.
- *     Optional.
+ * @param {boolean} [force=false] If true, establish a new session even if one
+ *     already exists.
 *
- * @return {module:client.Promise} resolves once the sessions are complete, to
+ * @param {Number} [otkTimeout] The timeout in milliseconds when requesting
+ *     one-time keys for establishing new olm sessions.
+ *
+ * @return {Promise} resolves once the sessions are complete, to
 *    an Object mapping from userId to deviceId to
 *    {@link module:crypto~OlmSessionResult}
 */
 export async function ensureOlmSessionsForDevices(
-    olmDevice, baseApis, devicesByUser, force,
+    olmDevice, baseApis, devicesByUser, force, otkTimeout,
 ) {
+    if (typeof force === "number") {
+        otkTimeout = force;
+        force = false;
+    }
+
    const devicesWithoutSession = [
        // [userId, deviceId], ...
    ];
    const result = {};
    const resolveSession = {};

-    for (const userId in devicesByUser) {
-        if (!devicesByUser.hasOwnProperty(userId)) {
-            continue;
-        }
+    for (const [userId, devices] of Object.entries(devicesByUser)) {
        result[userId] = {};
-        const devices = devicesByUser[userId];
-        for (let j = 0; j < devices.length; j++) {
-            const deviceInfo = devices[j];
+        for (const deviceInfo of devices) {
            const deviceId = deviceInfo.deviceId;
            const key = deviceInfo.getIdentityKey();
            if (!olmDevice._sessionsInProgress[key]) {
@@ -197,7 +251,7 @@ export async function ensureOlmSessionsForDevices(
    let res;
    try {
        res = await baseApis.claimOneTimeKeys(
-            devicesWithoutSession, oneTimeKeyAlgorithm,
+            devicesWithoutSession, oneTimeKeyAlgorithm, otkTimeout,
        );
    } catch (e) {
        for (const resolver of Object.values(resolveSession)) {
@@ -209,12 +263,8 @@ export async function ensureOlmSessionsForDevices(

    const otk_res = res.one_time_keys || {};
    const promises = [];
-    for (const userId in devicesByUser) {
-        if (!devicesByUser.hasOwnProperty(userId)) {
-            continue;
-        }
+    for (const [userId, devices] of Object.entries(devicesByUser)) {
        const userRes = otk_res[userId] || {};
-        const devices = devicesByUser[userId];
        for (let j = 0; j < devices.length; j++) {
            const deviceInfo = devices[j];
            const deviceId = deviceInfo.deviceId;
@@ -407,6 +457,15 @@ export function encodeBase64(uint8Array) {
    return Buffer.from(uint8Array).toString("base64");
 }

+/**
+ * Encode a typed array of uint8 as unpadded base64.
+ * @param {Uint8Array} uint8Array The data to encode.
+ * @return {string} The unpadded base64.
+ */
+export function encodeUnpaddedBase64(uint8Array) {
+    return encodeBase64(uint8Array).replace(/=+$/g, '');
+}
+
 /**
 * Decode a base64 string to a typed array of uint8.
 * @param {string} base64 The base64 to decode.
@@ -341,18 +341,39 @@ export class Backend {
        };
    }

+    getCrossSigningPrivateKey(txn, func, type) {
+        const objectStore = txn.objectStore("account");
+        const getReq = objectStore.get(`ssss_cache:${type}`);
+        getReq.onsuccess = function() {
+            try {
+                func(getReq.result || null);
+            } catch (e) {
+                abortWithException(txn, e);
+            }
+        };
+    }
+
    storeCrossSigningKeys(txn, keys) {
        const objectStore = txn.objectStore("account");
        objectStore.put(keys, "crossSigningKeys");
    }

+    storeCrossSigningPrivateKey(txn, type, key) {
+        const objectStore = txn.objectStore("account");
+        objectStore.put(key, `ssss_cache:${type}`);
+    }
+
    // Olm Sessions

    countEndToEndSessions(txn, func) {
        const objectStore = txn.objectStore("sessions");
        const countReq = objectStore.count();
        countReq.onsuccess = function() {
-            func(countReq.result);
+            try {
+                func(countReq.result);
+            } catch (e) {
+                abortWithException(txn, e);
+            }
        };
    }

@@ -402,16 +423,16 @@ export class Backend {
        const objectStore = txn.objectStore("sessions");
        const getReq = objectStore.openCursor();
        getReq.onsuccess = function() {
-            const cursor = getReq.result;
-            if (cursor) {
-                func(cursor.value);
-                cursor.continue();
-            } else {
-                try {
+            try {
+                const cursor = getReq.result;
+                if (cursor) {
+                    func(cursor.value);
+                    cursor.continue();
+                } else {
                    func(null);
-                } catch (e) {
-                    abortWithException(txn, e);
                }
+            } catch (e) {
+                abortWithException(txn, e);
            }
        };
    }
@@ -46,6 +46,7 @@ export class IndexedDBCryptoStore {
        this._indexedDB = indexedDB;
        this._dbName = dbName;
        this._backendPromise = null;
+        this._backend = null;
    }

    static exists(indexedDB, dbName) {
@@ -56,10 +57,12 @@ export class IndexedDBCryptoStore {
     * Ensure the database exists and is up-to-date, or fall back to
     * a local storage or in-memory store.
     *
+     * This must be called before the store can be used.
+     *
     * @return {Promise} resolves to either an IndexedDBCryptoStoreBackend.Backend,
     * or a MemoryCryptoStore
     */
-    _connect() {
+    startup() {
        if (this._backendPromise) {
            return this._backendPromise;
        }
@@ -135,6 +138,8 @@ export class IndexedDBCryptoStore {
                );
                return new MemoryCryptoStore();
            }
+        }).then(backend => {
+            this._backend = backend;
        });

        return this._backendPromise;
@@ -189,9 +194,7 @@ export class IndexedDBCryptoStore {
     *    same instance as passed in, or the existing one.
     */
    getOrAddOutgoingRoomKeyRequest(request) {
-        return this._connect().then((backend) => {
-            return backend.getOrAddOutgoingRoomKeyRequest(request);
-        });
+        return this._backend.getOrAddOutgoingRoomKeyRequest(request);
    }

    /**
@@ -205,9 +208,7 @@ export class IndexedDBCryptoStore {
     *    not found
     */
    getOutgoingRoomKeyRequest(requestBody) {
-        return this._connect().then((backend) => {
-            return backend.getOutgoingRoomKeyRequest(requestBody);
-        });
+        return this._backend.getOutgoingRoomKeyRequest(requestBody);
    }

    /**
@@ -221,9 +222,7 @@ export class IndexedDBCryptoStore {
     *    requests in those states, an arbitrary one is chosen.
     */
    getOutgoingRoomKeyRequestByState(wantedStates) {
-        return this._connect().then((backend) => {
-            return backend.getOutgoingRoomKeyRequestByState(wantedStates);
-        });
+        return this._backend.getOutgoingRoomKeyRequestByState(wantedStates);
    }

    /**
@@ -237,11 +236,9 @@ export class IndexedDBCryptoStore {
     *    {@link module:crypto/store/base~OutgoingRoomKeyRequest}
     */
    getOutgoingRoomKeyRequestsByTarget(userId, deviceId, wantedStates) {
-        return this._connect().then((backend) => {
-            return backend.getOutgoingRoomKeyRequestsByTarget(
-                userId, deviceId, wantedStates,
-            );
-        });
+        return this._backend.getOutgoingRoomKeyRequestsByTarget(
+            userId, deviceId, wantedStates,
+        );
    }

    /**
@@ -257,11 +254,9 @@ export class IndexedDBCryptoStore {
     *    updated request, or null if no matching row was found
     */
    updateOutgoingRoomKeyRequest(requestId, expectedState, updates) {
-        return this._connect().then((backend) => {
-            return backend.updateOutgoingRoomKeyRequest(
-                requestId, expectedState, updates,
-            );
-        });
+        return this._backend.updateOutgoingRoomKeyRequest(
+            requestId, expectedState, updates,
+        );
    }

    /**
@@ -274,9 +269,7 @@ export class IndexedDBCryptoStore {
     * @returns {Promise} resolves once the operation is completed
     */
    deleteOutgoingRoomKeyRequest(requestId, expectedState) {
-        return this._connect().then((backend) => {
-            return backend.deleteOutgoingRoomKeyRequest(requestId, expectedState);
-        });
+        return this._backend.deleteOutgoingRoomKeyRequest(requestId, expectedState);
    }

    // Olm Account
@@ -289,9 +282,7 @@ export class IndexedDBCryptoStore {
     * @param {function(string)} func Called with the account pickle
     */
    getAccount(txn, func) {
-        this._backendPromise.then(backend => {
-            backend.getAccount(txn, func);
-        });
+        this._backend.getAccount(txn, func);
    }

    /**
@@ -302,9 +293,7 @@ export class IndexedDBCryptoStore {
     * @param {string} newData The new account pickle to store.
     */
    storeAccount(txn, newData) {
-        this._backendPromise.then(backend => {
-            backend.storeAccount(txn, newData);
-        });
+        this._backend.storeAccount(txn, newData);
    }

    /**
@@ -316,9 +305,16 @@ export class IndexedDBCryptoStore {
     *        { key_type: base64 encoded seed } where key type = user_signing_key_seed or self_signing_key_seed
     */
    getCrossSigningKeys(txn, func) {
-        this._backendPromise.then(backend => {
-            backend.getCrossSigningKeys(txn, func);
-        });
+        this._backend.getCrossSigningKeys(txn, func);
+    }
+
+    /**
+     * @param {*} txn An active transaction. See doTxn().
+     * @param {function(string)} func Called with the private key
+     * @param {string} type A key type
+     */
+    getCrossSigningPrivateKey(txn, func, type) {
+        this._backend.getCrossSigningPrivateKey(txn, func, type);
    }

    /**
@@ -328,9 +324,18 @@ export class IndexedDBCryptoStore {
     * @param {string} keys keys object as getCrossSigningKeys()
     */
    storeCrossSigningKeys(txn, keys) {
-        this._backendPromise.then(backend => {
-            backend.storeCrossSigningKeys(txn, keys);
-        });
+        this._backend.storeCrossSigningKeys(txn, keys);
+    }
+
+    /**
+     * Write the cross-signing private keys back to the store
+     *
+     * @param {*} txn An active transaction. See doTxn().
+     * @param {string} type The type of cross-signing private key to store
+     * @param {string} key keys object as getCrossSigningKeys()
+     */
+    storeCrossSigningPrivateKey(txn, type, key) {
+        this._backend.storeCrossSigningPrivateKey(txn, type, key);
    }

    // Olm sessions
@@ -341,9 +346,7 @@ export class IndexedDBCryptoStore {
     * @param {function(int)} func Called with the count of sessions
     */
    countEndToEndSessions(txn, func) {
-        this._backendPromise.then(backend => {
-            backend.countEndToEndSessions(txn, func);
-        });
+        this._backend.countEndToEndSessions(txn, func);
    }

    /**
@@ -359,9 +362,7 @@ export class IndexedDBCryptoStore {
     *     a message.
     */
    getEndToEndSession(deviceKey, sessionId, txn, func) {
-        this._backendPromise.then(backend => {
-            backend.getEndToEndSession(deviceKey, sessionId, txn, func);
-        });
+        this._backend.getEndToEndSession(deviceKey, sessionId, txn, func);
    }

    /**
@@ -376,9 +377,7 @@ export class IndexedDBCryptoStore {
     *     a message.
     */
    getEndToEndSessions(deviceKey, txn, func) {
-        this._backendPromise.then(backend => {
-            backend.getEndToEndSessions(deviceKey, txn, func);
-        });
+        this._backend.getEndToEndSessions(deviceKey, txn, func);
    }

    /**
@@ -389,9 +388,7 @@ export class IndexedDBCryptoStore {
     *     and session keys.
     */
    getAllEndToEndSessions(txn, func) {
-        this._backendPromise.then(backend => {
-            backend.getAllEndToEndSessions(txn, func);
-        });
+        this._backend.getAllEndToEndSessions(txn, func);
    }

    /**
@@ -402,29 +399,21 @@ export class IndexedDBCryptoStore {
     * @param {*} txn An active transaction. See doTxn().
     */
    storeEndToEndSession(deviceKey, sessionId, sessionInfo, txn) {
-        this._backendPromise.then(backend => {
-            backend.storeEndToEndSession(
-                deviceKey, sessionId, sessionInfo, txn,
-            );
-        });
+        this._backend.storeEndToEndSession(
+            deviceKey, sessionId, sessionInfo, txn,
+        );
    }

    storeEndToEndSessionProblem(deviceKey, type, fixed) {
-        return this._backendPromise.then(async (backend) => {
-            await backend.storeEndToEndSessionProblem(deviceKey, type, fixed);
-        });
+        return this._backend.storeEndToEndSessionProblem(deviceKey, type, fixed);
    }

    getEndToEndSessionProblem(deviceKey, timestamp) {
-        return this._backendPromise.then(async (backend) => {
-            return await backend.getEndToEndSessionProblem(deviceKey, timestamp);
-        });
+        return this._backend.getEndToEndSessionProblem(deviceKey, timestamp);
    }

    filterOutNotifiedErrorDevices(devices) {
-        return this._backendPromise.then(async (backend) => {
-            return await backend.filterOutNotifiedErrorDevices(devices);
-        });
+        return this._backend.filterOutNotifiedErrorDevices(devices);
    }

    // Inbound group sessions
@@ -439,11 +428,9 @@ export class IndexedDBCryptoStore {
     *     to Base64 end-to-end session.
     */
    getEndToEndInboundGroupSession(senderCurve25519Key, sessionId, txn, func) {
-        this._backendPromise.then(backend => {
-            backend.getEndToEndInboundGroupSession(
-                senderCurve25519Key, sessionId, txn, func,
-            );
-        });
+        this._backend.getEndToEndInboundGroupSession(
+            senderCurve25519Key, sessionId, txn, func,
+        );
    }

    /**
@@ -454,9 +441,7 @@ export class IndexedDBCryptoStore {
     *     sessionData}, then once with null to indicate the end of the list.
     */
    getAllEndToEndInboundGroupSessions(txn, func) {
-        this._backendPromise.then(backend => {
-            backend.getAllEndToEndInboundGroupSessions(txn, func);
-        });
+        this._backend.getAllEndToEndInboundGroupSessions(txn, func);
    }

    /**
@@ -469,11 +454,9 @@ export class IndexedDBCryptoStore {
     * @param {*} txn An active transaction. See doTxn().
     */
    addEndToEndInboundGroupSession(senderCurve25519Key, sessionId, sessionData, txn) {
-        this._backendPromise.then(backend => {
-            backend.addEndToEndInboundGroupSession(
-                senderCurve25519Key, sessionId, sessionData, txn,
-            );
-        });
+        this._backend.addEndToEndInboundGroupSession(
+            senderCurve25519Key, sessionId, sessionData, txn,
+        );
    }

    /**
@@ -486,21 +469,17 @@ export class IndexedDBCryptoStore {
     * @param {*} txn An active transaction. See doTxn().
     */
    storeEndToEndInboundGroupSession(senderCurve25519Key, sessionId, sessionData, txn) {
-        this._backendPromise.then(backend => {
-            backend.storeEndToEndInboundGroupSession(
-                senderCurve25519Key, sessionId, sessionData, txn,
-            );
-        });
+        this._backend.storeEndToEndInboundGroupSession(
+            senderCurve25519Key, sessionId, sessionData, txn,
+        );
    }

    storeEndToEndInboundGroupSessionWithheld(
        senderCurve25519Key, sessionId, sessionData, txn,
    ) {
-        this._backendPromise.then(backend => {
-            backend.storeEndToEndInboundGroupSessionWithheld(
-                senderCurve25519Key, sessionId, sessionData, txn,
-            );
-        });
+        this._backend.storeEndToEndInboundGroupSessionWithheld(
+            senderCurve25519Key, sessionId, sessionData, txn,
+        );
    }

    // End-to-end device tracking
@@ -516,9 +495,7 @@ export class IndexedDBCryptoStore {
     * @param {*} txn An active transaction. See doTxn().
     */
    storeEndToEndDeviceData(deviceData, txn) {
-        this._backendPromise.then(backend => {
-            backend.storeEndToEndDeviceData(deviceData, txn);
-        });
+        this._backend.storeEndToEndDeviceData(deviceData, txn);
    }

    /**
@@ -529,9 +506,7 @@ export class IndexedDBCryptoStore {
     *     device data
     */
    getEndToEndDeviceData(txn, func) {
-        this._backendPromise.then(backend => {
-            backend.getEndToEndDeviceData(txn, func);
-        });
+        this._backend.getEndToEndDeviceData(txn, func);
    }

    // End to End Rooms
@@ -543,9 +518,7 @@ export class IndexedDBCryptoStore {
     * @param {*} txn An active transaction. See doTxn().
     */
    storeEndToEndRoom(roomId, roomInfo, txn) {
-        this._backendPromise.then(backend => {
-            backend.storeEndToEndRoom(roomId, roomInfo, txn);
-        });
+        this._backend.storeEndToEndRoom(roomId, roomInfo, txn);
    }

    /**
@@ -554,9 +527,7 @@ export class IndexedDBCryptoStore {
     * @param {function(Object)} func Function called with the end to end encrypted rooms
     */
    getEndToEndRooms(txn, func) {
-        this._backendPromise.then(backend => {
-            backend.getEndToEndRooms(txn, func);
-        });
+        this._backend.getEndToEndRooms(txn, func);
    }

    // session backups
@@ -568,9 +539,7 @@ export class IndexedDBCryptoStore {
     * @returns {Promise} resolves to an array of inbound group sessions
     */
    getSessionsNeedingBackup(limit) {
-        return this._connect().then((backend) => {
-            return backend.getSessionsNeedingBackup(limit);
-        });
+        return this._backend.getSessionsNeedingBackup(limit);
    }

    /**
@@ -579,9 +548,7 @@ export class IndexedDBCryptoStore {
     * @returns {Promise} resolves to the number of sessions
     */
    countSessionsNeedingBackup(txn) {
-        return this._connect().then((backend) => {
-            return backend.countSessionsNeedingBackup(txn);
-        });
+        return this._backend.countSessionsNeedingBackup(txn);
    }

    /**
@@ -591,9 +558,7 @@ export class IndexedDBCryptoStore {
     * @returns {Promise} resolves when the sessions are unmarked
     */
    unmarkSessionsNeedingBackup(sessions, txn) {
-        return this._connect().then((backend) => {
-            return backend.unmarkSessionsNeedingBackup(sessions, txn);
-        });
+        return this._backend.unmarkSessionsNeedingBackup(sessions, txn);
    }

    /**
@@ -603,9 +568,7 @@ export class IndexedDBCryptoStore {
     * @returns {Promise} resolves when the sessions are marked
     */
    markSessionsNeedingBackup(sessions, txn) {
-        return this._connect().then((backend) => {
-            return backend.markSessionsNeedingBackup(sessions, txn);
-        });
+        return this._backend.markSessionsNeedingBackup(sessions, txn);
    }

    /**
@@ -630,9 +593,7 @@ export class IndexedDBCryptoStore {
     *     exception will propagate to the caller of the getFoo method.
     */
    doTxn(mode, stores, func) {
-        return this._connect().then((backend) => {
-            return backend.doTxn(mode, stores, func);
-        });
+        return this._backend.doTxn(mode, stores, func);
    }
 }

@@ -367,12 +367,23 @@ export class LocalStorageCryptoStore extends MemoryCryptoStore {
        func(keys);
    }

+    getCrossSigningPrivateKey(txn, func, type) {
+        const key = getJsonItem(this.store, E2E_PREFIX + `ssss_cache.${type}`);
+        func(key ? Uint8Array.from(key) : key);
+    }
+
    storeCrossSigningKeys(txn, keys) {
        setJsonItem(
            this.store, KEY_CROSS_SIGNING_KEYS, keys,
        );
    }

+    storeCrossSigningPrivateKey(txn, type, key) {
+        setJsonItem(
+            this.store, E2E_PREFIX + `ssss_cache.${type}`, Array.from(key),
+        );
+    }
+
    doTxn(mode, stores, func) {
        return Promise.resolve(func(null));
    }
@@ -33,6 +33,7 @@ export class MemoryCryptoStore {
        this._outgoingRoomKeyRequests = [];
        this._account = null;
        this._crossSigningKeys = null;
+        this._privateKeys = {};

        // Map of {devicekey -> {sessionId -> session pickle}}
        this._sessions = {};
@@ -51,6 +52,18 @@ export class MemoryCryptoStore {
        this._sessionsNeedingBackup = {};
    }

+    /**
+     * Ensure the database exists and is up-to-date.
+     *
+     * This must be called before the store can be used.
+     *
+     * @return {Promise} resolves to the store.
+     */
+    async startup() {
+        // No startup work to do for the memory store.
+        return this;
+    }
+
    /**
     * Delete all data from this store.
     *
@@ -243,10 +256,19 @@ export class MemoryCryptoStore {
        func(this._crossSigningKeys);
    }

+    getCrossSigningPrivateKey(txn, func, type) {
+        const result = this._privateKeys[type];
+        return func(result || null);
+    }
+
    storeCrossSigningKeys(txn, keys) {
        this._crossSigningKeys = keys;
    }

+    storeCrossSigningPrivateKey(txn, type, key) {
+        this._privateKeys[type] = key;
+    }
+
    // Olm Sessions

    countEndToEndSessions(txn, func) {
@@ -263,11 +285,15 @@ export class MemoryCryptoStore {
    }

    getAllEndToEndSessions(txn, func) {
-        for (const deviceSessions of Object.values(this._sessions)) {
-            for (const sess of Object.values(deviceSessions)) {
-                func(sess);
-            }
-        }
+        Object.entries(this._sessions).forEach(([deviceKey, deviceSessions]) => {
+            Object.entries(deviceSessions).forEach(([sessionId, session]) => {
+                func({
+                    ...session,
+                    deviceKey,
+                    sessionId,
+                });
+            });
+        });
    }

    storeEndToEndSession(deviceKey, sessionId, sessionInfo, txn) {
@@ -24,9 +24,18 @@ import {EventEmitter} from 'events';
 import {logger} from '../../logger';
 import {DeviceInfo} from '../deviceinfo';
 import {newTimeoutError} from "./Error";
+import {CrossSigningInfo} from "../CrossSigning";
+import {decodeBase64} from "../olmlib";

 const timeoutException = new Error("Verification timed out");

+export class SwitchStartEventError extends Error {
+    constructor(startEvent) {
+        super();
+        this.startEvent = startEvent;
+    }
+}
+
 export class VerificationBase extends EventEmitter {
    /**
     * Base class for verification methods.
@@ -67,9 +76,21 @@ export class VerificationBase extends EventEmitter {
        this._done = false;
        this._promise = null;
        this._transactionTimeoutTimer = null;
+    }

-        // At this point, the verification request was received so start the timeout timer.
-        this._resetTimer();
+    static keyRequestTimeoutMs = 1000 * 60;
+
+    get initiatedByMe() {
+        // if there is no start event yet,
+        // we probably want to send it,
+        // which happens if we initiate
+        if (!this.startEvent) {
+            return true;
+        }
+        const sender = this.startEvent.getSender();
+        const content = this.startEvent.getContent();
+        return sender === this._baseApis.getUserId() &&
+            content.from_device === this._baseApis.getDeviceId();
    }

    _resetTimer() {
@@ -107,6 +128,24 @@ export class VerificationBase extends EventEmitter {
        });
    }

+    canSwitchStartEvent() {
+        return false;
+    }
+
+    switchStartEvent(event) {
+        if (this.canSwitchStartEvent(event)) {
+            logger.log("Verification Base: switching verification start event",
+                {restartingFlow: !!this._rejectEvent});
+            if (this._rejectEvent) {
+                const reject = this._rejectEvent;
+                this._rejectEvent = undefined;
+                reject(new SwitchStartEventError(event));
+            } else {
+                this.startEvent = event;
+            }
+        }
+    }
+
    handleEvent(e) {
        if (this._done) {
            return;
@@ -122,8 +161,18 @@ export class VerificationBase extends EventEmitter {
        } else if (e.getType() === "m.key.verification.cancel") {
            const reject = this._reject;
            this._reject = undefined;
-            reject(new Error("Other side cancelled verification"));
-        } else {
+            // there is only promise to reject if verify has been called
+            if (reject) {
+                const content = e.getContent();
+                const {reason, code} = content;
+                reject(new Error(`Other side cancelled verification ` +
+                    `because ${reason} (${code})`));
+            }
+        } else if (this._expectedEvent) {
+            // only cancel if there is an event expected.
+            // if there is no event expected, it means verify() wasn't called
+            // and we're just replaying the timeline events when syncing
+            // after a refresh when the events haven't been stored in the cache yet.
            const exception = new Error(
                "Unexpected message: expecting " + this._expectedEvent
                    + " but got " + e.getType(),
@@ -141,11 +190,65 @@ export class VerificationBase extends EventEmitter {
    done() {
        this._endTimer(); // always kill the activity timer
        if (!this._done) {
-            if (this._channel.needsDoneMessage) {
-                // verification in DM requires a done message
-                this._send("m.key.verification.done", {});
-            }
+            this.request.onVerifierFinished();
            this._resolve();
+
+            //#region Cross-signing keys request
+            // If this is a self-verification, ask the other party for keys
+            if (this._baseApis.getUserId() !== this.userId) {
+                return;
+            }
+            console.log("VerificationBase.done: Self-verification done; requesting keys");
+            /* This happens asynchronously, and we're not concerned about
+             * waiting for it.  We return here in order to test. */
+            return new Promise((resolve, reject) => {
+                const client = this._baseApis;
+                const original = client._crypto._crossSigningInfo;
+                const storage = client._crypto._secretStorage;
+
+                /* We already have all of the infrastructure we need to validate and
+                 * cache cross-signing keys, so instead of replicating that, here we
+                 * set up callbacks that request them from the other device and call
+                 * CrossSigningInfo.getCrossSigningKey() to validate/cache */
+                const crossSigning = new CrossSigningInfo(
+                    original.userId,
+                    { getCrossSigningKey: async (type) => {
+                        console.debug("VerificationBase.done: requesting secret",
+                                      type, this.deviceId);
+                        const { promise } =
+                            storage.request(`m.cross_signing.${type}`, [this.deviceId]);
+                        const result = await promise;
+                        const decoded = decodeBase64(result);
+                        return Uint8Array.from(decoded);
+                    } },
+                    original._cacheCallbacks,
+                );
+                crossSigning.keys = original.keys;
+
+                // XXX: get all keys out if we get one key out
+                // https://github.com/vector-im/riot-web/issues/12604
+                // then change here to reject on the timeout
+                /* Requests can be ignored, so don't wait around forever */
+                const timeout = new Promise((resolve, reject) => {
+                    setTimeout(
+                        resolve,
+                        VerificationBase.keyRequestTimeoutMs,
+                        new Error("Timeout"),
+                    );
+                });
+
+                /* We call getCrossSigningKey() for its side-effects */
+                return Promise.race([
+                    Promise.all([
+                        crossSigning.getCrossSigningKey("self_signing"),
+                        crossSigning.getCrossSigningKey("user_signing"),
+                    ]),
+                    timeout,
+                ]).then(resolve, reject);
+            }).catch((e) => {
+                console.warn("VerificationBase: failure while requesting keys:", e);
+            });
+            //#endregion
        }
    }

@@ -263,6 +366,13 @@ export class VerificationBase extends EventEmitter {
            throw new Error("No devices could be verified");
        }

+        logger.info(
+            "Verification completed! Marking devices verified: ",
+            verifiedDevices,
+        );
+        // TODO: There should probably be a batch version of this, otherwise it's going
+        // to upload each signature in a separate API call which is silly because the
+        // API supports as many signatures as you like.
        for (const deviceId of verifiedDevices) {
            await this._baseApis.setDeviceVerified(userId, deviceId);
        }
@@ -23,12 +23,10 @@ limitations under the License.
 import {MatrixEvent} from "../../models/event";

 export function newVerificationError(code, reason, extradata) {
-    extradata = extradata || {};
-    extradata.code = code;
-    extradata.reason = reason;
+    const content = Object.assign({}, {code, reason}, extradata);
    return new MatrixEvent({
        type: "m.key.verification.cancel",
-        content: extradata,
+        content,
    });
 }

@@ -0,0 +1,43 @@
+/*
+Copyright 2020 The Matrix.org Foundation C.I.C.
+
+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.
+*/
+
+/**
+ * Verification method that is illegal to have (cannot possibly
+ * do verification with this method).
+ * @module crypto/verification/IllegalMethod
+ */
+
+import {VerificationBase as Base} from "./Base";
+
+/**
+ * @class crypto/verification/IllegalMethod/IllegalMethod
+ * @extends {module:crypto/verification/Base}
+ */
+export class IllegalMethod extends Base {
+    static factory(...args) {
+        return new IllegalMethod(...args);
+    }
+
+    static get NAME() {
+        // Typically the name will be something else, but to complete
+        // the contract we offer a default one here.
+        return "org.matrix.illegal_method";
+    }
+
+    async _doVerification() {
+        throw new Error("Verification is not possible with this method");
+    }
+}
@@ -1,5 +1,6 @@
 /*
 Copyright 2018 New Vector Ltd
+Copyright 2020 The Matrix.org Foundation C.I.C.

 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -21,103 +22,92 @@ limitations under the License.

 import {VerificationBase as Base} from "./Base";
 import {
-    errorFactory,
    newKeyMismatchError,
-    newUserCancelledError,
    newUserMismatchError,
 } from './Error';

-const MATRIXTO_REGEXP = /^(?:https?:\/\/)?(?:www\.)?matrix\.to\/#\/([#@!+][^?]+)\?(.+)$/;
-const KEY_REGEXP = /^key_([^:]+:.+)$/;
-
-const newQRCodeError = errorFactory("m.qr_code.invalid", "Invalid QR code");
+export const SHOW_QR_CODE_METHOD = "m.qr_code.show.v1";
+export const SCAN_QR_CODE_METHOD = "m.qr_code.scan.v1";

 /**
- * @class crypto/verification/QRCode/ShowQRCode
+ * @class crypto/verification/QRCode/ReciprocateQRCode
 * @extends {module:crypto/verification/Base}
 */
-export class ShowQRCode extends Base {
-    _doVerification() {
-        if (!this._done) {
-            const url = "https://matrix.to/#/" + this._baseApis.getUserId()
-                  + "?device=" + encodeURIComponent(this._baseApis.deviceId)
-                  + "&action=verify&key_ed25519%3A"
-                  + encodeURIComponent(this._baseApis.deviceId) + "="
-                  + encodeURIComponent(this._baseApis.getDeviceEd25519Key());
-            this.emit("show_qr_code", {
-                url: url,
-            });
-        }
-    }
-}
-
-ShowQRCode.NAME = "m.qr_code.show.v1";
-
-/**
- * @class crypto/verification/QRCode/ScanQRCode
- * @extends {module:crypto/verification/Base}
- */
-export class ScanQRCode extends Base {
+export class ReciprocateQRCode extends Base {
    static factory(...args) {
-        return new ScanQRCode(...args);
+        return new ReciprocateQRCode(...args);
+    }
+
+    static get NAME() {
+        return "m.reciprocate.v1";
    }

    async _doVerification() {
-        const code = await new Promise((resolve, reject) => {
-            this.emit("scan", {
-                done: resolve,
-                cancel: () => reject(newUserCancelledError()),
-            });
-        });
-
-        const match = code.match(MATRIXTO_REGEXP);
-        let deviceId;
-        const keys = {};
-        if (!match) {
-            throw newQRCodeError();
-        }
-        const userId = match[1];
-        const params = match[2].split("&").map(
-            (x) => x.split("=", 2).map(decodeURIComponent),
-        );
-        let action;
-        for (const [name, value] of params) {
-            if (name === "device") {
-                deviceId = value;
-            } else if (name === "action") {
-                action = value;
-            } else {
-                const keyMatch = name.match(KEY_REGEXP);
-                if (keyMatch) {
-                    keys[keyMatch[1]] = value;
-                }
-            }
-        }
-        if (!deviceId || action !== "verify" || Object.keys(keys).length === 0) {
-            throw newQRCodeError();
+        if (!this.startEvent) {
+            // TODO: Support scanning QR codes
+            throw new Error("It is not currently possible to start verification" +
+                "with this method yet.");
        }

+        const targetUserId = this.startEvent.getSender();
        if (!this.userId) {
-            await new Promise((resolve, reject) => {
+            console.log("Asking to confirm user ID");
+            this.userId = await new Promise((resolve, reject) => {
                this.emit("confirm_user_id", {
-                    userId: userId,
-                    confirm: resolve,
+                    userId: targetUserId,
+                    confirm: resolve, // takes a userId
                    cancel: () => reject(newUserMismatchError()),
                });
            });
-        } else if (this.userId !== userId) {
+        } else if (targetUserId !== this.userId) {
            throw newUserMismatchError({
                expected: this.userId,
-                actual: userId,
+                actual: targetUserId,
            });
        }

-        await this._verifyKeys(userId, keys, (keyId, device, key) => {
-            if (device.keys[keyId] !== key) {
+        if (this.startEvent.getContent()['secret'] !== this.request.encodedSharedSecret) {
+            throw newKeyMismatchError();
+        }
+
+        // If we've gotten this far, verify the user's master cross signing key
+        const xsignInfo = this._baseApis.getStoredCrossSigningForUser(this.userId);
+        if (!xsignInfo) throw new Error("Missing cross signing info");
+
+        const masterKey = xsignInfo.getId("master");
+        const masterKeyId = `ed25519:${masterKey}`;
+        const keys = {[masterKeyId]: masterKey};
+
+        const devices = (await this._baseApis.getStoredDevicesForUser(this.userId)) || [];
+        const targetDevice = devices.find(d => {
+            return d.deviceId === this.request.targetDevice.deviceId;
+        });
+        if (!targetDevice) throw new Error("Device not found, somehow");
+        keys[`ed25519:${targetDevice.deviceId}`] = targetDevice.getFingerprint();
+
+        if (this.request.requestingUserId === this.request.receivingUserId) {
+            delete keys[masterKeyId];
+        }
+
+        await this._verifyKeys(this.userId, keys, (keyId, device, keyInfo) => {
+            const targetKey = keys[keyId];
+            if (!targetKey) throw newKeyMismatchError();
+
+            if (keyInfo !== targetKey) {
+                console.error("key ID from key info does not match");
                throw newKeyMismatchError();
            }
+            for (const deviceKeyId in device.keys) {
+                if (!deviceKeyId.startsWith("ed25519")) continue;
+                const deviceTargetKey = keys[deviceKeyId];
+                if (!deviceTargetKey) throw newKeyMismatchError();
+                if (device.keys[deviceKeyId] !== deviceTargetKey) {
+                    console.error("master key does not match");
+                    throw newKeyMismatchError();
+                }
+            }
+
+            // Otherwise it is probably fine
        });
    }
 }
-
-ScanQRCode.NAME = "m.qr_code.scan.v1";
@@ -19,7 +19,7 @@ limitations under the License.
 * @module crypto/verification/SAS
 */

-import {VerificationBase as Base} from "./Base";
+import {VerificationBase as Base, SwitchStartEventError} from "./Base";
 import anotherjson from 'another-json';
 import {
    errorFactory,
@@ -28,6 +28,9 @@ import {
    newUnknownMethodError,
    newUserCancelledError,
 } from './Error';
+import {logger} from '../../logger';
+
+const START_TYPE = "m.key.verification.start";

 const EVENTS = [
    "m.key.verification.accept",
@@ -163,6 +166,15 @@ const macMethods = {
    "hmac-sha256": "calculate_mac_long_kdf",
 };

+function calculateMAC(olmSAS, method) {
+    return function(...args) {
+        const macFunction = olmSAS[macMethods[method]];
+        const mac = macFunction.apply(olmSAS, args);
+        logger.log("SAS calculateMAC:", method, args, mac);
+        return mac;
+    };
+}
+
 /* lists of algorithms/methods that are supported.  The key agreement, hashes,
 * and MAC lists should be sorted in order of preference (most preferred
 * first).
@@ -201,16 +213,37 @@ export class SAS extends Base {
        // make sure user's keys are downloaded
        await this._baseApis.downloadKeys([this.userId]);

-        if (this.startEvent) {
-            return await this._doRespondVerification();
-        } else {
-            return await this._doSendVerification();
-        }
+        let retry = false;
+        do {
+            try {
+                if (this.initiatedByMe) {
+                    return await this._doSendVerification();
+                } else {
+                    return await this._doRespondVerification();
+                }
+            } catch (err) {
+                if (err instanceof SwitchStartEventError) {
+                    // this changes what initiatedByMe returns
+                    this.startEvent = err.startEvent;
+                    retry = true;
+                } else {
+                    throw err;
+                }
+            }
+        } while (retry);
    }

-    async _doSendVerification() {
-        const type = "m.key.verification.start";
-        const initialMessage = this._channel.completeContent(type, {
+    canSwitchStartEvent(event) {
+        if (event.getType() !== START_TYPE) {
+            return false;
+        }
+        const content = event.getContent();
+        return content && content.method === SAS.NAME &&
+            this._waitingForAccept;
+    }
+
+    async _sendStart() {
+        const startContent = this._channel.completeContent(START_TYPE, {
            method: SAS.NAME,
            from_device: this._baseApis.deviceId,
            key_agreement_protocols: KEY_AGREEMENT_LIST,
@@ -219,11 +252,33 @@ export class SAS extends Base {
            // FIXME: allow app to specify what SAS methods can be used
            short_authentication_string: SAS_LIST,
        });
-        // add the transaction id to the message beforehand because
-        // it needs to be included in the commitment hash later on
-        this._channel.sendCompleted(type, initialMessage);
+        await this._channel.sendCompleted(START_TYPE, startContent);
+        return startContent;
+    }

-        let e = await this._waitForEvent("m.key.verification.accept");
+    async _doSendVerification() {
+        this._waitingForAccept = true;
+        let startContent;
+        if (this.startEvent) {
+            startContent = this._channel.completedContentFromEvent(this.startEvent);
+        } else {
+            startContent = await this._sendStart();
+        }
+
+        // we might have switched to a different start event,
+        // but was we didn't call _waitForEvent there was no
+        // call that could throw yet. So check manually that
+        // we're still on the initiator side
+        if (!this.initiatedByMe) {
+            throw new SwitchStartEventError(this.startEvent);
+        }
+
+        let e;
+        try {
+            e = await this._waitForEvent("m.key.verification.accept");
+        } finally {
+            this._waitingForAccept = false;
+        }
        let content = e.getContent();
        const sasMethods
              = intersection(content.short_authentication_string, SAS_SET);
@@ -248,7 +303,7 @@ export class SAS extends Base {
            e = await this._waitForEvent("m.key.verification.key");
            // FIXME: make sure event is properly formed
            content = e.getContent();
-            const commitmentStr = content.key + anotherjson.stringify(initialMessage);
+            const commitmentStr = content.key + anotherjson.stringify(startContent);
            // TODO: use selected hash function (when we support multiple)
            if (olmutil.sha256(commitmentStr) !== hashCommitment) {
                throw newMismatchedCommitmentError();
@@ -261,7 +316,7 @@ export class SAS extends Base {
                  + this._channel.transactionId;
            const sasBytes = olmSAS.generate_bytes(sasInfo, 6);
            const verifySAS = new Promise((resolve, reject) => {
-                this.emit("show_sas", {
+                this.sasEvent = {
                    sas: generateSas(sasBytes, sasMethods),
                    confirm: () => {
                        this._sendMAC(olmSAS, macMethod);
@@ -269,7 +324,8 @@ export class SAS extends Base {
                    },
                    cancel: () => reject(newUserCancelledError()),
                    mismatch: () => reject(newMismatchedSASError()),
-                });
+                };
+                this.emit("show_sas", this.sasEvent);
            });


@@ -345,7 +401,7 @@ export class SAS extends Base {
                  + this._channel.transactionId;
            const sasBytes = olmSAS.generate_bytes(sasInfo, 6);
            const verifySAS = new Promise((resolve, reject) => {
-                this.emit("show_sas", {
+                this.sasEvent = {
                    sas: generateSas(sasBytes, sasMethods),
                    confirm: () => {
                        this._sendMAC(olmSAS, macMethod);
@@ -353,7 +409,8 @@ export class SAS extends Base {
                    },
                    cancel: () => reject(newUserCancelledError()),
                    mismatch: () => reject(newMismatchedSASError()),
-                });
+                };
+                this.emit("show_sas", this.sasEvent);
            });


@@ -384,7 +441,7 @@ export class SAS extends Base {
              + this._channel.transactionId;

        const deviceKeyId = `ed25519:${this._baseApis.deviceId}`;
-        mac[deviceKeyId] = olmSAS[macMethods[method]](
+        mac[deviceKeyId] = calculateMAC(olmSAS, method)(
            this._baseApis.getDeviceEd25519Key(),
            baseInfo + deviceKeyId,
        );
@@ -393,14 +450,14 @@ export class SAS extends Base {
        const crossSigningId = this._baseApis.getCrossSigningId();
        if (crossSigningId) {
            const crossSigningKeyId = `ed25519:${crossSigningId}`;
-            mac[crossSigningKeyId] = olmSAS[macMethods[method]](
+            mac[crossSigningKeyId] = calculateMAC(olmSAS, method)(
                crossSigningId,
                baseInfo + crossSigningKeyId,
            );
            keyList.push(crossSigningKeyId);
        }

-        const keys = olmSAS[macMethods[method]](
+        const keys = calculateMAC(olmSAS, method)(
            keyList.sort().join(","),
            baseInfo + "KEY_IDS",
        );
@@ -413,7 +470,7 @@ export class SAS extends Base {
              + this._baseApis.getUserId() + this._baseApis.deviceId
              + this._channel.transactionId;

-        if (content.keys !== olmSAS[macMethods[method]](
+        if (content.keys !== calculateMAC(olmSAS, method)(
            Object.keys(content.mac).sort().join(","),
            baseInfo + "KEY_IDS",
        )) {
@@ -421,7 +478,7 @@ export class SAS extends Base {
        }

        await this._verifyKeys(this.userId, content.mac, (keyId, device, keyInfo) => {
-            if (keyInfo !== olmSAS[macMethods[method]](
+            if (keyInfo !== calculateMAC(olmSAS, method)(
                device.keys[keyId],
                baseInfo + keyId,
            )) {
@@ -15,7 +15,13 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */

-import {REQUEST_TYPE, START_TYPE, VerificationRequest} from "./VerificationRequest";
+import {
+    VerificationRequest,
+    REQUEST_TYPE,
+    READY_TYPE,
+    START_TYPE,
+} from "./VerificationRequest";
+import {logger} from '../../../logger';

 const MESSAGE_TYPE = "m.room.message";
 const M_REFERENCE = "m.reference";
@@ -31,10 +37,10 @@ export class InRoomChannel {
     * @param {string} roomId id of the room where verification events should be posted in, should be a DM with the given user.
     * @param {string} userId id of user that the verification request is directed at, should be present in the room.
     */
-    constructor(client, roomId, userId) {
+    constructor(client, roomId, userId = null) {
        this._client = client;
        this._roomId = roomId;
-        this._userId = userId;
+        this.userId = userId;
        this._requestEventId = null;
    }

@@ -43,16 +49,41 @@ export class InRoomChannel {
        return true;
    }

+    get receiveStartFromOtherDevices() {
+        return true;
+    }
+
+    get roomId() {
+        return this._roomId;
+    }
+
    /** The transaction id generated/used by this verification channel */
    get transactionId() {
        return this._requestEventId;
    }

+    static getOtherPartyUserId(event, client) {
+        const type = InRoomChannel.getEventType(event);
+        if (type !== REQUEST_TYPE) {
+           return;
+        }
+        const ownUserId = client.getUserId();
+        const sender = event.getSender();
+        const content = event.getContent();
+        const receiver = content.to;
+
+        if (sender === ownUserId) {
+            return receiver;
+        } else if (receiver === ownUserId) {
+            return sender;
+        }
+    }
+
    /**
     * @param {MatrixEvent} event the event to get the timestamp of
     * @return {number} the timestamp when the event was sent
     */
-    static getTimestamp(event) {
+    getTimestamp(event) {
        return event.getTs();
    }

@@ -97,19 +128,26 @@ export class InRoomChannel {
        }
        const type = InRoomChannel.getEventType(event);
        const content = event.getContent();
+
+        // from here on we're fairly sure that this is supposed to be
+        // part of a verification request, so be noisy when rejecting something
        if (type === REQUEST_TYPE) {
-            if (typeof content.to !== "string" || !content.to.length) {
+            if (!content || typeof content.to !== "string" || !content.to.length) {
+                logger.log("InRoomChannel: validateEvent: " +
+                    "no valid to " + (content && content.to));
                return false;
            }
-            const ownUserId = client.getUserId();
+
            // ignore requests that are not direct to or sent by the syncing user
-            if (event.getSender() !== ownUserId && content.to !== ownUserId) {
+            if (!InRoomChannel.getOtherPartyUserId(event, client)) {
+                logger.log("InRoomChannel: validateEvent: " +
+                    `not directed to or sent by me: ${event.getSender()}` +
+                    `, ${content && content.to}`);
                return false;
            }
        }

-        return VerificationRequest.validateEvent(
-            type, event, InRoomChannel.getTimestamp(event), client);
+        return VerificationRequest.validateEvent(type, event, client);
    }

    /**
@@ -130,28 +168,54 @@ export class InRoomChannel {
                }
            }
        }
-        return type;
+        if (type && type !== REQUEST_TYPE) {
+            return type;
+        } else {
+            return "";
+        }
    }

    /**
     * Changes the state of the channel, request, and verifier in response to a key verification event.
     * @param {MatrixEvent} event to handle
     * @param {VerificationRequest} request the request to forward handling to
+     * @param {bool} isLiveEvent whether this is an even received through sync or not
     * @returns {Promise} a promise that resolves when any requests as an anwser to the passed-in event are sent.
     */
-    async handleEvent(event, request) {
+    async handleEvent(event, request, isLiveEvent) {
        const type = InRoomChannel.getEventType(event);
        // do validations that need state (roomId, userId),
        // ignore if invalid
-        if (event.getRoomId() !== this._roomId || event.getSender() !== this._userId) {
+
+        if (event.getRoomId() !== this._roomId) {
            return;
        }
-        // set transactionId when receiving a .request
-        if (!this._requestEventId && type === REQUEST_TYPE) {
-            this._requestEventId = event.getId();
+        // set userId if not set already
+        if (this.userId === null) {
+            const userId = InRoomChannel.getOtherPartyUserId(event, this._client);
+            if (userId) {
+                this.userId = userId;
+            }
+        }
+        // ignore events not sent by us or the other party
+        const ownUserId = this._client.getUserId();
+        const sender = event.getSender();
+        if (this.userId !== null) {
+            if (sender !== ownUserId && sender !== this.userId) {
+                logger.log(`InRoomChannel: ignoring verification event from ` +
+                    `non-participating sender ${sender}`);
+                return;
+            }
+        }
+        if (this._requestEventId === null) {
+            this._requestEventId = InRoomChannel.getTransactionId(event);
        }

-        return await request.handleEvent(type, event, InRoomChannel.getTimestamp(event));
+        const isRemoteEcho = !!event.getUnsigned().transaction_id;
+        const isSentByUs = event.getSender() === this._client.getUserId();
+
+        return await request.handleEvent(
+            type, event, isLiveEvent, isRemoteEcho, isSentByUs);
    }

    /**
@@ -180,7 +244,7 @@ export class InRoomChannel {
     */
    completeContent(type, content) {
        content = Object.assign({}, content);
-        if (type === REQUEST_TYPE || type === START_TYPE) {
+        if (type === REQUEST_TYPE || type === READY_TYPE || type === START_TYPE) {
            content.from_device = this._client.getDeviceId();
        }
        if (type === REQUEST_TYPE) {
@@ -191,7 +255,7 @@ export class InRoomChannel {
                    "verification.  You will need to use legacy key " +
                    "verification to verify keys.",
                msgtype: REQUEST_TYPE,
-                to: this._userId,
+                to: this.userId,
                from_device: content.from_device,
                methods: content.methods,
            };
@@ -232,3 +296,69 @@ export class InRoomChannel {
        }
    }
 }
+
+export class InRoomRequests {
+    constructor() {
+        this._requestsByRoomId = new Map();
+    }
+
+    getRequest(event) {
+        const roomId = event.getRoomId();
+        const txnId = InRoomChannel.getTransactionId(event);
+        return this._getRequestByTxnId(roomId, txnId);
+    }
+
+    getRequestByChannel(channel) {
+        return this._getRequestByTxnId(channel.roomId, channel.transactionId);
+    }
+
+    _getRequestByTxnId(roomId, txnId) {
+        const requestsByTxnId = this._requestsByRoomId.get(roomId);
+        if (requestsByTxnId) {
+            return requestsByTxnId.get(txnId);
+        }
+    }
+
+    setRequest(event, request) {
+        this._setRequest(
+            event.getRoomId(),
+            InRoomChannel.getTransactionId(event),
+            request,
+        );
+    }
+
+    setRequestByChannel(channel, request) {
+        this._setRequest(channel.roomId, channel.transactionId, request);
+    }
+
+    _setRequest(roomId, txnId, request) {
+        let requestsByTxnId = this._requestsByRoomId.get(roomId);
+        if (!requestsByTxnId) {
+            requestsByTxnId = new Map();
+            this._requestsByRoomId.set(roomId, requestsByTxnId);
+        }
+        requestsByTxnId.set(txnId, request);
+    }
+
+    removeRequest(event) {
+        const roomId = event.getRoomId();
+        const requestsByTxnId = this._requestsByRoomId.get(roomId);
+        if (requestsByTxnId) {
+            requestsByTxnId.delete(InRoomChannel.getTransactionId(event));
+            if (requestsByTxnId.size === 0) {
+                this._requestsByRoomId.delete(roomId);
+            }
+        }
+    }
+
+    findRequestInProgress(roomId) {
+        const requestsByTxnId = this._requestsByRoomId.get(roomId);
+        if (requestsByTxnId) {
+            for (const request of requestsByTxnId.values()) {
+                if (request.pending) {
+                    return request;
+                }
+            }
+        }
+    }
+}
@@ -1,59 +0,0 @@
-/*
-Copyright 2019 The Matrix.org Foundation C.I.C.
-
-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.
-*/
-
-/** a key verification channel that wraps over an actual channel to pass it to a verifier,
- * to notify the VerificationRequest when the verifier tries to send anything over the channel.
- * This way, the VerificationRequest can update its state based on events sent by the verifier.
- * Anything that is not sending is just routing through to the wrapped channel.
- */
-export class RequestCallbackChannel {
-    constructor(request, channel) {
-        this._request = request;
-        this._channel = channel;
-    }
-
-    get transactionId() {
-        return this._channel.transactionId;
-    }
-
-    get needsDoneMessage() {
-        return this._channel.needsDoneMessage;
-    }
-
-    handleEvent(event, request) {
-        return this._channel.handleEvent(event, request);
-    }
-
-    completedContentFromEvent(event) {
-        return this._channel.completedContentFromEvent(event);
-    }
-
-    completeContent(type, content) {
-        return this._channel.completeContent(type, content);
-    }
-
-    async send(type, uncompletedContent) {
-        this._request.handleVerifierSend(type, uncompletedContent);
-        const result = await this._channel.send(type, uncompletedContent);
-        return result;
-    }
-
-    async sendCompleted(type, content) {
-        this._request.handleVerifierSend(type, content);
-        const result = await this._channel.sendCompleted(type, content);
-        return result;
-    }
-}
@@ -20,11 +20,14 @@ import {logger} from '../../../logger';
 import {
    CANCEL_TYPE,
    PHASE_STARTED,
+    PHASE_READY,
    REQUEST_TYPE,
+    READY_TYPE,
    START_TYPE,
    VerificationRequest,
 } from "./VerificationRequest";
 import {errorFromEvent, newUnexpectedMessageError} from "../Error";
+import {MatrixEvent} from "../../../models/event";

 /**
 * A key verification channel that sends verification events over to_device messages.
@@ -34,12 +37,34 @@ export class ToDeviceChannel {
    // userId and devices of user we're about to verify
    constructor(client, userId, devices, transactionId = null, deviceId = null) {
        this._client = client;
-        this._userId = userId;
+        this.userId = userId;
        this._devices = devices;
        this.transactionId = transactionId;
        this._deviceId = deviceId;
    }

+    isToDevices(devices) {
+        if (devices.length === this._devices.length) {
+            for (const device of devices) {
+                const d = this._devices.find(d => d.deviceId === device.deviceId);
+                if (!d) {
+                    return false;
+                }
+            }
+            return true;
+        } else {
+            return false;
+        }
+    }
+
+    get deviceId() {
+        return this._deviceId;
+    }
+
+    get needsDoneMessage() {
+        return false;
+    }
+
    static getEventType(event) {
        return event.getType();
    }
@@ -80,10 +105,12 @@ export class ToDeviceChannel {
        }
        const content = event.getContent();
        if (!content) {
+            logger.warn("ToDeviceChannel.validateEvent: invalid: no content");
            return false;
        }

        if (!content.transaction_id) {
+            logger.warn("ToDeviceChannel.validateEvent: invalid: no transaction_id");
            return false;
        }

@@ -91,6 +118,7 @@ export class ToDeviceChannel {

        if (type === REQUEST_TYPE) {
            if (!Number.isFinite(content.timestamp)) {
+                logger.warn("ToDeviceChannel.validateEvent: invalid: no timestamp");
                return false;
            }
            if (event.getSender() === client.getUserId() &&
@@ -98,19 +126,19 @@ export class ToDeviceChannel {
            ) {
                // ignore requests from ourselves, because it doesn't make sense for a
                // device to verify itself
+                logger.warn("ToDeviceChannel.validateEvent: invalid: from own device");
                return false;
            }
        }

-        return VerificationRequest.validateEvent(
-            type, event, ToDeviceChannel.getTimestamp(event), client);
+        return VerificationRequest.validateEvent(type, event, client);
    }

    /**
     * @param {MatrixEvent} event the event to get the timestamp of
     * @return {number} the timestamp when the event was sent
     */
-    static getTimestamp(event) {
+    getTimestamp(event) {
        const content = event.getContent();
        return content && content.timestamp;
    }
@@ -119,12 +147,13 @@ export class ToDeviceChannel {
     * Changes the state of the channel, request, and verifier in response to a key verification event.
     * @param {MatrixEvent} event to handle
     * @param {VerificationRequest} request the request to forward handling to
+     * @param {bool} isLiveEvent whether this is an even received through sync or not
     * @returns {Promise} a promise that resolves when any requests as an anwser to the passed-in event are sent.
     */
-    async handleEvent(event, request) {
+    async handleEvent(event, request, isLiveEvent) {
        const type = event.getType();
        const content = event.getContent();
-        if (type === REQUEST_TYPE || type === START_TYPE) {
+        if (type === REQUEST_TYPE || type === READY_TYPE || type === START_TYPE) {
            if (!this.transactionId) {
                this.transactionId = content.transaction_id;
            }
@@ -143,14 +172,17 @@ export class ToDeviceChannel {
                return this._sendToDevices(CANCEL_TYPE, cancelContent, [deviceId]);
            }
        }
+        const wasStarted = request.phase === PHASE_STARTED ||
+                           request.phase === PHASE_READY;

-        const wasStarted = request.phase === PHASE_STARTED;
-        await request.handleEvent(
-            event.getType(), event, ToDeviceChannel.getTimestamp(event));
-        const isStarted = request.phase === PHASE_STARTED;
+        await request.handleEvent(event.getType(), event, isLiveEvent, false, false);

-        // the request has picked a start event, tell the other devices about it
-        if (type === START_TYPE && !wasStarted && isStarted && this._deviceId) {
+        const isStarted = request.phase === PHASE_STARTED ||
+                          request.phase === PHASE_READY;
+
+        const isAcceptingEvent = type === START_TYPE || type === READY_TYPE;
+        // the request has picked a ready or start event, tell the other devices about it
+        if (isAcceptingEvent && !wasStarted && isStarted && this._deviceId) {
            const nonChosenDevices = this._devices.filter(d => d !== this._deviceId);
            if (nonChosenDevices.length) {
                const message = this.completeContent({
@@ -186,7 +218,7 @@ export class ToDeviceChannel {
        if (this.transactionId) {
            content.transaction_id = this.transactionId;
        }
-        if (type === REQUEST_TYPE || type === START_TYPE) {
+        if (type === REQUEST_TYPE || type === READY_TYPE || type === START_TYPE) {
            content.from_device = this._client.getDeviceId();
        }
        if (type === REQUEST_TYPE) {
@@ -216,12 +248,28 @@ export class ToDeviceChannel {
     * @param {object} content
     * @returns {Promise} the promise of the request
     */
-    sendCompleted(type, content) {
+    async sendCompleted(type, content) {
+        let result;
        if (type === REQUEST_TYPE) {
-            return this._sendToDevices(type, content, this._devices);
+            result = await this._sendToDevices(type, content, this._devices);
        } else {
-            return this._sendToDevices(type, content, [this._deviceId]);
+            result = await this._sendToDevices(type, content, [this._deviceId]);
        }
+        // the VerificationRequest state machine requires remote echos of the event
+        // the client sends itself, so we fake this for to_device messages
+        const remoteEchoEvent = new MatrixEvent({
+            sender: this._client.getUserId(),
+            content,
+            type,
+        });
+        await this._request.handleEvent(
+            type,
+            remoteEchoEvent,
+            /*isLiveEvent=*/true,
+            /*isRemoteEcho=*/true,
+            /*isSentByUs=*/true,
+        );
+        return result;
    }

    _sendToDevices(type, content, devices) {
@@ -231,7 +279,7 @@ export class ToDeviceChannel {
                msgMap[deviceId] = content;
            }

-            return this._client.sendToDevice(type, {[this._userId]: msgMap});
+            return this._client.sendToDevice(type, {[this.userId]: msgMap});
        } else {
            return Promise.resolve();
        }
@@ -245,3 +293,71 @@ export class ToDeviceChannel {
        return randomString(32);
    }
 }
+
+
+export class ToDeviceRequests {
+    constructor() {
+        this._requestsByUserId = new Map();
+    }
+
+    getRequest(event) {
+        return this.getRequestBySenderAndTxnId(
+            event.getSender(),
+            ToDeviceChannel.getTransactionId(event),
+        );
+    }
+
+    getRequestByChannel(channel) {
+        return this.getRequestBySenderAndTxnId(channel.userId, channel.transactionId);
+    }
+
+    getRequestBySenderAndTxnId(sender, txnId) {
+        const requestsByTxnId = this._requestsByUserId.get(sender);
+        if (requestsByTxnId) {
+            return requestsByTxnId.get(txnId);
+        }
+    }
+
+    setRequest(event, request) {
+        this.setRequestBySenderAndTxnId(
+            event.getSender(),
+            ToDeviceChannel.getTransactionId(event),
+            request,
+        );
+    }
+
+    setRequestByChannel(channel, request) {
+        this.setRequestBySenderAndTxnId(channel.userId, channel.transactionId, request);
+    }
+
+    setRequestBySenderAndTxnId(sender, txnId, request) {
+        let requestsByTxnId = this._requestsByUserId.get(sender);
+        if (!requestsByTxnId) {
+            requestsByTxnId = new Map();
+            this._requestsByUserId.set(sender, requestsByTxnId);
+        }
+        requestsByTxnId.set(txnId, request);
+    }
+
+    removeRequest(event) {
+        const userId = event.getSender();
+        const requestsByTxnId = this._requestsByUserId.get(userId);
+        if (requestsByTxnId) {
+            requestsByTxnId.delete(ToDeviceChannel.getTransactionId(event));
+            if (requestsByTxnId.size === 0) {
+                this._requestsByUserId.delete(userId);
+            }
+        }
+    }
+
+    findRequestInProgress(userId, devices) {
+        const requestsByTxnId = this._requestsByUserId.get(userId);
+        if (requestsByTxnId) {
+            for (const request of requestsByTxnId.values()) {
+                if (request.pending && request.channel.isToDevices(devices)) {
+                    return request;
+                }
+            }
+        }
+    }
+}
@@ -16,7 +16,6 @@ limitations under the License.
 */

 import {logger} from '../../../logger';
-import {RequestCallbackChannel} from "./RequestCallbackChannel";
 import {EventEmitter} from 'events';
 import {
    errorFactory,
@@ -24,6 +23,7 @@ import {
    newUnexpectedMessageError,
    newUnknownMethodError,
 } from "../Error";
+import * as olmlib from "../../olmlib";

 // the recommended amount of time before a verification request
 // should be (automatically) cancelled without user interaction
@@ -41,11 +41,11 @@ export const REQUEST_TYPE = EVENT_PREFIX + "request";
 export const START_TYPE = EVENT_PREFIX + "start";
 export const CANCEL_TYPE = EVENT_PREFIX + "cancel";
 export const DONE_TYPE = EVENT_PREFIX + "done";
-// export const READY_TYPE = EVENT_PREFIX + "ready";
+export const READY_TYPE = EVENT_PREFIX + "ready";

 export const PHASE_UNSENT = 1;
 export const PHASE_REQUESTED = 2;
-// const PHASE_READY = 3;
+export const PHASE_READY = 3;
 export const PHASE_STARTED = 4;
 export const PHASE_CANCELLED = 5;
 export const PHASE_DONE = 6;
@@ -58,17 +58,22 @@ export const PHASE_DONE = 6;
 * @event "change" whenever the state of the request object has changed.
 */
 export class VerificationRequest extends EventEmitter {
-    constructor(channel, verificationMethods, userId, client) {
+    constructor(channel, verificationMethods, client) {
        super();
        this.channel = channel;
+        this.channel._request = this;
        this._verificationMethods = verificationMethods;
        this._client = client;
        this._commonMethods = [];
        this._setPhase(PHASE_UNSENT, false);
-        this._requestEvent = null;
-        this._otherUserId = userId;
-        this._initiatedByMe = null;
-        this._startTimestamp = null;
+        this._eventsByUs = new Map();
+        this._eventsByThem = new Map();
+        this._observeOnly = false;
+        this._timeoutTimer = null;
+        this._sharedSecret = null; // used for QR codes
+        this._accepting = false;
+        this._declining = false;
+        this._verifierHasFinished = false;
    }

    /**
@@ -76,37 +81,38 @@ export class VerificationRequest extends EventEmitter {
     * Invoked by the same static method in either channel.
     * @param {string} type the "symbolic" event type, as returned by the `getEventType` function on the channel.
     * @param {MatrixEvent} event the event to validate. Don't call getType() on it but use the `type` parameter instead.
-     * @param {number} timestamp the timestamp in milliseconds when this event was sent.
     * @param {MatrixClient} client the client to get the current user and device id from
     * @returns {bool} whether the event is valid and should be passed to handleEvent
     */
-    static validateEvent(type, event, timestamp, client) {
+    static validateEvent(type, event, client) {
        const content = event.getContent();

-        if (!type.startsWith(EVENT_PREFIX)) {
+
+        if (!type || !type.startsWith(EVENT_PREFIX)) {
            return false;
        }

-        if (type === REQUEST_TYPE) {
-            if (!Array.isArray(content.methods)) {
-                return false;
-            }
+        // from here on we're fairly sure that this is supposed to be
+        // part of a verification request, so be noisy when rejecting something
+        if (!content) {
+            logger.log("VerificationRequest: validateEvent: no content");
+            return false;
        }
-        if (type === REQUEST_TYPE || type === START_TYPE) {
-            if (typeof content.from_device !== "string" ||
-                content.from_device.length === 0
-            ) {
+
+        if (type === REQUEST_TYPE || type === READY_TYPE) {
+            if (!Array.isArray(content.methods)) {
+                logger.log("VerificationRequest: validateEvent: " +
+                    "fail because methods");
                return false;
            }
        }

-        // a timestamp is not provided on all to_device events
-        if (Number.isFinite(timestamp)) {
-            const elapsed = Date.now() - timestamp;
-            // ignore if event is too far in the past or too far in the future
-            if (elapsed > (VERIFICATION_REQUEST_TIMEOUT - VERIFICATION_REQUEST_MARGIN) ||
-                elapsed < -(VERIFICATION_REQUEST_TIMEOUT / 2)) {
-                logger.log("received verification that is too old or from the future");
+        if (type === REQUEST_TYPE || type === READY_TYPE || type === START_TYPE) {
+            if (typeof content.from_device !== "string" ||
+                content.from_device.length === 0
+            ) {
+                logger.log("VerificationRequest: validateEvent: "+
+                    "fail because from_device");
                return false;
            }
        }
@@ -114,20 +120,56 @@ export class VerificationRequest extends EventEmitter {
        return true;
    }

-    /** once the phase is PHASE_STARTED, common methods supported by both sides */
+    get invalid() {
+        return this.phase === PHASE_UNSENT;
+    }
+
+    /** returns whether the phase is PHASE_REQUESTED */
+    get requested() {
+        return this.phase === PHASE_REQUESTED;
+    }
+
+    /** returns whether the phase is PHASE_CANCELLED */
+    get cancelled() {
+        return this.phase === PHASE_CANCELLED;
+    }
+
+    /** returns whether the phase is PHASE_READY */
+    get ready() {
+        return this.phase === PHASE_READY;
+    }
+
+    /** returns whether the phase is PHASE_STARTED */
+    get started() {
+        return this.phase === PHASE_STARTED;
+    }
+
+    /** returns whether the phase is PHASE_DONE */
+    get done() {
+        return this.phase === PHASE_DONE;
+    }
+
+    /** once the phase is PHASE_STARTED (and !initiatedByMe) or PHASE_READY: common methods supported by both sides */
    get methods() {
        return this._commonMethods;
    }

-    /** the timeout of the request, provided for compatibility with previous verification code */
+    /** The current remaining amount of ms before the request should be automatically cancelled */
    get timeout() {
-        const elapsed = Date.now() - this._startTimestamp;
-        return Math.max(0, VERIFICATION_REQUEST_TIMEOUT - elapsed);
+        const requestEvent = this._getEventByEither(REQUEST_TYPE);
+        if (requestEvent) {
+            const elapsed = Date.now() - this.channel.getTimestamp(requestEvent);
+            return Math.max(0, VERIFICATION_REQUEST_TIMEOUT - elapsed);
+        }
+        return 0;
    }

-    /** the m.key.verification.request event that started this request, provided for compatibility with previous verification code */
-    get event() {
-        return this._requestEvent;
+    /**
+     * The key verification request event.
+     * @returns {MatrixEvent} The request event, or falsey if not found.
+     */
+    get requestEvent() {
+        return this._getEventByEither(REQUEST_TYPE);
    }

    /** current phase of the request. Some properties might only be defined in a current phase. */
@@ -140,11 +182,50 @@ export class VerificationRequest extends EventEmitter {
        return this._verifier;
    }

+    get canAccept() {
+        return this.phase < PHASE_READY && !this._accepting && !this._declining;
+    }
+
+    get accepting() {
+        return this._accepting;
+    }
+
+    get declining() {
+        return this._declining;
+    }
+
    /** whether this request has sent it's initial event and needs more events to complete */
    get pending() {
-        return this._phase !== PHASE_UNSENT
-            && this._phase !== PHASE_DONE
-            && this._phase !== PHASE_CANCELLED;
+        return !this.observeOnly &&
+            this._phase !== PHASE_DONE &&
+            this._phase !== PHASE_CANCELLED;
+    }
+
+    /** Checks whether the other party supports a given verification method.
+     *  This is useful when setting up the QR code UI, as it is somewhat asymmetrical:
+     *  if the other party supports SCAN_QR, we should show a QR code in the UI, and vice versa.
+     *  For methods that need to be supported by both ends, use the `methods` property.
+     *  @param {string} method the method to check
+     *  @return {bool} whether or not the other party said the supported the method */
+    otherPartySupportsMethod(method) {
+        if (!this.ready && !this.started) {
+            return false;
+        }
+        const theirMethodEvent = this._eventsByThem.get(REQUEST_TYPE) ||
+            this._eventsByThem.get(READY_TYPE);
+        if (!theirMethodEvent) {
+            return false;
+        }
+        const content = theirMethodEvent.getContent();
+        if (!content) {
+            return false;
+        }
+        const {methods} = content;
+        if (!Array.isArray(methods)) {
+            return false;
+        }
+
+        return methods.includes(method);
    }

    /** Whether this request was initiated by the syncing user.
@@ -152,27 +233,108 @@ export class VerificationRequest extends EventEmitter {
     * For ToDeviceChannel, this is who sent the .start event
     */
    get initiatedByMe() {
-        return this._initiatedByMe;
+        // event created by us but no remote echo has been received yet
+        const noEventsYet = (this._eventsByUs.size + this._eventsByThem.size) === 0;
+        if (this._phase === PHASE_UNSENT && noEventsYet) {
+            return true;
+        }
+        const hasMyRequest = this._eventsByUs.has(REQUEST_TYPE);
+        const hasTheirRequest = this._eventsByThem.has(REQUEST_TYPE);
+        if (hasMyRequest && !hasTheirRequest) {
+            return true;
+        }
+        if (!hasMyRequest && hasTheirRequest) {
+            return false;
+        }
+        const hasMyStart = this._eventsByUs.has(START_TYPE);
+        const hasTheirStart = this._eventsByThem.has(START_TYPE);
+        if (hasMyStart && !hasTheirStart) {
+            return true;
+        }
+        return false;
    }

-    /** the id of the user that initiated the request */
+    /** The id of the user that initiated the request */
    get requestingUserId() {
        if (this.initiatedByMe) {
            return this._client.getUserId();
        } else {
-            return this._otherUserId;
+            return this.otherUserId;
        }
    }

-    /** the id of the user that (will) receive(d) the request */
+    /** The id of the user that (will) receive(d) the request */
    get receivingUserId() {
        if (this.initiatedByMe) {
-            return this._otherUserId;
+            return this.otherUserId;
        } else {
            return this._client.getUserId();
        }
    }

+    /** The user id of the other party in this request */
+    get otherUserId() {
+        return this.channel.userId;
+    }
+
+    /**
+     * The id of the user that cancelled the request,
+     * only defined when phase is PHASE_CANCELLED
+     */
+    get cancellingUserId() {
+        const myCancel = this._eventsByUs.get(CANCEL_TYPE);
+        const theirCancel = this._eventsByThem.get(CANCEL_TYPE);
+
+        if (myCancel && (!theirCancel || myCancel.getId() < theirCancel.getId())) {
+            return myCancel.getSender();
+        }
+        if (theirCancel) {
+            return theirCancel.getSender();
+        }
+        return undefined;
+    }
+
+    /**
+     * The cancellation code e.g m.user which is responsible for cancelling this verification
+     */
+    get cancellationCode() {
+        const ev = this._getEventByEither(CANCEL_TYPE);
+        return ev ? ev.getContent().code : null;
+    }
+
+    get observeOnly() {
+        return this._observeOnly;
+    }
+
+    /**
+     * The unpadded base64 encoded shared secret. Primarily used for QR code
+     * verification.
+     */
+    get encodedSharedSecret() {
+        if (!this._sharedSecret) this._generateSharedSecret();
+        return this._sharedSecret;
+    }
+
+    /**
+     * Gets which device the verification should be started with
+     * given the events sent so far in the verification. This is the
+     * same algorithm used to determine which device to send the
+     * verification to when no specific device is specified.
+     * @returns {{userId: *, deviceId: *}} The device information
+     */
+    get targetDevice() {
+        const theirFirstEvent =
+            this._eventsByThem.get(REQUEST_TYPE) ||
+            this._eventsByThem.get(READY_TYPE) ||
+            this._eventsByThem.get(START_TYPE);
+        const theirFirstContent = theirFirstEvent.getContent();
+        const fromDevice = theirFirstContent.from_device;
+        return {
+            userId: this.otherUserId,
+            deviceId: fromDevice,
+        };
+    }
+
    /* Start the key verification, creating a verifier and sending a .start event.
     * If no previous events have been sent, pass in `targetDevice` to set who to direct this request to.
     * @param {string} method the name of the verification method to use.
@@ -182,8 +344,13 @@ export class VerificationRequest extends EventEmitter {
     */
    beginKeyVerification(method, targetDevice = null) {
        // need to allow also when unsent in case of to_device
-        if (!this._verifier) {
-            if (this._hasValidPreStartPhase()) {
+        if (!this.observeOnly && !this._verifier) {
+            const validStartPhase =
+                this.phase === PHASE_REQUESTED ||
+                this.phase === PHASE_READY ||
+                (this.phase === PHASE_UNSENT &&
+                    this.channel.constructor.canCreateRequest(START_TYPE));
+            if (validStartPhase) {
                // when called on a request that was initiated with .request event
                // check the method is supported by both sides
                if (this._commonMethods.length && !this._commonMethods.includes(method)) {
@@ -203,12 +370,10 @@ export class VerificationRequest extends EventEmitter {
     * @returns {Promise} resolves when the event has been sent.
     */
    async sendRequest() {
-        if (this._phase === PHASE_UNSENT) {
-            this._initiatedByMe = true;
-            this._setPhase(PHASE_REQUESTED, false);
+        if (!this.observeOnly && this._phase === PHASE_UNSENT) {
            const methods = [...this._verificationMethods.keys()];
            await this.channel.send(REQUEST_TYPE, {methods});
-            this.emit("change");
+            this._generateSharedSecret();
        }
    }

@@ -219,34 +384,67 @@ export class VerificationRequest extends EventEmitter {
     * @returns {Promise} resolves when the event has been sent.
     */
    async cancel({reason = "User declined", code = "m.user"} = {}) {
-        if (this._phase !== PHASE_CANCELLED) {
+        if (!this.observeOnly && this._phase !== PHASE_CANCELLED) {
+            this._declining = true;
+            this.emit("change");
            if (this._verifier) {
-                return this._verifier.cancel(errorFactory(code, reason));
+                return this._verifier.cancel(errorFactory(code, reason)());
            } else {
-                this._setPhase(PHASE_CANCELLED, false);
+                this._cancellingUserId = this._client.getUserId();
                await this.channel.send(CANCEL_TYPE, {code, reason});
            }
-            this.emit("change");
        }
    }

-    /** @returns {Promise} with the verifier once it becomes available. Can be used after calling `sendRequest`. */
-    waitForVerifier() {
-        if (this.verifier) {
-            return Promise.resolve(this.verifier);
-        } else {
-            return new Promise(resolve => {
-                const checkVerifier = () => {
-                    if (this.verifier) {
-                        this.off("change", checkVerifier);
-                        resolve(this.verifier);
-                    }
-                };
-                this.on("change", checkVerifier);
-            });
+    /**
+     * Accepts the request, sending a .ready event to the other party
+     * @returns {Promise} resolves when the event has been sent.
+     */
+    async accept() {
+        if (!this.observeOnly && this.phase === PHASE_REQUESTED && !this.initiatedByMe) {
+            const methods = [...this._verificationMethods.keys()];
+            this._accepting = true;
+            this.emit("change");
+            await this.channel.send(READY_TYPE, {methods});
+            this._generateSharedSecret();
        }
    }

+    _generateSharedSecret() {
+        const secretBytes = new Uint8Array(8);
+        global.crypto.getRandomValues(secretBytes);
+        this._sharedSecret = olmlib.encodeUnpaddedBase64(secretBytes);
+    }
+
+    /**
+     * Can be used to listen for state changes until the callback returns true.
+     * @param {Function} fn callback to evaluate whether the request is in the desired state.
+     *                      Takes the request as an argument.
+     * @returns {Promise} that resolves once the callback returns true
+     * @throws {Error} when the request is cancelled
+     */
+    waitFor(fn) {
+        return new Promise((resolve, reject) => {
+            const check = () => {
+                let handled = false;
+                if (fn(this)) {
+                    resolve(this);
+                    handled = true;
+                } else if (this.cancelled) {
+                    reject(new Error("cancelled"));
+                    handled = true;
+                }
+                if (handled) {
+                    this.off("change", check);
+                }
+                return handled;
+            };
+            if (!check()) {
+                this.on("change", check);
+            }
+        });
+    }
+
    _setPhase(phase, notify = true) {
        this._phase = phase;
        if (notify) {
@@ -254,155 +452,310 @@ export class VerificationRequest extends EventEmitter {
        }
    }

+    _getEventByEither(type) {
+        return this._eventsByThem.get(type) || this._eventsByUs.get(type);
+    }
+
+    _getEventBy(type, byThem) {
+        if (byThem) {
+            return this._eventsByThem.get(type);
+        } else {
+            return this._eventsByUs.get(type);
+        }
+    }
+
+    _calculatePhaseTransitions() {
+        const transitions = [{phase: PHASE_UNSENT}];
+        const phase = () => transitions[transitions.length - 1].phase;
+
+        // always pass by .request first to be sure channel.userId has been set
+        const hasRequestByThem = this._eventsByThem.has(REQUEST_TYPE);
+        const requestEvent = this._getEventBy(REQUEST_TYPE, hasRequestByThem);
+        if (requestEvent) {
+            transitions.push({phase: PHASE_REQUESTED, event: requestEvent});
+        }
+
+        const readyEvent =
+            requestEvent && this._getEventBy(READY_TYPE, !hasRequestByThem);
+        if (readyEvent && phase() === PHASE_REQUESTED) {
+            transitions.push({phase: PHASE_READY, event: readyEvent});
+        }
+
+        let startEvent;
+        if (readyEvent || !requestEvent) {
+            const theirStartEvent = this._eventsByThem.get(START_TYPE);
+            const ourStartEvent = this._eventsByUs.get(START_TYPE);
+            // any party can send .start after a .ready or unsent
+            if (theirStartEvent && ourStartEvent) {
+                startEvent = theirStartEvent.getSender() < ourStartEvent.getSender() ?
+                    theirStartEvent : ourStartEvent;
+            } else {
+                startEvent = theirStartEvent ? theirStartEvent : ourStartEvent;
+            }
+        } else {
+            startEvent = this._getEventBy(START_TYPE, !hasRequestByThem);
+        }
+        if (startEvent) {
+            const fromRequestPhase = phase() === PHASE_REQUESTED &&
+                requestEvent.getSender() !== startEvent.getSender();
+            const fromUnsentPhase = phase() === PHASE_UNSENT &&
+                this.channel.constructor.canCreateRequest(START_TYPE);
+            if (fromRequestPhase || phase() === PHASE_READY || fromUnsentPhase) {
+                transitions.push({phase: PHASE_STARTED, event: startEvent});
+            }
+        }
+
+        const ourDoneEvent = this._eventsByUs.get(DONE_TYPE);
+        if (this._verifierHasFinished || (ourDoneEvent && phase() === PHASE_STARTED)) {
+            transitions.push({phase: PHASE_DONE});
+        }
+
+        const cancelEvent = this._getEventByEither(CANCEL_TYPE);
+        if (cancelEvent && phase() !== PHASE_DONE) {
+            transitions.push({phase: PHASE_CANCELLED, event: cancelEvent});
+            return transitions;
+        }
+
+        return transitions;
+    }
+
+    _transitionToPhase(transition) {
+        const {phase, event} = transition;
+        // get common methods
+        if (phase === PHASE_REQUESTED || phase === PHASE_READY) {
+            if (!this._wasSentByOwnDevice(event)) {
+                const content = event.getContent();
+                this._commonMethods =
+                    content.methods.filter(m => this._verificationMethods.has(m));
+            }
+        }
+        // detect if we're not a party in the request, and we should just observe
+        if (!this.observeOnly) {
+            // if requested or accepted by one of my other devices
+            if (phase === PHASE_REQUESTED ||
+                phase === PHASE_STARTED ||
+                phase === PHASE_READY
+            ) {
+                if (
+                    this.channel.receiveStartFromOtherDevices &&
+                    this._wasSentByOwnUser(event) &&
+                    !this._wasSentByOwnDevice(event)
+                ) {
+                    this._observeOnly = true;
+                }
+            }
+        }
+        // create verifier
+        if (phase === PHASE_STARTED) {
+            const {method} = event.getContent();
+            if (!this._verifier && !this.observeOnly) {
+                this._verifier = this._createVerifier(method, event);
+            }
+        }
+    }
+
+    _applyPhaseTransitions() {
+        const transitions = this._calculatePhaseTransitions();
+        const existingIdx = transitions.findIndex(t => t.phase === this.phase);
+        // trim off phases we already went through, if any
+        const newTransitions = transitions.slice(existingIdx + 1);
+        // transition to all new phases
+        for (const transition of newTransitions) {
+            this._transitionToPhase(transition);
+        }
+        return newTransitions;
+    }
+
    /**
     * Changes the state of the request and verifier in response to a key verification event.
     * @param {string} type the "symbolic" event type, as returned by the `getEventType` function on the channel.
     * @param {MatrixEvent} event the event to handle. Don't call getType() on it but use the `type` parameter instead.
-     * @param {number} timestamp the timestamp in milliseconds when this event was sent.
+     * @param {bool} isLiveEvent whether this is an even received through sync or not
+     * @param {bool} isRemoteEcho whether this is the remote echo of an event sent by the same device
+     * @param {bool} isSentByUs whether this event is sent by a party that can accept and/or observe the request like one of our peers.
+     *   For InRoomChannel this means any device for the syncing user. For ToDeviceChannel, just the syncing device.
     * @returns {Promise} a promise that resolves when any requests as an anwser to the passed-in event are sent.
     */
-    async handleEvent(type, event, timestamp) {
-        const content = event.getContent();
-        if (type === REQUEST_TYPE || type === START_TYPE) {
-            if (this._startTimestamp === null) {
-                this._startTimestamp = timestamp;
-            }
-        }
-        if (type === REQUEST_TYPE) {
-            await this._handleRequest(content, event);
-        } else if (type === START_TYPE) {
-            await this._handleStart(content, event);
+    async handleEvent(type, event, isLiveEvent, isRemoteEcho, isSentByUs) {
+        // if reached phase cancelled or done, ignore anything else that comes
+        if (this.done || this.cancelled) {
+            return;
        }
+        const wasObserveOnly = this._observeOnly;

-        if (this._verifier) {
-            if (type === CANCEL_TYPE || (this._verifier.events
-                && this._verifier.events.includes(type))) {
-                this._verifier.handleEvent(event);
+        this._adjustObserveOnly(event, isLiveEvent);
+
+        if (!this.observeOnly && !isRemoteEcho) {
+            if (await this._cancelOnError(type, event)) {
+                return;
            }
        }

-        if (type === CANCEL_TYPE) {
-            this._handleCancel();
-        } else if (type === DONE_TYPE) {
-            this._handleDone();
+        const oldPhase = this.phase;
+        this._addEvent(type, event, isSentByUs);
+
+        // this will create if needed the verifier so needs to happen before calling it
+        const newTransitions = this._applyPhaseTransitions();
+        try {
+            // only pass events from the other side to the verifier,
+            // no remote echos of our own events
+            if (this._verifier && !this.observeOnly) {
+                const oldEvent = this._verifier.startEvent;
+                // if the verifier does not have a startEvent, it is because it's still sending and we are on the initator side
+                const oldSender = oldEvent ?
+                    oldEvent.getSender() :
+                    this._client.getUserId();
+                const newEventWinsRace = event.getSender() < oldSender;
+                if (this._verifier.canSwitchStartEvent(event) && newEventWinsRace) {
+                    this._verifier.switchStartEvent(event);
+                } else if (!isRemoteEcho) {
+                     if (type === CANCEL_TYPE || (this._verifier.events
+                        && this._verifier.events.includes(type))) {
+                        this._verifier.handleEvent(event);
+                    }
+                }
+            }
+
+            if (newTransitions.length) {
+                const lastTransition = newTransitions[newTransitions.length - 1];
+                const {phase} = lastTransition;
+
+                this._setupTimeout(phase);
+                // set phase as last thing as this emits the "change" event
+                this._setPhase(phase);
+            } else if (this._observeOnly !== wasObserveOnly) {
+                this.emit("change");
+            }
+        } finally {
+            // log events we processed so we can see from rageshakes what events were added to a request
+            logger.log(`Verification request ${this.channel.transactionId}: ` +
+                `${type} event with id:${event.getId()}, ` +
+                `content:${JSON.stringify(event.getContent())} ` +
+                `deviceId:${this.channel.deviceId}, ` +
+                `sender:${event.getSender()}, isSentByUs:${isSentByUs}, ` +
+                `isLiveEvent:${isLiveEvent}, isRemoteEcho:${isRemoteEcho}, ` +
+                `phase:${oldPhase}=>${this.phase}, ` +
+                `observeOnly:${wasObserveOnly}=>${this._observeOnly}`);
        }
    }

-    async _handleRequest(content, event) {
-        if (this._phase === PHASE_UNSENT) {
-            const otherMethods = content.methods;
-            this._commonMethods = otherMethods.
-                filter(m => this._verificationMethods.has(m));
-            this._requestEvent = event;
-            this._initiatedByMe = this._wasSentByMe(event);
-            this._setPhase(PHASE_REQUESTED);
-        } else if (this._phase !== PHASE_REQUESTED) {
-            logger.warn("Ignoring flagged verification request from " +
-                event.getSender());
-            await this.cancel(errorFromEvent(newUnexpectedMessageError()));
+    _setupTimeout(phase) {
+        const shouldTimeout = !this._timeoutTimer && !this.observeOnly &&
+            phase === PHASE_REQUESTED && this.initiatedByMe;
+
+        if (shouldTimeout) {
+            this._timeoutTimer = setTimeout(this._cancelOnTimeout, this.timeout);
+        }
+        if (this._timeoutTimer) {
+            const shouldClear = phase === PHASE_STARTED ||
+                phase === PHASE_READY ||
+                phase === PHASE_DONE ||
+                phase === PHASE_CANCELLED;
+            if (shouldClear) {
+                clearTimeout(this._timeoutTimer);
+                this._timeoutTimer = null;
+            }
        }
    }

-    _hasValidPreStartPhase() {
-        return this._phase === PHASE_REQUESTED ||
-            (
-                this.channel.constructor.canCreateRequest(START_TYPE) &&
-                this._phase === PHASE_UNSENT
-            );
-    }
+    _cancelOnTimeout = () => {
+        try {
+            this.cancel({reason: "Other party didn't accept in time", code: "m.timeout"});
+        } catch (err) {
+            logger.error("Error while cancelling verification request", err);
+        }
+    };

-    async _handleStart(content, event) {
-        if (this._hasValidPreStartPhase()) {
-            const {method} = content;
+    async _cancelOnError(type, event) {
+        if (type === START_TYPE) {
+            const method = event.getContent().method;
            if (!this._verificationMethods.has(method)) {
                await this.cancel(errorFromEvent(newUnknownMethodError()));
-            } else {
-                // if not in requested phase
-                if (this.phase === PHASE_UNSENT) {
-                    this._initiatedByMe = this._wasSentByMe(event);
+                return true;
+            }
+        }
+
+        const isUnexpectedRequest = type === REQUEST_TYPE && this.phase !== PHASE_UNSENT;
+        const isUnexpectedReady = type === READY_TYPE && this.phase !== PHASE_REQUESTED;
+        // only if phase has passed from PHASE_UNSENT should we cancel, because events
+        // are allowed to come in in any order (at least with InRoomChannel). So we only know
+        // we're dealing with a valid request we should participate in once we've moved to PHASE_REQUESTED
+        // before that, we could be looking at somebody elses verification request and we just
+        // happen to be in the room
+        if (this.phase !== PHASE_UNSENT && (isUnexpectedRequest || isUnexpectedReady)) {
+            logger.warn(`Cancelling, unexpected ${type} verification ` +
+                `event from ${event.getSender()}`);
+            const reason = `Unexpected ${type} event in phase ${this.phase}`;
+            await this.cancel(errorFromEvent(newUnexpectedMessageError({reason})));
+            return true;
+        }
+        return false;
+    }
+
+    _adjustObserveOnly(event, isLiveEvent) {
+        // don't send out events for historical requests
+        if (!isLiveEvent) {
+            this._observeOnly = true;
+        }
+        // a timestamp is not provided on all to_device events
+        const timestamp = this.channel.getTimestamp(event);
+        if (Number.isFinite(timestamp)) {
+            const elapsed = Date.now() - timestamp;
+            // don't allow interaction on old requests
+            if (elapsed > (VERIFICATION_REQUEST_TIMEOUT - VERIFICATION_REQUEST_MARGIN) ||
+                elapsed < -(VERIFICATION_REQUEST_TIMEOUT / 2)
+            ) {
+                this._observeOnly = true;
+            }
+        }
+    }
+
+    _addEvent(type, event, isSentByUs) {
+        if (isSentByUs) {
+            this._eventsByUs.set(type, event);
+        } else {
+            this._eventsByThem.set(type, event);
+        }
+
+        // once we know the userId of the other party (from the .request event)
+        // see if any event by anyone else crept into this._eventsByThem
+        if (type === REQUEST_TYPE) {
+            for (const [type, event] of this._eventsByThem.entries()) {
+                if (event.getSender() !== this.otherUserId) {
+                    this._eventsByThem.delete(type);
                }
-                this._verifier = this._createVerifier(method, event);
-                this._setPhase(PHASE_STARTED);
            }
        }
    }

-    /**
-     * Called by RequestCallbackChannel when the verifier sends an event
-     * @param {string} type the "symbolic" event type
-     * @param {object} content the completed or uncompleted content for the event to be sent
-     */
-    handleVerifierSend(type, content) {
-        if (type === CANCEL_TYPE) {
-            this._handleCancel();
-        } else if (type === START_TYPE) {
-            if (this._phase === PHASE_UNSENT || this._phase === PHASE_REQUESTED) {
-                // if unsent, we're sending a (first) .start event and hence requesting the verification.
-                // in any other situation, the request was initiated by the other party.
-                this._initiatedByMe = this.phase === PHASE_UNSENT;
-                this._setPhase(PHASE_STARTED);
-            }
-        }
-    }
-
-    _handleCancel() {
-        if (this._phase !== PHASE_CANCELLED) {
-            this._setPhase(PHASE_CANCELLED);
-        }
-    }
-
-    _handleDone() {
-        if (this._phase === PHASE_STARTED) {
-            this._setPhase(PHASE_DONE);
-        }
-    }
-
    _createVerifier(method, startEvent = null, targetDevice = null) {
-        const startSentByMe = startEvent && this._wasSentByMe(startEvent);
-        const {userId, deviceId} = this._getVerifierTarget(startEvent, targetDevice);
+        if (!targetDevice) {
+            targetDevice = this.targetDevice;
+        }
+        const {userId, deviceId} = targetDevice;

        const VerifierCtor = this._verificationMethods.get(method);
        if (!VerifierCtor) {
-            console.warn("could not find verifier constructor for method", method);
+            logger.warn("could not find verifier constructor for method", method);
            return;
        }
-        // invokes handleVerifierSend when verifier sends something
-        const callbackMedium = new RequestCallbackChannel(this, this.channel);
        return new VerifierCtor(
-            callbackMedium,
+            this.channel,
            this._client,
            userId,
            deviceId,
-            startSentByMe ? null : startEvent,
+            startEvent,
+            this,
        );
    }

-    _getVerifierTarget(startEvent, targetDevice) {
-        // targetDevice should be set when creating a verifier for to_device before the .start event has been sent,
-        // so the userId and deviceId are provided
-        if (targetDevice) {
-            return targetDevice;
-        } else {
-            let targetEvent;
-            if (startEvent && !this._wasSentByMe(startEvent)) {
-                targetEvent = startEvent;
-            } else if (this._requestEvent && !this._wasSentByMe(this._requestEvent)) {
-                targetEvent = this._requestEvent;
-            } else {
-                throw new Error(
-                    "can't determine who the verifier should be targeted at. " +
-                    "No .request or .start event and no targetDevice");
-            }
-            const userId = targetEvent.getSender();
-            const content = targetEvent.getContent();
-            const deviceId = content && content.from_device;
-            return {userId, deviceId};
-        }
+    _wasSentByOwnUser(event) {
+        return event.getSender() === this._client.getUserId();
    }

-    // only for .request and .start
-    _wasSentByMe(event) {
-        if (event.getSender() !== this._client.getUserId()) {
+    // only for .request, .ready or .start
+    _wasSentByOwnDevice(event) {
+        if (!this._wasSentByOwnUser(event)) {
            return false;
        }
        const content = event.getContent();
@@ -411,4 +764,16 @@ export class VerificationRequest extends EventEmitter {
        }
        return true;
    }
+
+    onVerifierFinished() {
+        if (this.channel.needsDoneMessage) {
+            // verification in DM requires a done message
+            this.channel.send("m.key.verification.done", {});
+        }
+        this._verifierHasFinished = true;
+        const newTransitions = this._applyPhaseTransitions();
+        if (newTransitions.length) {
+            this._setPhase(newTransitions[newTransitions.length - 1].phase);
+        }
+    }
 }
@@ -47,6 +47,7 @@ export const PREFIX_UNSTABLE = "/_matrix/client/unstable";

 /**
 * URI path for v1 of the the identity API
+ * @deprecated Use v2.
 */
 export const PREFIX_IDENTITY_V1 = "/_matrix/identity/api/v1";

@@ -155,7 +156,7 @@ MatrixHttpApi.prototype = {
     *    data has been uploaded, with an object containing the fields `loaded`
     *    (number of bytes transferred) and `total` (total size, if known).
     *
-     * @return {module:client.Promise} Resolves to response object, as
+     * @return {Promise} Resolves to response object, as
     *    determined by this.opts.onlyData, opts.rawResponse, and
     *    opts.onlyContentUri.  Rejects with an error (usually a MatrixError).
     */
@@ -436,7 +437,7 @@ MatrixHttpApi.prototype = {
     * @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 {Object} [data] The HTTP JSON body.
     *
     * @param {Object|Number=} opts additional options. If a number is specified,
     * this is treated as `opts.localTimeoutMs`.
@@ -449,7 +450,7 @@ MatrixHttpApi.prototype = {
     *
     * @param {Object=} opts.headers map of additional request headers
     *
-     * @return {module:client.Promise} Resolves to <code>{data: {Object},
+     * @return {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>
     * object only.
@@ -518,7 +519,7 @@ MatrixHttpApi.prototype = {
     * @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 {Object} [data] The HTTP JSON body.
     *
     * @param {Object=} opts additional options
     *
@@ -530,7 +531,7 @@ MatrixHttpApi.prototype = {
     *
     * @param {Object=} opts.headers map of additional request headers
     *
-     * @return {module:client.Promise} Resolves to <code>{data: {Object},
+     * @return {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>
     * object only.
@@ -557,7 +558,7 @@ MatrixHttpApi.prototype = {
     * @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 {Object} [data] The HTTP JSON body.
     *
     * @param {Object=} opts additional options
     *
@@ -569,7 +570,7 @@ MatrixHttpApi.prototype = {
     *
     * @param {Object=} opts.headers map of additional request headers
     *
-     * @return {module:client.Promise} Resolves to <code>{data: {Object},
+     * @return {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>
     * object only.
@@ -633,7 +634,7 @@ MatrixHttpApi.prototype = {
     * @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
+     * @return {Promise} a promise which resolves to either the
     * response object (if this.opts.onlyData is truthy), or the parsed
     * body. Rejects
     */
@@ -16,8 +16,9 @@ limitations under the License.

 import * as matrixcs from "./matrix";
 import * as utils from "./utils";
+import request from "request";

-matrixcs.request(import("request"));
+matrixcs.request(request);
 utils.runPolyfills();

 export * from "./matrix";
@@ -47,14 +47,14 @@ const MSISDN_STAGE_TYPE = "m.login.msisdn";
 * @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
+ * @param {function(object?): Promise} opts.doRequest
 *     called with the new auth dict to submit the request. Also passes a
 *     second deprecated arg which is a flag set to true if this request
 *     is a background request. The busyChanged callback should be used
 *     instead of the backfround flag. Should return a promise which resolves
 *     to the successful response or rejects with a MatrixError.
 *
- * @param {function(bool): module:client.Promise} opts.busyChanged
+ * @param {function(bool): Promise} opts.busyChanged
 *     called whenever the interactive auth logic becomes busy submitting
 *     information provided by the user or finsihes. After this has been
 *     called with true the UI should indicate that a request is in progress
@@ -132,7 +132,7 @@ InteractiveAuth.prototype = {
    /**
     * begin the authentication process.
     *
-     * @return {module:client.Promise} which resolves to the response on success,
+     * @return {Promise} which resolves to the response on success,
     * or rejects with the error on failure. Rejects with NoAuthFlowFoundError if
     *     no suitable authentication flow can be found
     */
@@ -29,6 +29,25 @@ import log from "loglevel";
 // Part of #332 is introducing a logging library in the first place.
 const DEFAULT_NAMESPACE = "matrix";

+// because rageshakes in react-sdk hijack the console log, also at module load time,
+// initializing the logger here races with the initialization of rageshakes.
+// to avoid the issue, we override the methodFactory of loglevel that binds to the
+// console methods at initialization time by a factory that looks up the console methods
+// when logging so we always get the current value of console methods.
+log.methodFactory = function(methodName, logLevel, loggerName) {
+    return function(...args) {
+        const supportedByConsole = methodName === "error" ||
+            methodName === "warn" ||
+            methodName === "trace" ||
+            methodName === "info";
+        if (supportedByConsole) {
+            return console[methodName](...args);
+        } else {
+            return console.log(...args);
+        }
+    };
+};
+
 /**
 * Drop-in replacement for <code>console</code> using {@link https://www.npmjs.com/package/loglevel|loglevel}.
 * Can be tailored down to specific use cases if needed.
@@ -103,11 +103,11 @@ export function setCryptoStoreFactory(fac) {
 }

 /**
- * Construct a Matrix Client. Similar to {@link module:client~MatrixClient}
+ * Construct a Matrix Client. Similar to {@link module:client.MatrixClient}
 * except that the 'request', 'store' and 'scheduler' dependencies are satisfied.
 * @param {(Object|string)} opts The configuration options for this client. If
 * this is a string, it is assumed to be the base URL. These configuration
- * options will be passed directly to {@link module:client~MatrixClient}.
+ * options will be passed directly to {@link module:client.MatrixClient}.
 * @param {Object} opts.store If not set, defaults to
 * {@link module:store/memory.MemoryStore}.
 * @param {Object} opts.scheduler If not set, defaults to
@@ -122,7 +122,7 @@ export function setCryptoStoreFactory(fac) {
 *    in-memory otherwise).
 *
 * @return {MatrixClient} A new matrix client.
- * @see {@link module:client~MatrixClient} for the full list of options for
+ * @see {@link module:client.MatrixClient} for the full list of options for
 * <code>opts</code>.
 */
 export function createClient(opts) {
@@ -490,8 +490,9 @@ EventTimelineSet.prototype.addEventsToTimeline = function(events, toStartOfTimel
 *
 * @param {MatrixEvent} event Event to be added
 * @param {string?} duplicateStrategy 'ignore' or 'replace'
+ * @param {boolean} fromCache whether the sync response came from cache
 */
-EventTimelineSet.prototype.addLiveEvent = function(event, duplicateStrategy) {
+EventTimelineSet.prototype.addLiveEvent = function(event, duplicateStrategy, fromCache) {
    if (this._filter) {
        const events = this._filter.filterRoomTimeline([event]);
        if (!events.length) {
@@ -529,7 +530,7 @@ EventTimelineSet.prototype.addLiveEvent = function(event, duplicateStrategy) {
        return;
    }

-    this.addEventToTimeline(event, this._liveTimeline, false);
+    this.addEventToTimeline(event, this._liveTimeline, false, fromCache);
 };

 /**
@@ -541,11 +542,12 @@ EventTimelineSet.prototype.addLiveEvent = function(event, duplicateStrategy) {
 * @param {MatrixEvent} event
 * @param {EventTimeline} timeline
 * @param {boolean} toStartOfTimeline
+ * @param {boolean} fromCache whether the sync response came from cache
 *
 * @fires module:client~MatrixClient#event:"Room.timeline"
 */
 EventTimelineSet.prototype.addEventToTimeline = function(event, timeline,
-                                                         toStartOfTimeline) {
+                                                         toStartOfTimeline, fromCache) {
    const eventId = event.getId();
    timeline.addEvent(event, toStartOfTimeline);
    this._eventIdToTimeline[eventId] = timeline;
@@ -555,7 +557,7 @@ EventTimelineSet.prototype.addEventToTimeline = function(event, timeline,

    const data = {
        timeline: timeline,
-        liveEvent: !toStartOfTimeline && timeline == this._liveTimeline,
+        liveEvent: !toStartOfTimeline && timeline == this._liveTimeline && !fromCache,
    };
    this.emit("Room.timeline", event, this.room,
              Boolean(toStartOfTimeline), false, data);
@@ -828,7 +830,7 @@ EventTimelineSet.prototype.aggregateRelations = function(event) {
 *
 * @param {object} data  more data about the event
 *
- * @param {module:event-timeline.EventTimeline} data.timeline the timeline the
+ * @param {module:models/event-timeline.EventTimeline} data.timeline the timeline the
 * event was added to/removed from
 *
 * @param {boolean} data.liveEvent true if the event was a real-time event
@@ -22,7 +22,7 @@ limitations under the License.
 */

 import {EventEmitter} from 'events';
-import * as utils from '../utils.js';
+import * as utils from '../utils';
 import {logger} from '../logger';

 /**
@@ -154,6 +154,12 @@ export const MatrixEvent = function(
     * attempt may succeed)
     */
    this._retryDecryption = false;
+
+    /* If the event is a `m.key.verification.request` (or to_device `m.key.verification.start`) event,
+     * `Crypto` will set this the `VerificationRequest` for the event
+     * so it can be easily accessed from the timeline.
+     */
+    this.verificationRequest = null;
 };
 utils.inherits(MatrixEvent, EventEmitter);

@@ -1054,6 +1060,10 @@ utils.extend(MatrixEvent.prototype, {
            encrypted: this.event,
        };
    },
+
+    setVerificationRequest: function(request) {
+        this.verificationRequest = request;
+    },
 });


@@ -861,11 +861,23 @@ Room.prototype.getAliases = function() {
 Room.prototype.getCanonicalAlias = function() {
    const canonicalAlias = this.currentState.getStateEvents("m.room.canonical_alias", "");
    if (canonicalAlias) {
-        return canonicalAlias.getContent().alias;
+        return canonicalAlias.getContent().alias || null;
    }
    return null;
 };

+/**
+ * Get this room's alternative aliases
+ * @return {array} The room's alternative aliases, or an empty array
+ */
+Room.prototype.getAltAliases = function() {
+    const canonicalAlias = this.currentState.getStateEvents("m.room.canonical_alias", "");
+    if (canonicalAlias) {
+        return canonicalAlias.getContent().alt_aliases || [];
+    }
+    return [];
+};
+
 /**
 * Add events to a timeline
 *
@@ -1067,10 +1079,11 @@ Room.prototype.removeFilteredTimelineSet = function(filter) {
 *
 * @param {MatrixEvent} event Event to be added
 * @param {string?} duplicateStrategy 'ignore' or 'replace'
+ * @param {boolean} fromCache whether the sync response came from cache
 * @fires module:client~MatrixClient#event:"Room.timeline"
 * @private
 */
-Room.prototype._addLiveEvent = function(event, duplicateStrategy) {
+Room.prototype._addLiveEvent = function(event, duplicateStrategy, fromCache) {
    if (event.isRedaction()) {
        const redactId = event.event.redacts;

@@ -1117,7 +1130,7 @@ Room.prototype._addLiveEvent = function(event, duplicateStrategy) {

    // add to our timeline sets
    for (let i = 0; i < this._timelineSets.length; i++) {
-        this._timelineSets[i].addLiveEvent(event, duplicateStrategy);
+        this._timelineSets[i].addLiveEvent(event, duplicateStrategy, fromCache);
    }

    // synthesize and inject implicit read receipts
@@ -1427,9 +1440,10 @@ Room.prototype._revertRedactionLocalEcho = function(redactionEvent) {
 * this function will be ignored entirely, preserving the existing event in the
 * timeline. Events are identical based on their event ID <b>only</b>.
 *
+ * @param {boolean} fromCache whether the sync response came from cache
 * @throws If <code>duplicateStrategy</code> is not falsey, 'replace' or 'ignore'.
 */
-Room.prototype.addLiveEvents = function(events, duplicateStrategy) {
+Room.prototype.addLiveEvents = function(events, duplicateStrategy, fromCache) {
    let i;
    if (duplicateStrategy && ["replace", "ignore"].indexOf(duplicateStrategy) === -1) {
        throw new Error("duplicateStrategy MUST be either 'replace' or 'ignore'");
@@ -1455,7 +1469,7 @@ Room.prototype.addLiveEvents = function(events, duplicateStrategy) {
    for (i = 0; i < events.length; i++) {
        // TODO: We should have a filter to say "only add state event
        // types X Y Z to the timeline".
-        this._addLiveEvent(events[i], duplicateStrategy);
+        this._addLiveEvent(events[i], duplicateStrategy, fromCache);
    }
 };

@@ -1819,7 +1833,7 @@ function calculateRoomName(room, userId, ignoreRoomNameEvent) {
    let alias = room.getCanonicalAlias();

    if (!alias) {
-        const aliases = room.getAliases();
+        const aliases = room.getAltAliases();

        if (aliases.length) {
            alias = aliases[0];
@@ -388,8 +388,10 @@ SyncApi.prototype._peekPoll = function(peekRoom, token) {
        });

        // strip out events which aren't for the given room_id (e.g presence)
+        // and also ephemeral events (which we're assuming is anything without
+        // and event ID because the /events API doesn't separate them).
        const events = res.chunk.filter(function(e) {
-            return e.room_id === peekRoom.roomId;
+            return e.room_id === peekRoom.roomId && e.event_id;
        }).map(self.client.getEventMapper());

        peekRoom.addLiveEvents(events);
@@ -688,6 +690,7 @@ SyncApi.prototype._syncFromCache = async function(savedSync) {
        oldSyncToken: null,
        nextSyncToken,
        catchingUp: false,
+        fromCache: true,
    };

    const data = {
@@ -1237,7 +1240,8 @@ SyncApi.prototype._processSyncResponse = async function(
            }
        }

-        self._processRoomEvents(room, stateEvents, timelineEvents);
+        self._processRoomEvents(room, stateEvents,
+            timelineEvents, syncEventData.fromCache);

        // set summary after processing events,
        // because it will trigger a name calculation
@@ -1564,10 +1568,11 @@ SyncApi.prototype._resolveInvites = function(room) {
 * @param {MatrixEvent[]} stateEventList A list of state events. This is the state
 * at the *START* of the timeline list if it is supplied.
 * @param {MatrixEvent[]} [timelineEventList] A list of timeline events. Lower index
+ * @param {boolean} fromCache whether the sync response came from cache
 * is earlier in time. Higher index is later.
 */
 SyncApi.prototype._processRoomEvents = function(room, stateEventList,
-                                                timelineEventList) {
+                                                timelineEventList, fromCache) {
    // If there are no events in the timeline yet, initialise it with
    // the given state events
    const liveTimeline = room.getLiveTimeline();
@@ -1621,7 +1626,7 @@ SyncApi.prototype._processRoomEvents = function(room, stateEventList,
    // if the timeline has any state events in it.
    // This also needs to be done before running push rules on the events as they need
    // to be decorated with sender etc.
-    room.addLiveEvents(timelineEventList || []);
+    room.addLiveEvents(timelineEventList || [], null, fromCache);
 };

 /**
@@ -89,7 +89,7 @@ export function TimelineWindow(client, timelineSet, opts) {
 *    given event
 * @param {number} [initialWindowSize = 20]   Size of the initial window
 *
- * @return {module:client.Promise}
+ * @return {Promise}
 */
 TimelineWindow.prototype.load = function(initialEventId, initialWindowSize) {
    const self = this;
@@ -147,6 +147,62 @@ TimelineWindow.prototype.load = function(initialEventId, initialWindowSize) {
    }
 };

+/**
+ * Get the TimelineIndex of the window in the given direction.
+ *
+ * @param {string} direction   EventTimeline.BACKWARDS to get the TimelineIndex
+ * at the start of the window; EventTimeline.FORWARDS to get the TimelineIndex at
+ * the end.
+ *
+ * @return {TimelineIndex} The requested timeline index if one exists, null
+ * otherwise.
+ */
+TimelineWindow.prototype.getTimelineIndex = function(direction) {
+    if (direction == EventTimeline.BACKWARDS) {
+        return this._start;
+    } else if (direction == EventTimeline.FORWARDS) {
+        return this._end;
+    } else {
+        throw new Error("Invalid direction '" + direction + "'");
+    }
+};
+
+/**
+ * Try to extend the window using events that are already in the underlying
+ * TimelineIndex.
+ *
+ * @param {string} direction   EventTimeline.BACKWARDS to try extending it
+ *   backwards; EventTimeline.FORWARDS to try extending it forwards.
+ * @param {number} size   number of events to try to extend by.
+ *
+ * @return {boolean} true if the window was extended, false otherwise.
+ */
+TimelineWindow.prototype.extend = function(direction, size) {
+    const tl = this.getTimelineIndex(direction);
+
+    if (!tl) {
+        debuglog("TimelineWindow: no timeline yet");
+        return false;
+    }
+
+    const count = (direction == EventTimeline.BACKWARDS) ?
+        tl.retreat(size) : tl.advance(size);
+
+    if (count) {
+        this._eventCount += count;
+        debuglog("TimelineWindow: increased cap by " + count +
+                 " (now " + this._eventCount + ")");
+        // remove some events from the other end, if necessary
+        const excess = this._eventCount - this._windowLimit;
+        if (excess > 0) {
+            this.unpaginate(excess, direction != EventTimeline.BACKWARDS);
+        }
+        return true;
+    }
+
+    return false;
+};
+
 /**
 * Check if this window can be extended
 *
@@ -161,14 +217,7 @@ TimelineWindow.prototype.load = function(initialEventId, initialWindowSize) {
 * @return {boolean} true if we can paginate in the given direction
 */
 TimelineWindow.prototype.canPaginate = function(direction) {
-    let tl;
-    if (direction == EventTimeline.BACKWARDS) {
-        tl = this._start;
-    } else if (direction == EventTimeline.FORWARDS) {
-        tl = this._end;
-    } else {
-        throw new Error("Invalid direction '" + direction + "'");
-    }
+    const tl = this.getTimelineIndex(direction);

    if (!tl) {
        debuglog("TimelineWindow: no timeline yet");
@@ -208,7 +257,7 @@ TimelineWindow.prototype.canPaginate = function(direction) {
 * @param {number} [requestLimit = 5] limit for the number of API requests we
 *    should make.
 *
- * @return {module:client.Promise} Resolves to a boolean which is true if more events
+ * @return {Promise} Resolves to a boolean which is true if more events
 *    were successfully retrieved.
 */
 TimelineWindow.prototype.paginate = function(direction, size, makeRequest,
@@ -224,14 +273,7 @@ TimelineWindow.prototype.paginate = function(direction, size, makeRequest,
        requestLimit = DEFAULT_PAGINATE_LOOP_LIMIT;
    }

-    let tl;
-    if (direction == EventTimeline.BACKWARDS) {
-        tl = this._start;
-    } else if (direction == EventTimeline.FORWARDS) {
-        tl = this._end;
-    } else {
-        throw new Error("Invalid direction '" + direction + "'");
-    }
+    const tl = this.getTimelineIndex(direction);

    if (!tl) {
        debuglog("TimelineWindow: no timeline yet");
@@ -243,18 +285,7 @@ TimelineWindow.prototype.paginate = function(direction, size, makeRequest,
    }

    // try moving the cap
-    const count = (direction == EventTimeline.BACKWARDS) ?
-        tl.retreat(size) : tl.advance(size);
-
-    if (count) {
-        this._eventCount += count;
-        debuglog("TimelineWindow: increased cap by " + count +
-                 " (now " + this._eventCount + ")");
-        // remove some events from the other end, if necessary
-        const excess = this._eventCount - this._windowLimit;
-        if (excess > 0) {
-            this.unpaginate(excess, direction != EventTimeline.BACKWARDS);
-        }
+    if (this.extend(direction, size)) {
        return Promise.resolve(true);
    }

@@ -490,4 +521,3 @@ TimelineIndex.prototype.advance = function(delta) {
 TimelineIndex.prototype.retreat = function(delta) {
    return this.advance(delta * -1) * -1;
 };
-
@@ -28,7 +28,7 @@ import unhomoglyph from 'unhomoglyph';
 * {"foo": "bar", "baz": "taz"}
 * @return {string} The encoded string e.g. foo=bar&baz=taz
 */
-export function encodeParams(params) {
+export function encodeParams(params: Record<string, string>): string {
    let qs = "";
    for (const key in params) {
        if (!params.hasOwnProperty(key)) {
@@ -48,7 +48,8 @@ export function encodeParams(params) {
 * variables with. E.g. { "$bar": "baz" }.
 * @return {string} The result of replacing all template variables e.g. '/foo/baz'.
 */
-export function encodeUri(pathTemplate, variables) {
+export function encodeUri(pathTemplate: string,
+                          variables: Record<string, string>): string {
    for (const key in variables) {
        if (!variables.hasOwnProperty(key)) {
            continue;
@@ -67,7 +68,7 @@ export function encodeUri(pathTemplate, variables) {
 * the array with the signature <code>fn(element){...}</code>
 * @return {Array} A new array with the results of the function.
 */
-export function map(array, fn) {
+export function map<T, S>(array: T[], fn: (t: T) => S): S[] {
    const results = new Array(array.length);
    for (let i = 0; i < array.length; i++) {
        results[i] = fn(array[i]);
@@ -83,8 +84,9 @@ export function map(array, fn) {
 * looks like <code>fn(element, index, array){...}</code>.
 * @return {Array} A new array with the results of the function.
 */
-export function filter(array, fn) {
-    const results = [];
+export function filter<T>(array: T[],
+                          fn: (t: T, i?: number, a?: T[]) => boolean): T[] {
+    const results: T[] = [];
    for (let i = 0; i < array.length; i++) {
        if (fn(array[i], i, array)) {
            results.push(array[i]);
@@ -98,15 +100,15 @@ export function filter(array, fn) {
 * @param {Object} obj The object to get the keys for.
 * @return {string[]} The keys of the object.
 */
-export function keys(obj) {
-    const keys = [];
+export function keys(obj: object): string[] {
+    const result = [];
    for (const key in obj) {
        if (!obj.hasOwnProperty(key)) {
            continue;
        }
-        keys.push(key);
+        result.push(key);
    }
-    return keys;
+    return result;
 }

 /**
@@ -114,15 +116,15 @@ export function keys(obj) {
 * @param {Object} obj The object to get the values for.
 * @return {Array<*>} The values of the object.
 */
-export function values(obj) {
-    const values = [];
+export function values<T>(obj: Record<string, T>): T[] {
+    const result = [];
    for (const key in obj) {
        if (!obj.hasOwnProperty(key)) {
            continue;
        }
-        values.push(obj[key]);
+        result.push(obj[key]);
    }
-    return values;
+    return result;
 }

 /**
@@ -131,7 +133,7 @@ export function values(obj) {
 * @param {Function} fn The function to invoke for each element. Has the
 * function signature <code>fn(element, index)</code>.
 */
-export function forEach(array, fn) {
+export function forEach<T>(array: T[], fn: (t: T, i: number) => void) {
    for (let i = 0; i < array.length; i++) {
        fn(array[i], i);
    }
@@ -148,7 +150,11 @@ export function forEach(array, fn) {
 * @return {*} The first value in the array which returns <code>true</code> for
 * the given function.
 */
-export function findElement(array, fn, reverse) {
+export function findElement<T>(
+        array: T[],
+        fn: (t: T, i?: number, a?: T[]) => boolean,
+        reverse?: boolean
+    ) {
    let i;
    if (reverse) {
        for (i = array.length - 1; i >= 0; i--) {
@@ -175,7 +181,11 @@ export function findElement(array, fn, reverse) {
 * @param {boolean} reverse True to search in reverse order.
 * @return {boolean} True if an element was removed.
 */
-export function removeElement(array, fn, reverse) {
+export function removeElement<T>(
+        array: T[],
+        fn: (t: T, i?: number, a?: T[]) => boolean,
+        reverse?: boolean
+    ) {
    let i;
    let removed;
    if (reverse) {
@@ -203,8 +213,8 @@ export function removeElement(array, fn, reverse) {
 * @param {*} value The thing to check.
 * @return {boolean} True if it is a function.
 */
-export function isFunction(value) {
-    return Object.prototype.toString.call(value) == "[object Function]";
+export function isFunction(value: any) {
+    return Object.prototype.toString.call(value) === "[object Function]";
 }

 /**
@@ -212,7 +222,7 @@ export function isFunction(value) {
 * @param {*} value The thing to check.
 * @return {boolean} True if it is an array.
 */
-export function isArray(value) {
+export function isArray(value: any) {
    return Array.isArray ? Array.isArray(value) :
        Boolean(value && value.constructor === Array);
 }
@@ -223,10 +233,11 @@ export function isArray(value) {
 * @param {string[]} keys The list of keys that 'obj' must have.
 * @throws If the object is missing keys.
 */
-export function checkObjectHasKeys(obj, keys) {
-    for (let i = 0; i < keys.length; i++) {
-        if (!obj.hasOwnProperty(keys[i])) {
-            throw new Error("Missing required key: " + keys[i]);
+// note using 'keys' here would shadow the 'keys' function defined above
+export function checkObjectHasKeys(obj: object, keys_: string[]) {
+    for (let i = 0; i < keys_.length; i++) {
+        if (!obj.hasOwnProperty(keys_[i])) {
+            throw new Error("Missing required key: " + keys_[i]);
        }
    }
 }
@@ -237,7 +248,7 @@ export function checkObjectHasKeys(obj, keys) {
 * @param {string[]} allowedKeys The list of allowed key names.
 * @throws If there are extra keys.
 */
-export function checkObjectHasNoAdditionalKeys(obj, allowedKeys) {
+export function checkObjectHasNoAdditionalKeys(obj: object, allowedKeys: string[]): void {
    for (const key in obj) {
        if (!obj.hasOwnProperty(key)) {
            continue;
@@ -254,7 +265,7 @@ export function checkObjectHasNoAdditionalKeys(obj, allowedKeys) {
 * @param {Object} obj The object to deep copy.
 * @return {Object} A copy of the object without any references to the original.
 */
-export function deepCopy(obj) {
+export function deepCopy(obj: object): object {
    return JSON.parse(JSON.stringify(obj));
 }

@@ -266,7 +277,7 @@ export function deepCopy(obj) {
 *
 * @return {boolean} true if the two objects are equal
 */
-export function deepCompare(x, y) {
+export function deepCompare(x: any, y: any): boolean {
    // Inspired by
    // http://stackoverflow.com/questions/1068834/object-comparison-in-javascript#1144249

@@ -377,7 +388,7 @@ export function runPolyfills() {
    // SOURCE:
    // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter
    if (!Array.prototype.filter) {
-      Array.prototype.filter = function(fun/*, thisArg*/) {
+      Array.prototype.filter = function(fun: Function/*, thisArg*/) {
        if (this === void 0 || this === null) {
          throw new TypeError();
        }
@@ -453,7 +464,7 @@ export function runPolyfills() {

        // 8. Repeat, while k < len
        while (k < len) {
-          var kValue, mappedValue;
+          let kValue, mappedValue;

          // a. Let Pk be ToString(k).
          //   This is implicit for LHS operands of the in operator
@@ -538,7 +549,7 @@ export function runPolyfills() {

        // 7. Repeat, while k < len
        while (k < len) {
-          var kValue;
+          let kValue;

          // a. Let Pk be ToString(k).
          //   This is implicit for LHS operands of the in operator
@@ -572,7 +583,7 @@ export function runPolyfills() {
 *     prototype.
 * @param {function} superCtor Constructor function to inherit prototype from.
 */
-export function inherits(ctor, superCtor) {
+export function inherits(ctor: Function, superCtor: Function) {
    // Add util.inherits from Node.js
    // Source:
    // https://github.com/joyent/node/blob/master/lib/util.js
@@ -596,7 +607,7 @@ export function inherits(ctor, superCtor) {
    // DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
    // OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
    // USE OR OTHER DEALINGS IN THE SOFTWARE.
-    ctor.super_ = superCtor;
+    (ctor as any).super_ = superCtor;
    ctor.prototype = Object.create(superCtor.prototype, {
        constructor: {
            value: ctor,
@@ -617,7 +628,7 @@ export function inherits(ctor, superCtor) {
 * @param {any} SuperType The type to act as a super instance
 * @param {any} params Arguments to supply to the super type's constructor
 */
-export function polyfillSuper(thisArg, SuperType, ...params) {
+export function polyfillSuper(thisArg: any, SuperType: any, ...params: any[]) {
    try {
        SuperType.call(thisArg, ...params);
    } catch (e) {
@@ -633,7 +644,7 @@ export function polyfillSuper(thisArg, SuperType, ...params) {
 * @param {*} value the value to test
 * @return {boolean} whether or not value is a finite number without type-coercion
 */
-export function isNumber(value) {
+export function isNumber(value: any): boolean {
    return typeof value === 'number' && isFinite(value);
 }

@@ -643,7 +654,7 @@ export function isNumber(value) {
 * @param {string} str the string to remove hidden characters from
 * @return {string} a string with the hidden characters removed
 */
-export function removeHiddenChars(str) {
+export function removeHiddenChars(str: string): string {
    return unhomoglyph(str.normalize('NFD').replace(removeHiddenCharsRegex, ''));
 }

@@ -656,11 +667,11 @@ export function removeHiddenChars(str) {
 // Zero width no-break space (BOM) U+FEFF
 const removeHiddenCharsRegex = /[\u2000-\u200F\u202A-\u202F\u0300-\u036f\uFEFF\s]/g;

-export function escapeRegExp(string) {
+export function escapeRegExp(string: string): string {
    return string.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }

-export function globToRegexp(glob, extended) {
+export function globToRegexp(glob: string, extended: any): string {
    extended = typeof(extended) === 'boolean' ? extended : true;
    // From
    // https://github.com/matrix-org/synapse/blob/abbee6b29be80a77e05730707602f3bbfc3f38cb/synapse/push/__init__.py#L132
@@ -679,7 +690,7 @@ export function globToRegexp(glob, extended) {
    return pat;
 }

-export function ensureNoTrailingSlash(url) {
+export function ensureNoTrailingSlash(url: string): string {
    if (url && url.endsWith("/")) {
        return url.substr(0, url.length - 1);
    } else {
@@ -688,13 +699,13 @@ export function ensureNoTrailingSlash(url) {
 }

 // Returns a promise which resolves with a given value after the given number of ms
-export function sleep(ms, value) {
+export function sleep<T>(ms: number, value: T): Promise<T> {
    return new Promise((resolve => {
        setTimeout(resolve, ms, value);
    }));
 }

-export function isNullOrUndefined(val) {
+export function isNullOrUndefined(val: any): boolean {
    return val === null || val === undefined;
 }

@@ -711,12 +722,15 @@ export function defer() {
    return {resolve, reject, promise};
 }

-export async function promiseMapSeries(promises, fn) {
+export async function promiseMapSeries<T>(
+        promises: Promise<T>[],
+        fn: (t: T) => void
+    ): Promise<void> {
    for (const o of await promises) {
        await fn(await o);
    }
 }

-export function promiseTry(fn) {
+export function promiseTry<T>(fn: () => T): Promise<T> {
    return new Promise((resolve) => resolve(fn()));
 }